Claude Code MCP 完全指南：连接外部工具的官方参考

本文是对官方文档《Connect Claude Code to tools via MCP》的中文要点摘要，完整内容以原文为准。原文地址：https://code.claude.com/docs/en/mcp

什么是 MCP，能做什么

MCP（Model Context Protocol）是 Anthropic 推出的开放标准，让 Claude Code 可以连接外部工具、数据库与 API。接入后，你可以直接让 Claude：

• 从 Issue 追踪系统实现功能：「把 JIRA ENG-4521 里描述的功能实现并创建 PR」
• 分析监控数据：「查 Sentry 和 Statsig，看 ENG-4521 功能的使用情况」
• 查询数据库：「在 PostgreSQL 里找 10 个用过这个功能的用户邮箱」
• 集成设计稿：「根据 Slack 里的新 Figma 设计更新邮件模板」
• 自动化工作流：「给这 10 个用户起草 Gmail 邀请邮件」
• 响应外部事件：MCP 服务器还可作为 Channel，让 Claude 在你离开时响应 Telegram、Discord 或 Webhook 消息

快速上手：三步接入第一个服务器

官方推荐用 claude-code-docs（无需认证的托管服务器）作为入门练习：

# 1. 注册服务器
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

# 2. 检查连接状态
claude mcp list

# 3. 启动会话后即可使用
claude

claude mcp list 的状态含义：

三种安装范围（Scope）

切换范围需先删除再用 --scope 重新添加：

# 改为 user 范围（对所有项目生效）
claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

# 改为 project 范围（提交 Git 供团队使用）
claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

直接编辑 .mcp.json

project 范围的服务器也可以手动写 .mcp.json：

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

首次启动时 Claude Code 会提示确认（防止克隆的仓库自动启动进程），通过后即可连接。

两种传输类型

• HTTP：服务器托管在 URL，用 --transport http 指定，适合 Sentry、Linear、GitHub 等 SaaS 服务
• stdio：服务器作为本地子进程启动，不需要指定 transport（默认），适合需要访问本地资源的工具（如 Playwright 浏览器、本地数据库）

# 本地 stdio 服务器示例（Playwright）
claude mcp add playwright -- npx -y @playwright/mcp@latest

OAuth 认证服务器

对于 Sentry、Linear、Notion 等需要登录的托管服务：

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

添加后 claude mcp list 显示 ! Needs authentication，在会话内运行 /mcp，选中服务器 → Authenticate，浏览器打开完成授权即可。

若服务器用静态 token，则在 add 时直接附带：

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

常见故障排查

企业管控：管理员如何限制 MCP

本节内容来自官方子页《Control MCP server access for your organization》（/en/managed-mcp），MCP 主页面仅链接到该页。

管理员可通过系统级文件控制组织内哪些 MCP 服务器可以运行：

独占控制（managed-mcp.json）

在系统路径部署 managed-mcp.json（macOS：/Library/Application Support/ClaudeCode/managed-mcp.json；Linux 与 WSL：/etc/claude-code/managed-mcp.json；Windows：C:\Program Files\ClaudeCode\managed-mcp.json），Claude Code 将只加载该文件中定义的服务器，用户无法自行添加、修改或使用其他服务器（包括插件提供的服务器）。

{
  "mcpServers": {
    "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"]
    }
  }
}

部署空 mcpServers: {} 可完全禁用 MCP。

白名单 / 黑名单

通过 allowedMcpServers 和 deniedMcpServers 进行策略过滤，支持按 URL（支持 * 通配符）、命令行或服务器名称匹配：

{
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."] }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://*.untrusted.example.com/*" }
  ]
}

配合 allowManagedMcpServersOnly: true 可防止用户在自己的配置中扩展白名单。

注意：serverName 匹配不是安全控制手段，因为用户可以给任意服务器起任意名字。需要真正限制运行哪些服务器，应使用 serverUrl 或 serverCommand。

其他平台接入方式

除 CLI 外，多个平台均可配置 MCP 服务器：

• 桌面应用：通过 Connectors UI 添加
• VS Code：参见 VS Code 扩展文档
• Web 版 Claude Code：读取仓库中的 .mcp.json
• Claude.ai connectors：在 claude.ai 配置的连接器会自动同步到 CLI
• Claude Desktop：运行 claude mcp add-from-claude-desktop 可导入已有配置