连接 MCP

MCP 的价值不是“把所有工具都接进 Claude”，而是把你反复复制粘贴的外部上下文，变成可治理、可认证、可撤销、可限权的工具连接。——翔宇

1. MCP 解决的是“上下文搬运”问题

不用 MCP 时，你通常这样工作：

1. 打开 Jira / Linear / GitHub issue。
2. 复制需求。
3. 打开 Sentry / 日志 / 数据库。
4. 复制报错、schema、查询结果。
5. 粘给 Claude。
6. Claude 根据这段静态信息做事。

MCP 让 Claude Code 直接连接这些系统。官方例子包括：

• 从 issue tracker 读取需求并实现功能。
• 查 Sentry / Statsig 分析线上错误和使用数据。
• 查询 PostgreSQL 数据库。
• 根据 Figma / Slack 里的设计更新模板。
• 创建 Gmail 草稿或自动化业务流程。
• 通过 channel 接收外部事件，让 Claude 对 CI、监控或聊天消息做反应。

2. 什么时候不该接 MCP

这些场景不要急着接：

• 只是偶尔查一次资料。
• 复制一小段上下文就能完成。
• MCP server 来源不可信。
• server 会读取不可信网页、issue 评论、用户输入，但没有 prompt injection 防护。
• server 能访问生产数据，却没有只读账号或最小权限。
• server 有写操作，但没有审批、权限和回滚。
• 工具一次返回海量日志、schema 或搜索结果。
• 你还没配置好 Claude Code permissions。

官方提醒很明确：第三方 MCP server 未必经过 Anthropic 验证，尤其是能抓取不可信内容的 server，会带来 prompt injection 风险。

3. MCP 三种 transport 怎么选

Claude Code 支持三类连接方式。

• HTTP：远程 MCP server 的推荐方式，适合云服务和 SaaS。
• SSE：兼容旧服务。官方当前说明 SSE transport 已废弃，能用 HTTP 就不要新接 SSE。
• stdio：本机进程。适合内部脚本、本地数据库、本机文件系统、需要直接跑命令的 server。

典型安装命令：

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

claude mcp add --transport sse asana https://mcp.asana.com/sse

claude mcp add --transport stdio airtable -- npx -y airtable-mcp-server

stdio 命令里有一个容易踩的点：Claude Code 自己的参数必须放在 server name 前面，-- 后面的内容才是传给 MCP server 的命令和参数。

claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080

4. Windows 上 stdio 要特别处理

官方特别提醒：native Windows 里，如果 local MCP server 用 npx，通常要加 cmd /c 包一层。

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

否则可能遇到 Connection closed，因为 Windows 不能像 Unix shell 那样直接执行 npx。

WSL 场景按 Linux 习惯处理，不等同于 native Windows。

5. 安装后怎么管理

常用命令只有几个：

claude mcp list

claude mcp get github

claude mcp remove github

会话内查看连接、认证和来源：

/mcp

远程 HTTP / SSE server 断线时，Claude Code 会自动重连并使用指数退避。stdio server 是本机进程，不会自动按远程连接逻辑重连。

6. 三种作用域：local、project、user

MCP server 有三种安装作用域。

• local：默认。只在当前项目加载，配置保存在 ~/.claude.json 的当前项目条目里，不提交。适合个人试验、本机开发 server、带个人凭据的连接。
• project：写入项目根目录 .mcp.json，设计上可以提交到 git。适合团队都需要、结构可共享、凭据不进仓库的 server。
• user：写入 ~/.claude.json，跨所有项目生效。适合个人长期使用的通用工具。

安装示例：

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

claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

7. 作用域优先级：同名只连接一次

当同一个 server 名字在多个地方出现时，Claude Code 只连接一次，并按官方优先级选择定义：

1. Local scope（本地作用域）
2. Project scope（项目作用域）
3. User scope（用户作用域）
4. Plugin-provided servers
5. Claude.ai connectors

前三层按 server name 去重。插件和 Claude.ai connectors 按 endpoint 去重。

