MCP (Model Context Protocol)

Configuration scopes (priority order)

Servers are loaded from 6 sources. Higher priority overrides lower when names conflict. The enterprise scope is exclusive: if managed-mcp.json exists, all other scopes are ignored.

Project config example (.mcp.json)

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "my-api": {
      "type": "sse",
      "url": "https://example.com/mcp/sse",
      "headers": { "Authorization": "Bearer ${API_TOKEN}" }
    }
  }
}

All config fields support ${VAR} and ${VAR:-default} expansion. Servers in .mcp.json require explicit user approval before connecting (stored in enabledMcpjsonServers in settings).

Transport types

Connection lifecycle

Startup

Tool call flow

Shutdown

Authentication

"oauth": {
  "clientId": "my-app",
  "callbackPort": 8080,
  "authServerMetadataUrl": "https://auth.example.com/.well-known/..."
}

Tool exposure

Naming examples

Tool annotations (from MCP spec)

Tool descriptions are capped at 2048 characters. When output exceeds 100,000 characters, it is saved to a temp file and the model receives instructions to use the Read tool.

Permission system

All MCP tools return checkPermissions() → passthrough. This means in default mode the user is always prompted, in bypassPermissions mode they are auto-approved, and in auto mode the YOLO classifier decides.

User permission rules

{
  "permissions": {
    "allow": [
      "mcp__github__search_code",
      "mcp__slack__*"
    ],
    "deny": [
      "mcp__untrusted_server__*"
    ]
  }
}

Enterprise server policies (managed-mcp.json)

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverUrl": "https://*.company.com/*" },
    { "serverCommand": ["npx", "-y", "@company/mcp-*"] }
  ],
  "deniedMcpServers": [
    { "serverName": "untrusted" }
  ]
}

Denylist always takes precedence over allowlist.

CLI commands

# Add a stdio server (default scope: local)
claude mcp add my-server npx -y @org/mcp-server
  -s, --scope <scope>      # local, user, or project
  -e, --env KEY=VALUE      # environment variables

# Add a remote server (transport auto-detected from URL)
claude mcp add my-api https://api.example.com/mcp
  -t, --transport sse|http
  -H, --header "Key: Value"
  --client-id <id>         # OAuth client ID
  --xaa                    # Enable Cross-App Access

# Add with full JSON config
claude mcp add-json my-server '{"type":"http","url":"https://example.com/mcp"}'

# Other operations
claude mcp remove my-server [-s scope]
claude mcp list
claude mcp get my-server

/mcp slash command

Advanced features

Key constants and timeouts

MCP_TIMEOUT, MCP_TOOL_TIMEOUT, and MAX_MCP_OUTPUT_TOKENS are in the SAFE_ENV_VARS set: they can be set via managed settings without triggering a security dialog.

Error handling