Claude Code 调用外部工具实战：从零配置 MCP 服务器的完整工作流

原创。Claude Code 的 MCP 集成不是黑魔法，而是一套有明确配置规则、作用域和权限模型的工程实践，本文把官方文档里散落的细节串成一条能直接落地的工作流。

如果你用 Claude Code 写代码时，经常遇到这种场景——"帮我把这个 bug 对应的 Sentry 报错看一下"、"根据 JIRA 工单 ENG-4521 实现功能"、"查一下过去 24 小时数据库里的异常订单"——每次都要手动复制粘贴数据进聊天框，那 MCP（Model Context Protocol）就是为你准备的。

MCP 是 Anthropic 推动的开放标准，定义了 AI 应用如何与外部工具、数据库、API 通信。Claude Code 从 2024 年底开始全面支持 MCP，到 2025 年中已经能接入数百种外部服务。本文基于 Claude Code 官方文档和 MCP 协议规范，从零开始搭建一个完整的 MCP 工作流。

一、MCP 到底是什么：别把它想复杂了

1.1 协议定位

MCP 本质上是一个 JSON-RPC 2.0 的通信协议，运行在传输层之上。官方文档里把它比作"AI 应用的 USB-C 接口"——标准化、即插即用。一个 MCP 服务器暴露三类能力：

• Tools（工具）：可被 LLM 主动调用的函数，比如查询数据库、发送 Slack 消息、创建 GitHub Issue。
• Resources（资源）：只读数据源，比如文件内容、API 文档、数据库 Schema。用户用 @ 引用。
• Prompts（提示模板）：预置的交互模板，比如"/plan-vacation"这类结构化指令。

Claude Code 作为 MCP Host，会为每个接入的服务器创建一个独立的 MCP Client，维护专属连接。本地 stdio 服务器通常一对一服务，远程 HTTP 服务器则支持多客户端并发。

1.2 两种传输方式

MCP 规范定义了两种传输机制：

Claude Code 早期还支持 SSE（Server-Sent Events）传输，但官方文档已明确标注 SSE 为 deprecated，建议新项目直接用 HTTP。

1.3 生命周期与能力协商

每次连接建立时，客户端和服务器会做一次能力协商（Capability Negotiation）。客户端发送 initialize 请求，携带支持的协议版本（如 2025-06-18）和能力声明；服务器返回自身支持的能力，比如 "tools": {"listChanged": true} 表示支持工具列表变更通知。

协商成功后，客户端发送 notifications/initialized 通知，之后才能进行工具发现（tools/list）和调用（tools/call）。

二、Claude Code 的三种 MCP 接入方式

Claude Code 支持三种配置 MCP 服务器的途径，按推荐程度排序：HTTP 远程服务器、stdio 本地服务器、SSE 远程服务器（已弃用）。

2.1 HTTP 远程服务器（推荐）

HTTP 是最广泛支持的传输方式，适合连接云托管服务。基本命令格式：

# 基础语法
claude mcp add --transport http <name> <url>
 
# 实例：接入 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp
 
# 带 Bearer Token 认证
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

在 .mcp.json 中配置时，type 字段可以写 http 或 streamable-http，两者等价。MCP 规范使用 streamable-http 这个名称，Claude Code 做了兼容处理。

2.2 stdio 本地服务器

stdio 服务器以本地进程方式运行，适合需要直接系统访问的工具。命令格式有个容易踩坑的细节：所有选项必须写在服务器名之前，命令参数用 -- 分隔。

# 基础语法
claude mcp add [options] <name> -- <command> [args...]
 
# 实例：接入 Airtable
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server
 
# 带环境变量和参数
claude mcp add --transport stdio --env KEY=value myserver \
  -- python server.py --port 8080

Claude Code 会在启动服务器时设置 CLAUDE_PROJECT_DIR 环境变量，指向项目根目录。你的服务器代码里可以用 process.env.CLAUDE_PROJECT_DIR（Node）或 os.environ["CLAUDE_PROJECT_DIR"]（Python）读取。注意这个变量只在服务器进程环境里，不在 Claude Code 自身环境中，所以在 .mcp.json 的 command 或 args 里引用时，需要写默认值：${CLAUDE_PROJECT_DIR:-.}。

