2.4　将 MCP 服务器集成到 Claude Code 与 Agent 工作流

这一条考什么

考你能否把 MCP 服务器正确接入 Claude Code 和 Agent 工作流：团队共享的服务器放哪里、个人实验的服务器放哪里，凭据怎样不进 Git，多个服务器的工具如何同时可用。还会考两类“设计判断”：标准集成（如 Jira、GitHub）优先用现成的社区 MCP 服务器；以及用 MCP 资源（resources）公开内容目录、用更好的工具描述让 Agent 真正去用 MCP 工具，而不是退回到 Grep 之类的内置工具。

核心概念

作用域：项目级 .mcp.json 与用户级 ~/.claude.json

Claude Code 的 MCP 配置有不同作用域，考试最常考的是两种：

• 项目级（project scope）：写在仓库根目录的 .mcp.json，随代码提交到版本控制。所有克隆仓库的人都会得到同一套服务器配置，适合团队共享的工具（工单系统、内部文档搜索、数据库查询）。出于安全考虑，Claude Code 首次使用项目里的服务器时会请求用户批准。
• 用户级（user scope）：写在 ~/.claude.json，只对你自己生效，跨所有项目可用，不会被同事看到。适合个人工具、正在试验的服务器。
• 另外还有默认的 local 作用域（同样存在 ~/.claude.json，但只绑定当前项目），本质也是“个人的、不共享”。

用 CLI 添加时通过作用域参数区分，例如 claude mcp add --scope project ... 写入 .mcp.json，--scope user 写入用户配置。判断原则只有一句话：需要团队共享就放 .mcp.json；只给自己用、实验性质就放 ~/.claude.json。

环境变量展开：凭据不进仓库

.mcp.json 要提交，所以绝不能写死 token。Claude Code 支持在 .mcp.json 中用 ${VAR} 展开环境变量（也支持 ${VAR:-默认值}），可以出现在 command、args、env、url、headers 中：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "docs-search": {
      "type": "http",
      "url": "${DOCS_MCP_URL:-https://mcp.internal.example.com/docs}",
      "headers": { "Authorization": "Bearer ${DOCS_API_KEY}" }
    }
  }
}

每个开发者在自己的 shell 或密钥管理工具里设置 GITHUB_TOKEN，配置文件本身可以安全共享。

连接时发现、同时可用

Claude Code 启动（或 Agent SDK 建立会话）时会连接所有已配置的 MCP 服务器，并通过 MCP 的工具列表接口发现每个服务器提供的工具。所有服务器的工具会同时出现在 Agent 的工具集合里，模型在同一轮里可以先调 GitHub 服务器建分支，再调 Jira 服务器更新工单，不需要“切换服务器”或手动指定。在 Claude Code 中这些工具以 mcp__<服务器名>__<工具名> 的形式命名，可以用 /mcp 查看连接状态和工具列表。

MCP 资源：公开内容目录

MCP 除了 tools，还有 resources（可读取的数据）和 prompts（可复用的提示模板）。resources 的典型用法是公开“目录”：工单摘要列表、文档层级结构、数据库 schema。Agent 一开始就知道“这里有什么”，就不必靠一连串 search、list、get 的探索性调用去摸索，既省调用次数也省上下文。在 Claude Code 中，资源可以通过 @服务器名:资源URI 的方式引用并附加到消息里；MCP prompts 则以 /mcp__服务器名__提示名 的斜杠命令出现。

工具描述决定工具是否被使用

模型选工具主要依据工具的名称和描述。如果 MCP 工具描述只有一句“分析依赖”，而内置 Grep 的描述清楚写着“用正则搜索文件内容，返回带行号的匹配”，模型自然会选 Grep。解决方法是扩充 MCP 工具描述：写清它能做什么、返回什么结构、什么场景比文本搜索更合适、输入格式和限制。

{
  "name": "analyze_dependencies",
  "description": "构建指定模块的依赖图：返回直接依赖、传递依赖（含层级）、循环依赖列表。比在代码中 grep import 语句更准确，因为它会解析别名导入、re-export 和动态导入。输入：模块路径（如 src/billing）。输出：JSON，含 direct、transitive、cycles 三个数组。"
}

社区服务器 vs 自建服务器