这意味着：你在 local scope（本地作用域）临时加了一个同名 github，它会压过项目 .mcp.json 里的 github。如果排障时你发现团队配置没生效，先查本机 ~/.claude.json 里是否有同名 server。

8. .mcp.json 可以提交什么

项目级 MCP 配置会写到：

.mcp.json

一个基本结构：

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

可以提交：

• server 名称。
• transport 类型。
• 公开 URL。
• 本机命令结构。
• 环境变量名称。
• 不含密钥的默认参数。

不该提交：

• API key。
• OAuth client secret。
• 个人 token。
• 生产数据库明文 DSN。
• 个人机器绝对路径，除非用环境变量或默认值兜底。

9. .mcp.json 支持环境变量展开

官方支持两种语法：

• ${VAR}：读取环境变量。
• ${VAR:-default}：有环境变量就用，没有就用默认值。

可展开的位置包括：

• command
• args
• env
• url
• headers

示例：

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

如果必需环境变量没有设置、也没有默认值，Claude Code 会解析配置失败。

10. 项目级 server 首次使用会要求信任

Project scope 的 .mcp.json 是可以提交的，这也意味着你 clone 一个仓库时，仓库可能带着 MCP server 配置。

官方设计了安全提示：Claude Code 使用 project-scoped server 前会要求你批准。如果要重置选择，可以运行：

claude mcp reset-project-choices

这和 headersHelper 一起看尤其重要。headersHelper 可以执行 shell 命令动态生成 header；如果定义在 project 或 local scope，只有你接受 workspace trust 后才会运行。

11. OAuth：远程 MCP 的推荐认证方式

很多远程 MCP server 需要认证。Claude Code 支持 OAuth 2.0，通常流程是：

1. 添加 HTTP MCP server。
2. 在 Claude Code 里运行 /mcp。
3. 跟随浏览器登录。
4. 回到 Claude Code 查看认证状态。

示例：

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

/mcp

官方说明认证 token 会被安全存储并自动刷新。你可以在 /mcp 菜单里清除认证，必要时重新授权。

12. 固定 callback port 和预配置 OAuth 凭据

某些 MCP server 要求预先注册 redirect URI。默认情况下，Claude Code 会随机选择本地可用端口作为 OAuth callback port。你可以固定端口：

claude mcp add --transport http --callback-port 8080 my-server https://mcp.example.com/mcp

如果 server 不支持 Dynamic Client Registration，可能需要预配置 client ID / secret：

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

也可以通过环境变量提供 secret：

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

官方说明 client secret 会存到系统 keychain 或 credentials file，而不是写进配置文件。

13. OAuth metadata 和 scope 限制

企业或内部 OAuth server 可能不能走默认 discovery。Claude Code 支持在 MCP 配置里指定 authServerMetadataUrl：

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

这个 URL 必须是 https://。

如果要限制 OAuth 请求的 scope，可以在 oauth.scopes 里固定范围。官方说明 oauth.scopes 会优先于 metadata 和 server 自动发现的 scopes。不要把 scope 配到“能用就全给”，而是按最小权限给。

14. 动态 header：headersHelper

有些内部系统 token 很短，或需要每次连接动态签名。Claude Code 支持 headersHelper：

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

helper 要求：

• stdout 输出 JSON object。
• key 和 value 都是字符串。
• 运行超时是 10 秒。
• 动态 header 会覆盖同名静态 headers。
• 每次连接或重连都会重新执行，不缓存。

Claude Code 执行 helper 时会提供：

• CLAUDE_CODE_MCP_SERVER_NAME
• CLAUDE_CODE_MCP_SERVER_URL

15. MCP 权限规则怎么写

MCP server 接入后，不等于所有工具都应该自动放行。

Claude Code permissions 支持 MCP 工具规则：

• mcp__puppeteer：匹配 puppeteer server 提供的任意工具。
• mcp__puppeteer__*：也匹配该 server 的全部工具。
• mcp__puppeteer__puppeteer_navigate：只匹配具体工具。

更稳的做法是只允许明确工具：