2.3 SSE 远程服务器（已弃用）

虽然还能用，但官方明确建议迁移到 HTTP：

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

三、配置作用域：个人用、团队用、全项目用

这是最容易被忽视但最关键的部分。Claude Code 的 MCP 配置有三层作用域，直接影响配置存储位置和共享范围：

3.1 Local 作用域（默认）

Local 是默认作用域，配置只对当前项目、当前用户生效，不会进入版本控制。适合存放个人开发用的实验性服务器或带敏感凭据的配置：

# 默认就是 local
claude mcp add --transport http stripe https://mcp.stripe.com
 
# 显式声明
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

执行后，~/.claude.json 里会多出一个按项目路径隔离的条目：

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

注意：MCP 的 local scope 和普通 local settings 不是一回事。MCP local 存在 ~/.claude.json，而普通 local settings 存在 .claude/settings.local.json。

3.2 Project 作用域（团队协作）

Project scope 把配置写进项目根目录的 .mcp.json，可以提交到 Git，确保团队所有人用同一套工具链：

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

生成的 .mcp.json 格式：

{
  "mcpServers": {
    "paypal": {
      "type": "http",
      "url": "https://mcp.paypal.com/mcp"
    }
  }
}

出于安全考虑，Claude Code 首次使用 project-scoped 服务器时会提示用户确认。如果想重置这些确认记录，运行：

claude mcp reset-project-choices

3.3 User 作用域（跨项目复用）

User scope 把配置存在 ~/.claude.json 的全局区域，当前用户的所有项目都能访问：

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

3.4 作用域优先级

同一服务器在多处定义时，Claude Code 按以下优先级取一个：

1. Local scope
2. Project scope
3. User scope
4. Plugin 自带的服务器
5. claude.ai 的 connectors

前三个按服务器名称去重，后两个按端点（URL 或命令）去重。

四、环境变量与动态配置

4.1 环境变量展开

.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 会解析失败并报错。

4.2 动态头部（headersHelper）

对于非 OAuth 的自定义认证（比如 Kerberos、短效 Token、内部 SSO），可以用 headersHelper 在连接时动态生成请求头：

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

命令要求：

• 向 stdout 输出 JSON 格式的字符串键值对
• 10 秒超时
• 每次连接都会重新执行，没有缓存
• 动态头部会覆盖同名的静态 headers

Claude Code 执行 helper 时会传入两个环境变量：CLAUDE_CODE_MCP_SERVER_NAME 和 CLAUDE_CODE_MCP_SERVER_URL，方便写一个脚本服务多个服务器。

五、认证：OAuth 2.0 与预配置凭据

远程 MCP 服务器通常需要认证。Claude Code 原生支持 OAuth 2.0，也支持固定 Token 和动态头部。

5.1 OAuth 2.0 流程

当服务器返回 401 或 403 时，Claude Code 会在 /mcp 面板里标记该服务器需要认证。用户运行 /mcp 后按提示在浏览器完成登录即可。

Token 会自动存储在系统钥匙串（macOS）或凭据文件里，并自动刷新。清除认证在 /mcp 菜单里选 "Clear authentication"。

5.2 固定回调端口

默认情况下 OAuth 回调用随机端口。如果服务器要求预注册 redirect URI，用 --callback-port 固定：

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

5.3 预配置 OAuth 凭据

有些服务器不支持动态客户端注册（Dynamic Client Registration），需要先在开发者后台注册应用，再手动提供 client ID 和 secret：

# 交互式输入 secret（会掩码）
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp
 
# 通过环境变量避免交互
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
 
# JSON 方式
claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

Client secret 不会存进配置文件，而是放在系统钥匙串或加密凭据文件里。用 claude mcp get <name> 可以验证 OAuth 是否配置成功。

5.4 限制 OAuth Scope

可以用 oauth.scopes 限制申请的权限范围，值是 RFC 6749 格式的空格分隔字符串：

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

如果授权服务器支持 offline_access，Claude Code 会自动追加，确保 Token 能刷新。

六、实战：三个完整配置示例

