Claude Code uses Model Context Protocol (MCP) servers to work with databases, issue trackers, monitoring services, design files, and custom programs.
Local servers run as processes on your computer through stdio. Remote servers run at HTTP endpoints and can authenticate through OAuth or request headers.
A working setup requires three decisions: the server transport, the configuration scope, and the permissions granted to its tools.
The setup guide below covers both local and remote setup, connection checks with /mcp, OAuth, troubleshooting, updates, and removal.
What MCP does in Claude Code
Claude Code acts as the MCP host and opens client connections to configured servers. A server can advertise one or more capabilities for use during a session:
- Tools perform actions or retrieve data, such as querying a database, reading an issue, or creating a draft.
- Resources provide content that you can attach with an
@mention, such as a document, schema, or issue record. - Prompts provide reusable prompt templates. They appear as slash commands in the form
/mcp__servername__promptname.
Claude Code maintains each server connection, presents the available capabilities to the model, and applies permission rules before a tool runs. The model does not open a direct connection to the external service.
MCP fits tasks that require structured, repeated access to systems outside Claude Code’s built-in file and shell tools. A normal command-line program is simpler for one predictable operation.
Learn the protocol: What is Model Context Protocol? Everything You Need to Know About MCP
Choose stdio or remote HTTP
| Transport | Use it for |
|---|---|
stdio | A local executable, Node package, Python program, database bridge, or custom script that Claude Code starts as a child process |
HTTP (http or streamable-http) | A hosted endpoint or long-running service reached by URL, with OAuth or request headers when authentication is required |
Claude Code also accepts WebSocket server definitions through JSON. WebSocket is ideal for services that push events over a persistent connection.
Add a remote HTTP MCP server
Run claude mcp add in a terminal. The name is your local label for the connection. It must contain only letters, numbers, hyphens, and underscores. Use a short, recognizable name because it becomes part of each MCP tool name.
claude mcp add --transport http <name> <url>Sentry provides a remote HTTP server that authenticates through OAuth:
claude mcp add --transport http sentry https://mcp.sentry.dev/mcpAn Added message confirms only that Claude Code saved the definition. It does not verify the endpoint or credentials. Start an interactive Claude Code session, enter /mcp, select sentry, and complete the browser sign-in. The server should then report a connected status.
Some servers use a token in an HTTP header:
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer YOUR_TOKEN"Replace the placeholder only in private configuration. Never commit a real token in a project-level .mcp.json. Use OAuth, an environment variable reference, a local-scoped definition, or a credential helper supported by the service.
Add a local stdio MCP server
A stdio server runs as a child process and exchanges protocol messages through standard input and output. Claude Code launches the configured executable for the connection.
Use this command form:
claude mcp add --transport stdio <name> -- <command> [arguments]The double dash separates Claude Code options from the server command. Everything after -- goes to the child process unchanged.
This example starts DBHub through npx and connects it to PostgreSQL:
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:password@localhost:5432/analytics"Pass secrets or settings to a local process with --env:
claude mcp add --env API_KEY=YOUR_KEY --transport stdio my-server \
-- npx -y example-mcp-packageChoose local, project, or user scope
The transport controls how Claude Code connects. The scope controls where the definition applies and whether it can be shared with a repository.
| Scope | Behavior | Storage |
|---|---|---|
local | Current project and current user only; this is the default | Current project’s entry inside ~/.claude.json |
project | Current project; shared through version control | .mcp.json in the project root |
user | Every project for the current user | ~/.claude.json |
Use local scope for experiments, private credentials, and services tied to one repository. You can state it explicitly:
claude mcp add --scope local --transport http my-api https://api.example.com/mcpUse project scope when everyone working in a repository should receive the same server definition. This command creates or updates .mcp.json. Each developer reviews and approves the server locally. A repository cannot preapprove its own MCP server before the user trusts the workspace.
claude mcp add --scope project --transport http shared-api https://api.example.com/mcpUse user scope for a small set of personal services needed across unrelated projects:
claude mcp add --scope user --transport http my-service https://mcp.example.com/mcpMCP local scope does not use .claude/settings.local.json. Local and user MCP definitions both live in ~/.claude.json, while local entries are stored under the current project’s path.
When the same server name appears in several scopes, Claude Code selects one complete definition rather than merging fields. Precedence runs from local to project, user, plugin-provided server, and then a matching claude.ai connector. A stale local entry can therefore hide an updated project entry with the same name.
Configure MCP servers with JSON
Project scope uses an .mcp.json file with a top-level mcpServers object. A shareable HTTP entry can reference environment variables for its URL and headers:
{
"mcpServers": {
"company-api": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_TOKEN}"
}
}
}
}Each machine must set ${API_TOKEN} before starting Claude Code. ${API_BASE_URL:-https://api.example.com} supplies a default URL when the variable is missing. Claude Code expands variables in command, args, env, url, and headers. If a required variable has no value or default, claude mcp list reports a warning and leaves the placeholder unexpanded.
A stdio entry names the executable and its arguments separately:
{
"mcpServers": {
"local-service": {
"type": "stdio",
"command": "node",
"args": ["./tools/mcp-server.js"],
"env": {
"SERVICE_TOKEN": "${SERVICE_TOKEN}"
}
}
}
}Include "type": "http" when an entry has a url. A missing type makes Claude Code interpret the entry as stdio, which leads to a configuration error.
You can also add one JSON definition from the terminal:
claude mcp add-json weather-api \
'{"type":"http","url":"https://api.example.com/mcp"}'Shell quoting differs across PowerShell, Command Prompt, Bash, and Zsh. Edit .mcp.json directly when a definition is long or deeply nested, then validate the JSON before starting Claude Code.
Use /mcp and complete OAuth
Enter /mcp in an interactive Claude Code session to open the MCP manager. It shows each connection, its source, status, available capabilities, and authentication state. From this panel, you can disable a server for the current project, reconnect a failed connection, start OAuth, re-authenticate, or clear stored credentials.
The shell commands provide a second view:
claude mcp list
claude mcp get sentry
claude mcp login sentry
claude mcp logout sentryclaude mcp list reads saved definitions and checks eligible server connections. Common states include Connected, Needs authentication, Failed to connect, and Pending approval. claude mcp get <name> shows the selected definition and its scope.
OAuth works with HTTP servers. When an eligible server returns 401 Unauthorized or 403 Forbidden, Claude Code can mark it as needing authentication. Start the flow from /mcp or run claude mcp login <name>.
If a browser does not open, copy the displayed authorization URL into a browser. For SSH sessions or systems without a local browser, use:
claude mcp login sentry --no-browserAfter signing in, paste the full redirect URL from the browser’s address bar back into Claude Code. An SSH session needs an interactive terminal, such as one opened with ssh -t.
If authentication succeeds in the browser but the localhost callback fails, paste the full callback URL into Claude Code’s URL prompt. When a provider requires a pre-registered redirect URI, pass the matching --callback-port while adding the server. Add --client-id and --client-secret only when the authorization server requires pre-configured OAuth credentials.
Control permissions and protect credentials
MCP setup involves three separate security decisions. Workspace trust controls whether project-supplied configuration can take effect. Project-server approval controls whether an entry from .mcp.json can connect. Tool permissions control whether Claude Code can call a capability after the connection exists.
MCP tools use names such as mcp__github__search_repositories or mcp__db__query. Open /permissions to inspect allow, ask, and deny rules. Claude Code checks deny rules first, then ask rules, then allow rules.
This settings example preapproves selected read operations from one server and requires confirmation for its write operations:
{
"permissions": {
"allow": [
"mcp__github__get_*"
],
"ask": [
"mcp__github__create_*",
"mcp__github__update_*"
]
}
}An allow wildcard must begin with a literal server prefix such as mcp__github__*. Claude Code skips an unanchored allow rule such as mcp__* and reports a warning. Deny and ask rules accept broader patterns, including mcp__* when an administrator needs to block or review every MCP tool.
Review the actual tool list in /mcp before granting a server-wide allow rule. A server can combine harmless read functions with actions that publish content, change infrastructure, spend money, or delete data.
Treat local stdio packages as executable software. Check the publisher, repository, package name, release history, and installation command. A project-level stdio entry can run a command after you trust the workspace and approve the server. Review remote servers as well because they receive task context and can return untrusted content. Issues, web pages, documents, and logs can contain prompt-injection instructions.
Keep secrets outside committed configuration. Use OAuth, environment expansion, a system credential store, or a private local definition. Limit API tokens to the repositories, workspaces, and operations the server actually needs.
Verify, disable, update, and remove a server
Run these checks after setup:
claude mcp list
claude mcp get <name>Then open Claude Code and run /mcp. A connected status confirms that the process or endpoint responded. Inspect the advertised capabilities and try one low-risk read operation before approving write access.
To stop a connection without deleting its definition, disable it in /mcp. Claude Code records the choice for the current project, and you can enable the server again from the same panel.
Claude Code has no general claude mcp update command. To change a local or user definition, remove it from the correct scope and add it again with the new URL, command, headers, or environment settings:
claude mcp remove my-server --scope user
claude mcp add --scope user --transport http my-server https://new.example.com/mcpFor a project-scoped server, update .mcp.json, review the diff, and test the connection. Teammates may need to review and approve the changed definition on their machines. Use this command to clear prior approvals and rejections for project entries:
claude mcp reset-project-choicesTo delete a server, run claude mcp remove <name>. Add --scope local, --scope project, or --scope user when the name appears in more than one scope or when you want to target one definition precisely.
Common Claude Code MCP errors
| Symptom | Likely cause | Fix |
|---|---|---|
A URL entry reports that type is missing | Claude Code reads an entry without type as stdio | Add "type": "http" or "type": "streamable-http" |
command: expected string, received undefined | An older Claude Code version found a URL entry with no HTTP type, or the wrong transport was selected | Add the type and update Claude Code if the old message persists |
spawn ... ENOENT | The stdio executable is missing or absent from Claude Code’s PATH | Install it, use the full executable path, or add the required Windows command wrapper |
| Server arguments cause an unknown option error | The stdio command lacks the -- separator | Put all Claude options before the name and the server command after -- |
A variable appears literally as ${API_TOKEN} | The variable is unset and has no default, or the configuration uses unsupported syntax | Set it before starting Claude Code and use ${VAR} or ${VAR:-default} |
Needs authentication, 401, or 403 | OAuth is incomplete, a token expired, or a static header is invalid | Use /mcp or claude mcp login; remove a rejected static header if the server expects OAuth |
| OAuth succeeds in the browser but the callback fails | Claude Code runs over SSH, inside a container, or behind a firewall that blocks localhost | Paste the full callback URL into Claude Code or use --no-browser and an interactive terminal |
.mcp.json shows Pending approval | The workspace is untrusted or this server has not been approved locally | Start Claude Code in the repository, accept workspace trust, and review the server |
claude mcp get shows Rejected | The server appears in disabledMcpjsonServers or was rejected earlier | Review the setting or run claude mcp reset-project-choices, then approve the entry |
| An edited definition does not take effect | A same-name local entry has higher precedence, or the wrong scope was edited | Run claude mcp get <name>, identify its scope, and remove or rename the higher-priority entry |
| A remote connection times out | The endpoint is unreachable, blocked by a proxy, or slow to respond | Check the URL, proxy, and network path; inspect /mcp and server logs before changing MCP_TIMEOUT or a per-server timeout |
| A stdio server disconnects after startup | The process crashed, wrote invalid protocol output to stdout, or lacks an environment variable | Run the command directly, inspect stderr, and keep diagnostic logging off protocol stdout |
Where to find MCP servers
The Anthropic Directory lists reviewed remote connectors that use the same MCP infrastructure as Claude Code. The Official MCP Registry publishes standardized metadata for public servers and verifies publisher namespaces.
For a shorter list organized around =web development tasks, see 10 Best MCP Servers for Web Developers in 2026.
FAQs
Does adding an MCP server grant access to every tool automatically?
No. Adding and connecting a server makes its capabilities available, while Claude Code’s permission system still decides whether a tool call can run. Check /permissions and approve the narrowest practical set of tools.
Can a shared .mcp.json support different paths on each computer?
Yes. Use environment variables in command, args, or env, and let each developer set the machine-specific value. Add a default with ${VAR:-default} only when that fallback is safe on every supported system.
Why does /mcp show a connected server with zero tools?
An MCP server can expose resources or prompts without exposing tools. If its documentation promises tools, confirm the installed server version, inspect its logs, and check whether authentication or configuration limits the advertised capabilities.
Can claude -p complete an MCP OAuth login?
No. Non-interactive mode has no /mcp panel and cannot complete the browser flow. Authenticate first in an interactive session or run claude mcp login <name> from an interactive terminal.
What should I do when an MCP server disconnects?
Open /mcp and reconnect the server after checking its status. For a stdio server, run the configured command directly to expose startup errors, missing variables, or invalid stdout output. Correct the underlying error, then reconnect or start a new Claude Code session.