{
  "permissions": {
    "allow": [
      "mcp__sentry__get_issue",
      "mcp__github__list_pull_requests"
    ],
    "ask": [
      "mcp__github__create_issue"
    ],
    "deny": [
      "mcp__postgres__execute_write"
    ]
  }
}

16. MCP 与 sandbox 的关系

上一章讲过：permissions 适用于 Bash、Read、Edit、WebFetch、MCP 等工具。sandbox 主要限制 Bash 及其子进程。

这意味着：

• MCP 工具调用靠 permissions 控制。
• MCP server 自己连外部 API，通常不受 Bash sandbox 直接约束。
• stdio MCP server 是本机进程，启动命令本身要当作本机程序审查。
• 远程 MCP server 的外部访问边界，主要由 server 自身权限、OAuth scope、token、网络策略和 managed policy 控制。

17. 输出大小也是安全和质量问题

MCP 工具输出太大，会带来三个问题：

• 占满上下文。
• 把无关信息带进判断。
• 让 prompt injection 内容更容易混入任务。

官方机制：

• 单个 MCP 工具输出超过 10,000 tokens 会显示警告。
• 默认最大输出限制是 25,000 tokens。
• 可以用 MAX_MCP_OUTPUT_TOKENS 调整。

export MAX_MCP_OUTPUT_TOKENS=50000
claude

如果你是 MCP server 作者，可以为特定工具声明 _meta["anthropic/maxResultSizeChars"]，最高到 500,000 characters。否则超出默认阈值的结果会落盘，并在会话里替换成文件引用。

18. Tool Search：多 MCP 不一定撑爆上下文

官方现在默认启用 MCP Tool Search。

它的作用是：启动时不把所有 MCP tool schema 全塞进上下文，而是先加载 tool names。Claude 需要时再搜索相关工具，只有真正使用的工具进入上下文。

这降低了“接几个 MCP 就占满上下文”的风险，但不代表可以无节制安装。

MCP server 作者要注意：server instructions 和 tool descriptions 会影响 Claude 何时搜索这些工具。官方说明 tool description 和 server instructions 会被截断到 2KB 左右，所以关键说明要放前面。

如果某些核心工具必须始终加载，可以设置 alwaysLoad：

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

19. MCP resources：用 @ 引用外部资源

MCP server 可以暴露 resources。Claude Code 支持在 prompt 里用 @ 引用它们。

示例：

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

Compare @postgres:schema://users with @docs:file://database/user-model

这些资源会被自动获取并作为附件加入上下文。路径可以在 @ 自动补全里模糊搜索。

20. MCP prompts 可以变成命令

MCP server 可以暴露 prompts。Claude Code 会把它们显示成 slash command，格式通常是：

/mcp__servername__promptname

例如：

/mcp__github__list_prs

/mcp__github__pr_review 456

prompt 结果会直接注入当前对话。server name 和 prompt name 会被规范化，空格通常变成下划线。

21. Plugin 和 Claude.ai connectors 也会带 MCP

MCP 不只来自你手动 claude mcp add。

插件可以打包 MCP server：

• 插件启用时，server 自动连接。
• 插件禁用或启用后，可能需要 /reload-plugins。
• plugin MCP server 会出现在 /mcp 里，并标明来源。

Claude.ai connectors 也可能出现在 Claude Code：

• 你用 Claude.ai 账号登录时，Claude.ai 中配置的 MCP server 会自动可用。
• Team / Enterprise 里通常由管理员添加 connector。
• 如果 Claude Code 本地配置了相同 endpoint，优先使用本地配置，Claude.ai connector 会被隐藏。

可以关闭 Claude.ai MCP server：

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

22. Claude Code 也可以作为 MCP server

官方支持让 Claude Code 自己作为 stdio MCP server：

claude mcp serve

这可以被 Claude Desktop 等 MCP client 调用。配置时 command 必须能找到 Claude Code 可执行文件；如果 PATH 里没有 claude，要写完整路径。

which claude

23. 组织级 MCP 管理

企业有两种集中管理方式。

