MCP（模型上下文协议）

配置范围（优先级顺序）

服务器从 6 个源加载。当名称冲突时，更高优先级覆盖更低优先级。 企业范围是排他的：如果 managed-mcp.json 存在， 所有其他范围都被忽略。

项目配置示例（.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).

传输类型

连接生命周期

启动

工具调用流程

关闭

认证

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

工具暴露

命名示例

工具注解（来自 MCP 规范）

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.

权限系统

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.

用户权限规则

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

企业服务器策略（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 命令

# 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 斜杠命令

高级功能

关键常量和超时

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.

错误处理