Jira、GitHub、Slack、Postgres 这类标准系统已经有成熟的社区或官方 MCP 服务器，直接集成即可：维护成本低、工具接口经过验证。自建 MCP 服务器应该留给团队特有的工作流，例如内部发布审批流程、专有数据模型。用 Bash + curl 直接调 REST API、或把工单导出成 Markdown，都是绕开 MCP 的做法，缺少可发现的工具接口和结构化结果。

正确做法与反模式

• 正确：团队共享服务器写入 .mcp.json 并提交，token 用 ${GITHUB_TOKEN} 展开。反模式：把 token 明文写进 .mcp.json 提交；或者让每个人各自在 ~/.claude.json 里手配，导致团队配置不一致。
• 正确：个人或实验性服务器写入 ~/.claude.json。反模式：把只有自己在试的服务器塞进 .mcp.json，强加给全队。
• 正确：扩充 MCP 工具描述，说明能力、输出和优于内置工具的场景。反模式：为了“逼”模型用 MCP 工具而删除 Grep，或在系统提示里写死路由规则、再加一层意图分类器。
• 正确：标准集成选现成社区服务器，自建服务器只用于团队特有流程。反模式：为 Jira 从零写一个 MCP 服务器，或用 Bash curl 调 API 代替。
• 正确：把工单摘要、文档目录、数据库 schema 作为 MCP resources 公开。反模式：让 Agent 每次都通过大量探索性工具调用摸清数据，耗尽上下文。

常见陷阱

• 作用域放反：选项把团队服务器放 ~/.claude.json、个人服务器放 .mcp.json，或“两个都放同一处”。记住：共享靠版本控制，只有 .mcp.json 会被提交。
• “Agent 每轮只能用一个服务器 / 需要按请求路由到某个服务器”：错。所有已配置服务器的工具在连接时被发现，同时可用。
• “删掉 Grep 来消除功能重叠”：看似直接，实际上削弱了 Agent 的通用能力，也没解决描述不清的根因。正确答案几乎总是改进工具描述。
• “自建 MCP 服务器更贴合团队需求”：对标准系统来说是过度工程，题目强调“标准 Jira 数据”时应选现成服务器。
• 用一个“万能”工具（如 prepare_investigation 接收自然语言问题）或合并多个服务器来解决探索成本：正确方向是用 resources 暴露内容目录，让 Agent 先看到有什么。
• 把 MCP prompts 当成自动注入的系统上下文或模型自动调用的工具：在 Claude Code 中它们是用户可调用的斜杠命令。

实操练习

目标：在一个仓库里同时配置一个团队共享服务器和一个个人服务器，验证环境变量展开和工具同时可用。

1. 在仓库根目录创建 .mcp.json，加入 GitHub 服务器，token 使用 ${GITHUB_TOKEN}。
2. 在 shell 中导出 GITHUB_TOKEN，确认 .mcp.json 里没有任何明文密钥后再提交。
3. 用 CLI 以用户作用域添加一个个人实验服务器。
4. 启动 Claude Code，运行 /mcp 查看两个服务器是否都已连接，以及工具名前缀。
5. 发一个同时需要两个服务器的请求，观察模型在同一会话中调用两边的工具。

# 1) 项目级：写入 .mcp.json（团队共享）
claude mcp add --scope project github \
  -e GITHUB_PERSONAL_ACCESS_TOKEN='${GITHUB_TOKEN}' \
  -- npx -y @modelcontextprotocol/server-github

# 2) 用户级：只对自己生效（个人实验）
claude mcp add --scope user scratch-notes -- npx -y my-experimental-mcp-server

# 3) 检查
cat .mcp.json          # 应只看到 ${GITHUB_TOKEN}，没有真实 token
claude mcp list        # 两个服务器都应列出
export GITHUB_TOKEN=ghp_xxx
claude                 # 进入后执行 /mcp

检查结果：.mcp.json 中只有占位符；同事克隆后只会看到 github 服务器，看不到 scratch-notes；在会话里两个服务器的 mcp__... 工具同时出现。

自测清单

• 团队共享的 MCP 服务器和个人实验服务器分别应该配置在哪个文件？为什么？
• 如何在 .mcp.json 中引用 token 而不把密钥提交到仓库？
• 配置了三个 MCP 服务器时，Agent 是如何获得并选择这些工具的？
• Agent 总是用 Grep 而不用功能更强的 MCP 工具，首选的修复方法是什么？哪些修复是反模式？
• 什么情况下应自建 MCP 服务器，什么情况下应直接用社区服务器？
• MCP resources 解决了什么问题？举出三种适合作为资源公开的内容目录。