Claude Code MCP: add, configure and manage servers

To connect Claude Code to an MCP server, run claude mcp add with a transport, a name and the server’s URL or launch command, then check it with claude mcp list or /mcp inside a session. Claude Code MCP servers can be stored per project, per user or in a shared .mcp.json.

claude mcp add --transport http notion https://mcp.notion.com/mcp

Applies to: Claude Code 2.1.287 (changelog), docs as of October 2, 2026. Last checked: October 2, 2026.

On this page

What MCP gives Claude Code

The Model Context Protocol is an open standard that lets Claude Code call tools, databases and APIs in other systems. Anthropic’s MCP reference suggests connecting a server when you keep copying data into the chat from another tool, such as an issue tracker or a monitoring dashboard, so Claude can read and act on that system directly.

Warning

Anthropic’s docs say to verify you trust each server before connecting it: servers that fetch external content can expose you to prompt injection. Anthropic reviews connectors for its Directory but doesn’t security-audit or manage any MCP server.

How do I add an MCP server with claude mcp add?

The command shape depends on the transport. The MCP reference documents four.

Remote HTTP server

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

In JSON configs, type also accepts streamable-http as an alias for http. An entry with a url but no type is read as stdio and skipped with an error asking you to add "type": "http" (source).

Remote SSE server

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Local stdio server

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

The -- separates Claude Code’s own options (--transport, --env, --scope) from the server command. Everything after it is passed to the server untouched; without it, Claude Code tries to parse the server’s flags such as --port as its own (source). The docs also note that --env accepts several KEY=value pairs, so put at least one other option between --env and the server name or the CLI reads the name as another pair.

Claude Code sets CLAUDE_PROJECT_DIR in the stdio server’s environment to the project root, so the server can resolve project-relative paths.

WebSocket server

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

Flags you will use most

From the MCP reference tips:

Server names added through claude mcp can contain only letters, numbers, hyphens and underscores, and the names workspace, claude-in-chrome, computer-use, Claude Preview and Claude Browser are reserved for built-in servers (source).

Which scope should I use: local, project or user?

The --scope flag decides where the config is written and who gets it (MCP installation scopes).

# Add a project-scoped server
claude mcp add --transport http shared-server --scope project https://example.com/mcp

That command writes this .mcp.json, which you commit so the team gets the same servers:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

When one server name exists in several places, Claude Code uses the whole entry from the highest-precedence source, without merging fields: local, then project, then user, then plugin-provided servers, then claude.ai connectors.

In interactive sessions, Claude Code asks for approval before using project-scoped servers from .mcp.json; claude mcp reset-project-choices resets those choices. The docs point out that claude -p runs, Agent SDK sessions and cloud sessions can’t show that prompt and load project servers without asking. Use disabledMcpjsonServers to keep a server out in every mode (source). As of v2.1.196, a cloned repository can’t approve its own servers through a committed .claude/settings.json until you accept the workspace trust dialog.

Environment variables in .mcp.json

.mcp.json expands ${VAR} and ${VAR:-default} in command, args, env, url and headers, so a shared file can keep secrets out of version control (source):

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

If a variable is unset and has no default, the config still loads, claude mcp list shows a warning, and the literal ${VAR} text is used.

How do I list, inspect and remove servers?

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get notion

# Remove a server
claude mcp remove notion

# (within Claude Code) Check server status
/mcp

claude mcp list shows a status per server, such as ✔ Connected, ! Needs authentication or ✘ Failed to connect; a failure there means Claude Code couldn’t reach that server, not that the command failed. Project servers waiting for approval show ⏸ Pending approval. WebSocket servers don’t appear in claude mcp list; check them with claude mcp get or /mcp (server status).

To switch a server off without deleting its config, toggle it in the /mcp panel. Claude Code records that per project in ~/.claude.json under disabledMcpServers (source).

How does OAuth work for remote servers?

Many remote servers use OAuth 2.0. Add the server without a credential, then sign in from /mcp (authentication):

1. Add the server:

   claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
   

2. In a Claude Code session, run /mcp and follow the browser sign-in.

3. Check that the server shows connected in the /mcp menu.

Tokens are stored and refreshed automatically; “Clear authentication” in /mcp revokes access. From v2.1.186 you can run the flow from the shell instead, and --no-browser prints the authorization URL for SSH sessions:

claude mcp login sentry

claude mcp login sentry --no-browser

claude mcp logout <name> clears stored credentials.

Servers without dynamic client registration

If you see “Incompatible auth server: does not support dynamic client registration”, register an OAuth app with the server and pass its credentials. --client-secret prompts with masked input, and the secret goes to the system keychain (macOS) or a credentials file, not your config:

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

The same section documents oauth.scopes to pin requested scopes, oauth.authServerMetadataUrl to override metadata discovery, and headersHelper for non-OAuth schemes such as Kerberos or short-lived tokens.

Warning

The docs state that headersHelper executes arbitrary shell commands. At project or local scope it only runs after you accept the workspace trust dialog.

Can I add a server from JSON or import from Claude Desktop?

Yes. claude mcp add-json takes a full JSON entry:

# Basic syntax
claude mcp add-json <name> '<json>'

# Example: Adding an HTTP server with JSON configuration
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

To copy servers you set up in Claude Desktop, run:

claude mcp add-from-claude-desktop

An interactive dialog lets you pick which servers to import. The docs say this works only on macOS and WSL, reads the Claude Desktop config from its standard location, accepts --scope user, and skips any server whose name contains characters other than letters, numbers, hyphens and underscores (source).

If you log in to Claude Code with a claude.ai account, connectors you added at claude.ai appear automatically in /mcp. Set "disableClaudeAiConnectors": true in settings, or ENABLE_CLAUDEAI_MCP_SERVERS=false, to turn them off (source).

How do I use MCP resources and prompts?

Resources. Type @ in a prompt to see resources from connected servers next to files, and reference one as @server:protocol://resource/path:

Can you analyze @github:issue://123 and suggest a fix?

Prompts. Servers can expose prompts that show up as slash commands in the format /mcp__servername__promptname, with arguments space-separated:

/mcp__github__pr_review 456

Both are described in the MCP reference.

Output limits, timeouts and tool search

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Sources: output limits, tool search. Server authors can raise the limit for one tool with _meta["anthropic/maxResultSizeChars"], up to 500,000 characters.

How do organizations control MCP servers?

Admins have two mechanisms, documented in Control MCP server access for your organization:

• managed-mcp.json: a fixed server set with exclusive control. Users can’t add or use any other server, including plugin servers. An empty "mcpServers": {} disables MCP entirely.
• allowedMcpServers and deniedMcpServers in managed settings: filter user-configured servers by serverUrl, serverCommand or serverName. Add allowManagedMcpServersOnly: true so users can’t broaden the allowlist. The denylist always wins.

{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ]
}

The docs warn that a serverName entry is not a security control, since users choose the name; use serverUrl or serverCommand for enforcement. Any user on the machine can read managed-mcp.json, so keep credentials out of its env blocks.

Servers the docs use as examples

Anthropic’s reference walks through Notion, Sentry (OAuth), GitHub (personal access token in a header) and Stripe. Our directory has the install commands and client support for each: GitHub MCP Server, Sentry MCP, Notion MCP and Stripe MCP. The full list is at /mcp-servers.

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

The docs note that claude mcp add saves the config without validating credentials, so a placeholder is accepted but the server fails later with an HTTP 401 shown in /mcp.