6.1 查询生产数据库（stdio）

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

之后可以直接问：

这个月总收入是多少？
orders 表的 Schema 是什么样的？
找出 90 天没下单的客户

6.2 接入 GitHub 做代码审查（HTTP + Bearer Token）

先去 GitHub Settings > Developer settings > Personal access tokens 生成 fine-grained token，然后：

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

使用示例：

Review PR #456 并给出改进建议
给我创建一个关于刚才发现的 bug 的 Issue
列出所有分配给我的 open PR

6.3 监控生产错误（HTTP + OAuth）

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

在 Claude Code 里运行 /mcp，按提示完成 Sentry OAuth 登录。然后：

过去 24 小时最常见的错误是什么？
查看错误 ID abc123 的堆栈
哪个部署引入了这些新错误？

七、管理服务器：日常运维命令

# 列出所有已配置服务器
claude mcp list
 
# 查看某个服务器的详细配置
claude mcp get github
 
# 删除服务器
claude mcp remove github
 
# 在 Claude Code 会话内查看状态（含工具数量、连接状态）
/mcp
 
# 从 JSON 直接添加
claude mcp add-json weather-api \
  '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'
 
# 从 Claude Desktop 导入已有配置（仅 macOS/WSL）
claude mcp add-from-claude-desktop

7.1 自动重连机制

HTTP 和 SSE 服务器断线后，Claude Code 会自动重连，最多 5 次，退避策略是指数增长（1 秒起步，每次翻倍）。初始连接失败时，对于 5xx、连接拒绝、超时等瞬态错误也会重试最多 3 次。401/403 和 404 不会重试，因为需要改配置。

stdio 服务器是本地进程，断线后不会自动重连。

7.2 动态工具更新

Claude Code 支持 MCP 的 list_changed 通知。如果服务器在运行期间新增或修改了工具，会主动通知客户端刷新，不需要手动重连。

八、权限与工具搜索：控制 Claude 能做什么

8.1 工具命名规则

MCP 工具在 Claude Code 里的完整名称是 mcp__<server-name>__<tool-name>。比如 GitHub 服务器的 list_issues 工具，全名是 mcp__github__list_issues。

8.2 用 allowedTools 自动授权

MCP 工具需要显式授权才能使用。最精确的方式是在 settings.json 或代码里配置 allowedTools：

{
  "permissions": {
    "allow": [
      "mcp__github__*",
      "mcp__db__query",
      "mcp__slack__send_message"
    ]
  }
}

通配符 * 可以批量授权。官方文档明确建议：优先用 allowedTools 而不是 permission mode 来控制 MCP。因为 acceptEdits 模式不会自动批准 MCP 工具（只批文件编辑和 Bash），而 bypassPermissions 会关掉所有安全提示，范围过大。

8.3 工具搜索（Tool Search）

默认启用的工具搜索机制，会把 MCP 工具的定义延迟加载，只在 Claude 需要时才搜索并载入。这样加再多服务器也不会挤爆上下文窗口。

控制方式：

# 默认行为：全部延迟加载
# （在 Vertex AI 或非官方代理上会自动回退到前置加载）
 
# 强制延迟加载（即使 Vertex AI 也发 beta header，可能失败）
ENABLE_TOOL_SEARCH=true claude
 
# 阈值模式：如果工具定义占上下文不到 10% 就前置加载，否则延迟
ENABLE_TOOL_SEARCH=auto claude
 
# 自定义阈值
ENABLE_TOOL_SEARCH=auto:5 claude
 
# 完全关闭
ENABLE_TOOL_SEARCH=false claude

工具搜索需要模型支持 tool_reference 块：Sonnet 4 及以上、Opus 4 及以上。Haiku 不支持。

8.4 强制前置加载特定服务器

如果某个服务器的工具 Claude 每轮都需要，可以设置 alwaysLoad: true：

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

这会阻塞启动直到该服务器连上（最多等 5 秒连接超时）。服务器作者也可以在工具的 _meta 里加 "anthropic/alwaysLoad": true，只对单个工具生效。

九、输出限制与性能调优

9.1 MCP 工具输出上限

Claude Code 对 MCP 工具输出有两层限制：

