MCP（Model Context Protocol）是 Claude Code 连接外部工具与实时数据的标准化协议。本文将指导您完成 MCP 服务器的安装配置、OAuth 认证流程、多服务器工作流构建，并深入讲解工具搜索、资源引用、作用域管理及关键版本（v2.1.136+）的稳定性修复，帮助您构建强大且可靠的自动化工作流。

Claude Code MCP 集成指南：外部工具连接、OAuth 认证与多服务器工作流

MCP 协议让 Claude Code 能够超越静态记忆，实时访问 GitHub 仓库、数据库、文件系统等外部服务的数据与功能。这种集成是构建复杂、动态工作流的基础。

理解 MCP 架构与生态系统

Claude Code、MCP 服务器与外部服务三者之间的通信遵循请求-响应模式，核心架构如下图所示：

graph TB
    A["Claude"]
    B["MCP Server"]
    C["External Service"]

    A -->|Request: list_issues| B
    B -->|Query| C
    C -->|Data| B
    B -->|Response| A

    A -->|Request: create_issue| B
    B -->|Action| C
    C -->|Result| B
    B -->|Response| A

Claude Code 可以同时连接多个 MCP 服务器，形成一个丰富的工具生态系统。

graph TB
    A["Claude"] -->|MCP| B["Filesystem<br/>MCP Server"]
    A -->|MCP| C["GitHub<br/>MCP Server"]
    A -->|MCP| D["Database<br/>MCP Server"]
    A -->|MCP| E["Slack<br/>MCP Server"]
    A -->|MCP| F["Google Docs<br/>MCP Server"]

安装与配置 MCP 服务器

Claude Code 支持三种传输协议连接 MCP 服务器。下表列出了它们的适用场景：

传输协议	状态	典型场景	安装命令示例
HTTP (推荐)	活跃	连接远程云服务 (如 Notion API)	`claude mcp add --transport http notion https://mcp.notion.com/mcp`
Stdio	活跃	运行本地 Node.js 服务器	`claude mcp add --transport stdio myserver -- npx @myorg/mcp-server`
SSE	已弃用	连接旧版服务器	`claude mcp add --transport sse legacy-server https://example.com/sse`

使用 `CLAUDE_PROJECT_DIR` 环境变量 (v2.1.139+)

对于 stdio 服务器，Claude Code 会自动设置 CLAUDE_PROJECT_DIR 环境变量，指向项目根目录的绝对路径。你可以在 .mcp.json 配置中引用它，实现路径的动态解析。

{
  “mcpServers”: {
    “repo-tools”: {
      “type”: “stdio”,
      “command”: “node”,
      “args”: [“${CLAUDE_PROJECT_DIR}/.claude/mcp/repo-tools.js”],
      “env”: {
        “REPO_ROOT”: “${CLAUDE_PROJECT_DIR}”
      }
    }
  }
}

这对于编写需要读取项目内文件的本地 MCP 工具脚本非常有用。

Windows 用户注意事项

在原生 Windows（非 WSL）环境下运行 npx 命令时，需要使用 cmd /c 包裹：

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

配置 OAuth 2.0 认证

对于需要 OAuth 认证的服务（如 GitHub、Google Docs），Claude Code 提供了完整的交互式认证流程。

交互式认证

直接添加 OAuth 服务器后，在 Claude Code 会话中使用 /mcp 命令，选择对应的服务即可触发浏览器认证流程。

claude mcp add --transport http my-service https://my-service.example.com/mcp
# 然后在会话中输入 /mcp 并选择 my-service

预配置凭证（用于自动化或非交互环境）

可以通过命令行参数预先指定 OAuth 客户端信息，实现非交互式设置。

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

Token 会安全存储在你的系统钥匙串中。v2.1.136 版本修复了多个 OAuth 服务器并发刷新 token 时可能导致失效的问题，建议升级以获得更稳定的体验。

覆盖 OAuth 元数据发现端点

如果你的服务器标准元数据端点 (/.well-known/oauth-authorization-server) 有问题，但提供了有效的 OIDC 端点，可以在 .mcp.json 中覆盖。

{
  “mcpServers”: {
    “my-server”: {
      “type”: “http”,
      “url”: “https://mcp.example.com/mcp”,
      “oauth”: {
        “authServerMetadataUrl”: “https://auth.example.com/.well-known/openid-configuration”
      }
    }
  }
}

优化工具管理与交互

当连接的 MCP 工具过多时，Claude Code 提供了智能的工具搜索机制以避免上下文过载。

工具搜索机制 (ENABLE_TOOL_SEARCH)

工具描述总和超过上下文窗口 10% 时，工具搜索会自动启用。你也可以通过环境变量控制：