第一种是 managed-mcp.json：管理员部署固定 MCP server 列表，用户不能添加、修改或使用其他 MCP server。系统路径包括：

• macOS：/Library/Application Support/ClaudeCode/managed-mcp.json
• Linux / WSL：/etc/claude-code/managed-mcp.json
• Windows：C:\Program Files\ClaudeCode\managed-mcp.json

第二种是 managed settings 里的 allowlist / denylist：

• allowedMcpServers
• deniedMcpServers

限制维度有三种：

• serverName：按 server 名称。
• serverCommand：按 stdio server 的启动命令和参数。
• serverUrl：按远程 server URL，可用 wildcard。

如果组织只允许 managed MCP，可以用 managed-only 设置 allowManagedMcpServersOnly。

24. 一个安全的接入顺序

新 MCP 不要一上来 project scope + allow all。按这个顺序：

25. 常见故障排查

连接失败：

• 运行 claude mcp get <name> 看配置。
• 会话内运行 /mcp 看连接状态。
• HTTP / SSE 检查 URL、认证、网络、OAuth。
• stdio 检查 command、args、PATH、环境变量。
• Windows + npx 检查是否需要 cmd /c。
• 增加 MCP_TIMEOUT 处理启动慢的 server。

认证失败：

• 在 /mcp 重新认证。
• 清除旧认证后重新登录。
• 检查 OAuth callback port。
• 检查 client ID / secret。
• 检查 scope 是否被限制过小。
• 检查 headersHelper 是否输出合法 JSON。

工具不出现：

• 检查 server 是否 connected。
• 检查是否被同名 local scope 覆盖。
• 检查 plugin / connector 是否被隐藏。
• 检查 managed allowlist / denylist。
• 检查 Tool Search 下工具是否需要被搜索触发。

输出太大：

• 优先让 server 分页和摘要。
• 对具体工具增加 server 侧 result size annotation。
• 必要时调整 MAX_MCP_OUTPUT_TOKENS。

26. 自检清单

学完这一章，你应该能完成这些判断：

• 我能解释 MCP 解决的是上下文搬运，不是越多工具越好。
• 我知道远程优先 HTTP，SSE 是兼容路径，stdio 是本机进程。
• 我能判断 MCP 应该放 local、project 还是 user scope。
• 我知道 local scope 会压过同名 project scope。
• 我知道 .mcp.json 可以提交结构，但不能提交密钥。
• 我知道 OAuth token、client secret、headersHelper 的安全边界。
• 我知道如何用 permissions 精确限制 MCP 工具。
• 我知道 MCP 输出过大会污染上下文。
• 我知道 Tool Search 默认降低工具 schema 的上下文占用。
• 我知道 plugin、Claude.ai connectors、managed MCP 都可能让 MCP 出现在 /mcp 里。

27. 术语速查

• MCP：Model Context Protocol，用来把外部工具、数据源和 API 接入 Claude Code。
• MCP server：提供 tools、resources、prompts 或 channels 的外部服务。
• transport：Claude Code 连接 MCP server 的方式，包括 HTTP、SSE、stdio。
• local scope：只在当前项目加载，配置保存在 ~/.claude.json。
• project scope：写入项目根目录 .mcp.json，可提交给团队。
• user scope：跨项目可用，配置保存在 ~/.claude.json。
• .mcp.json：项目级 MCP 配置文件。
• /mcp：Claude Code 会话内查看和认证 MCP server 的命令。
• headersHelper：动态生成 HTTP headers 的命令。
• MAX_MCP_OUTPUT_TOKENS：控制 MCP 工具输出 token 上限的环境变量。
• Tool Search：延迟加载 MCP tool schema 的机制。
• managed-mcp.json：组织集中下发的 MCP server 配置文件。
• allowedMcpServers：managed settings 中允许 MCP server 的策略字段。
• deniedMcpServers：managed settings 中禁止 MCP server 的策略字段。

官方来源

• Connect Claude Code to tools via MCP
• Configure permissions
• Claude Code settings
• Model Context Protocol