• 警告阈值：10,000 tokens，超过会在界面提示
• 默认上限：25,000 tokens，超过会被截断或写入磁盘

调整环境变量：

export MAX_MCP_OUTPUT_TOKENS=50000
claude

9.2 单个工具提升限额

如果你是服务器作者，可以在工具定义里加 _meta 注解：

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

这个值最高可以到 500,000 字符，且独立于 MAX_MCP_OUTPUT_TOKENS。注意对返回图片的工具无效，图片始终受 token 限制。

9.3 超时配置

• 服务器启动超时：MCP_TIMEOUT 环境变量，默认 5 秒。比如 MCP_TIMEOUT=10000 claude 设为 10 秒。
• 单工具执行超时：在 .mcp.json 里加 "timeout": 600000（毫秒），表示 10 分钟。这个值会覆盖 MCP_TOOL_TIMEOUT 环境变量。

超时是硬性的 wall-clock 限制，服务器的进度通知不会延长它。小于 1000 的值会被提升到 1 秒。HTTP/SSE 的首次字节预算最少 60 秒，不受此值影响。

十、故障排查：常见问题与解法

10.1 服务器连不上

# 先看列表确认配置是否生效
claude mcp list
 
# 看详细配置
claude mcp get <name>
 
# 在 Claude Code 里看实时状态
/mcp

如果服务器显示 pending，可能是：

• 网络问题（HTTP/SSE）
• 命令路径不对（stdio，试试 which claude 或 which npx）
• 环境变量没传进去（stdio 用 --env 或检查 .mcp.json 的 env）

10.2 OAuth 回调失败

浏览器认证完成后如果 Claude Code 没收到回调，直接把浏览器地址栏里的完整 callback URL 粘贴到 Claude Code 的 URL 提示框里即可。

10.3 工具调用没反应

• 确认 allowedTools 里授权了对应的 mcp__<server>__<tool>
• 确认服务器在 /mcp 里显示已连接且工具有效数量 > 0
• 检查 Claude Code 版本是否支持 tool reference（v2.1.121+ 推荐）

10.4 从 Claude Desktop 迁移

如果你之前在 Claude Desktop 里配过 MCP，可以一键导入：

claude mcp add-from-claude-desktop --scope user

仅支持 macOS 和 WSL。导入后同名服务器会自动加数字后缀避免冲突。

十一、进阶：把 Claude Code 本身变成 MCP 服务器

Claude Code 也可以反向作为 MCP 服务器被其他客户端调用：

claude mcp serve

在 Claude Desktop 里配置：

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

如果 claude 不在 PATH 里，用 which claude 找完整路径替换 command 字段。这个服务器会暴露 Claude Code 的内置工具（View、Edit、LS 等），但调用确认需要客户端自己实现。

十二、总结：一张图理清配置决策

面对一个新工具，按这个流程判断怎么接：

1. 工具跑在哪？

   • 云端服务（Notion、Sentry、GitHub）→ HTTP 传输
   • 本地脚本/数据库 → stdio 传输

2. 几个人用？

   • 只有我自己 → Local scope（默认）
   • 团队共享 → Project scope（.mcp.json）
   • 我所有项目都要 → User scope

3. 怎么认证？

   • OAuth 2.0 → 直接 claude mcp add，然后 /mcp 登录
   • 固定 Token → --header "Authorization: Bearer ..."
   • 动态 Token → headersHelper 脚本

4. 权限怎么控？

   • 在 settings.json 或 .claude/settings.json 里配 allowedTools，用 mcp__<server>__* 批量授权

5. 工具太多怕占上下文？

   • 默认 Tool Search 已帮你延迟加载，无需操作
   • 核心工具设 alwaysLoad: true

MCP 不是魔法，它的价值在于把"AI 能做什么"从模型能力边界，扩展到了你现有工具链的能力边界。配置一次，后续的自然语言交互就会顺畅很多。

参考链接

• Claude Code MCP 文档
• Claude Code Agent SDK MCP 文档
• MCP 协议官方文档
• MCP 架构概述
• MCP 服务器概念
• MCP 工具规范
• 构建 MCP 服务器教程