ENABLE_TOOL_SEARCH=true: 始终启用。
ENABLE_TOOL_SEARCH=false: 始终禁用，所有工具描述全部发送。
ENABLE_TOOL_SEARCH=auto:<N>: 自定义工具数量阈值。

强制加载关键工具 (`alwaysLoad: true`)

对于每次会话都必须可用的关键工具，可以在其服务器配置中设置 “alwaysLoad”: true，以跳过工具搜索的延迟加载。

{
  “mcpServers”: {
    “always-on-tool”: {
      “command”: “node”,
      “args”: [“./tools/always.js”],
      “alwaysLoad”: true
    }
  }
}

MCP Apps：交互式 UI 组件

MCP 工具调用现在可以返回交互式 UI 组件（如表格、表单、图表），直接渲染在聊天界面中，大大提升了数据展示和交互体验。

资源引用与提示命令

资源引用：使用 @ 语法直接在提示词中引用 MCP 资源，如 @database:postgres://mydb/users。
提示命令：MCP 服务器暴露的提示（Prompts）会成为斜杠命令，命名规则为 /mcp__<服务器名>__<提示名>，例如 /mcp__github__review。

管理多服务器配置与作用域

MCP 配置可以存在于多个作用域，便于个人、团队和项目之间的隔离与共享。

作用域	配置文件路径	描述	共享范围	首次使用需批准
Local (默认)	`~/.claude.json` (项目路径下)	仅限当前用户、当前项目	仅自己	否
Project	`.mcp.json` (项目根目录)	提交到代码仓库，团队共享	团队成员	是
User	`~/.claude.json`	当前用户所有项目可用	仅自己	否

服务器去重规则：当同一服务器在多个作用域中定义时，Local 作用域的配置拥有最高优先级，会覆盖 Project 或 User 作用域的配置。

v2.1.136 关键生命周期修复

该版本修复了两个影响多服务器工作流的长期问题：

/clear 后服务器持久化：通过 .mcp.json、插件或 claude.ai 连接器配置的 MCP 服务器，在执行 /clear 命令后不会再丢失。
并发 OAuth 刷新：多个 OAuth 服务器并发刷新 token 时不再会丢失刷新令牌，解决了需要频繁重新认证的问题。

最佳实践与故障排查

安全实践

使用环境变量管理所有凭证，切勿硬编码在配置文件中。
遵循最小权限原则，为每个 MCP 工具分配必要的最小权限。
将 .mcp.json 纳入版本控制，但确保其中不包含任何密钥。

性能与调试

通过 /mcp 命令查看服务器状态、工具数量和连接情况。
v2.1.128 版本起，/mcp 会高亮显示工具数为 0 的服务器，方便快速定位配置问题。
如果遇到连接问题，首先使用 claude mcp list 和 claude mcp get <服务器名> 检查配置。
检查 MCP 服务器日志通常位于 ~/.claude/logs/ 目录下。

更多高级配置如插件提供的 MCP 服务器、子代理作用域 MCP 等，可以参考本指南对应的 MCP 配置模板。整个 Claude Code 功能的学习路径，可参考 Claude HowTo 完全指南。

FAQ

Q: 工具搜索和 alwaysLoad 应该如何选择？ A: 工具搜索是为了节省上下文，适合工具数量多但并非每次都会用到的场景。alwaysLoad 适用于像“代码质量扫描”这样几乎每次交互都需要的核心工具，但会占用固定上下文，需谨慎使用。

Q: 为什么连接 OAuth 服务器后，过一段时间又需要重新认证？ A: 这通常是旧版本中多个 OAuth 服务器并发刷新 token 时的已知 Bug。请升级 Claude Code 至 v2.1.136 或更高版本以解决此问题。

Q: 如何让团队成员在使用我的项目 .mcp.json 时自动获得正确的配置？ A: 将 .mcp.json 文件提交到项目的 Git 仓库即可。团队成员首次使用其中的 MCP 服务器时，Claude Code 会提示他们进行一次性的批准。

Claude Code MCP 集成指南：外部工具连接、OAuth 认证与多服务器工作流 #

理解 MCP 架构与生态系统 #

安装与配置 MCP 服务器 #

使用 CLAUDE_PROJECT_DIR 环境变量 (v2.1.139+) #

Windows 用户注意事项 #

配置 OAuth 2.0 认证 #

交互式认证 #

预配置凭证（用于自动化或非交互环境） #

覆盖 OAuth 元数据发现端点 #

优化工具管理与交互 #

工具搜索机制 (ENABLE_TOOL_SEARCH) #

强制加载关键工具 (alwaysLoad: true) #

MCP Apps：交互式 UI 组件 #

资源引用与提示命令 #

管理多服务器配置与作用域 #

v2.1.136 关键生命周期修复 #

最佳实践与故障排查 #

安全实践 #

性能与调试 #

FAQ #