Claude Code 什么时候需要接 MCP

平时做代码重构，文件全在本地磁盘上，Claude 靠自带的工具就能完成读取。换到稍微复杂的真实场景，单机就不够用了：审查代码时，代码在本地，团队在 PR 上留下的二十多条最新评审意见却在远端；分析线上丢单故障时，应用逻辑盘得再透彻，也得去只读数据库里查当前的交易流水状态。

这些任务需要一条安全连接外部系统的通道，以获取当前状态。MCP（Model Context Protocol）就是做这件事的。可以把它想成一套统一的插头标准：Claude Code 是插座，各种 MCP server 是转换插头，负责对接后面的 GitHub、Postgres、Jira 甚至自研的内网接口。

真正动手接入时，常见的困惑有三类：

• 哪些需求真要 MCP，哪些读本地文件、写进记忆或者用现成的 CLI 就够；
• 远程服务和本地工具该用哪种连接方式，令牌怎样传才不落进配置文件；
• 配置放在个人范围还是项目范围，环境变量要不要写默认值。

先用四个问题判断要不要接；真要接，起步时只接一个只读服务，摸透它的权限和返回格式，再慢慢加。

01 MCP 在链路里负责什么

Claude Code → MCP server → 外部服务
                 │
                 ├─ 描述工具用途与参数
                 ├─ 处理连接、认证和权限
                 └─ 返回结果，必要时请求用户补充信息

MCP server 把鉴权、参数校验和返回格式包揽下来，省得你每次临时给它写一段拼凑的 Python 脚本或 curl 命令。MCP server 可以暴露几类能力：

Tools 执行动作，Prompts 复用流程（以 /mcp__<server>__<prompt> 形式出现），Resources 用 @server-name:protocol://resource/path 引用对象，Elicitation 在创建工单前询问优先级、负责人这类结构化信息。

02 MCP、记忆和本地文件的边界

MCP 和 Memory 都会提供上下文，但解决的问题不同：

“需要上下文”还不足以决定用哪一个。拿 PR 来说：团队的编码规范变化少，放 Memory；当前审查状态会变，需要实时查；同一份摘要若已导出到本地，直接读文件就行。长期规则放哪一层，见 CLAUDE.md 规则越写越乱，怎么整理。

已有可靠 CLI 能完成查询时，也可以继续用。只有确实需要稳定连接外部系统、发现工具和复用认证，MCP 才补上一个实际缺口。为读一份本地材料再搭一层连接，通常不划算。

03 接入前问四个问题

能接进来的外部服务五花八门：代码托管、业务数据库、本地文件系统、工单系统、团队通知或者自研内网 API。先挑一个眼下最需要的服务试用。每次动手接入前，问自己四个问题：

1. 这个数据是否需要实时访问？
2. Claude Code 是否真的需要直接调用这个外部能力？
3. 可以授予的最小权限是什么？
4. 如果工具返回大量数据，如何限制输出？

以工单查询为例，把四个问题落到具体选择：

04 按 server 在哪里运行选传输方式

MCP server 可以通过不同 transport 连接：

选 transport，先确定 server 在哪里运行。团队共享的远程服务，通常从 HTTP 看起；本机工具、项目脚本和开发调试，通常从 stdio 看起。协议层面的定义见 MCP 规范的传输方式一节。

下面的 @company/... 包名和示例地址均为占位示例，执行前替换为服务方提供、经过审核的地址或启动命令。HTTP 适合远程服务：

claude mcp add --transport http project-api "https://mcp.example.com/mcp"

stdio 适合本地 server，也可以传入环境变量：

claude mcp add --transport stdio local-tools -- npx @company/mcp-server

在 Windows 上，本地 server 可能需要显式使用 cmd /c：

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

05 令牌怎样传，才不落进配置

要给 HTTP 服务认证，可以用 header 或 OAuth。先看下面这条命令发生了什么：

claude mcp add --transport http secure-api "https://mcp.example.com/mcp" \
  --header "Authorization: Bearer $API_TOKEN"

shell 会先把 $API_TOKEN 展开成实际值，再交给 CLI。命令里写的是变量，生成的配置却可能已经存入了真实凭据。用 --env "API_TOKEN=$API_TOKEN" 给 stdio server 传值也是同样的道理。这类写法适合演示传参；要共享配置定义，改用下一节 .mcp.json 里的环境变量占位写法。

对于支持 OAuth 2.0 的 MCP server，Claude Code 可以处理浏览器授权、token 存储和刷新：

claude mcp add --transport http my-service "https://mcp.example.com/mcp"
claude mcp login my-service

需要清除登录状态时用 claude mcp logout my-service。按 Claude Code 的 MCP 文档，claude -p 这类打印模式运行没有交互面板，走不了 OAuth 流程，要先在交互会话里用 /mcp 或在 shell 里用 claude mcp login 完成登录。

连接所用凭据决定外部系统的实际权限，按这些规则管理：

• 密钥不写进 .mcp.json。
• 凭据优先放在环境变量、系统 keychain 或 OAuth 机制中。
• 团队共享配置只保留 server 定义，不保留个人 token。
• 不同环境使用不同凭据。
• 定期清理失效 token。
• 给外部服务配置最小权限 scope。

06 .mcp.json 与环境变量展开

项目级 MCP 配置写在项目根目录的 .mcp.json；用 CLI 添加时要显式指定 --scope project，否则默认写进当前项目的个人 local 配置。先只接入一个只读服务，确认能完成查询，再组合多个服务。

{
  "mcpServers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["@company/database-mcp"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "project-api": {
      "type": "http",
      "url": "${PROJECT_API_MCP_ENDPOINT}",
      "headers": {
        "Authorization": "Bearer ${PROJECT_API_TOKEN}"
      }
    }
  }
}

环境变量有两种写法：

必填信息用 ${VAR}，可安全默认的本地工具路径等才用 ${VAR:-default}。

配置时很多人图省事喜欢写默认回退，比如 ${DATABASE_URL:-postgresql://localhost/dev}。这在本地摸索时看似贴心，在团队协作或正式排障中却藏着一个隐蔽的陷阱：负责跑任务的同学漏配了目标环境的 DATABASE_URL，系统不会提示，而是悄悄连上本地很久没更新的 dev 数据库。

这时所有的只读查询表面上全跑通了，返回的旧数据看起来也合情合理，可你查的根本不是同一个环境。这种“假装成功”比直接连接失败更危险。

所以凡是涉及环境边界、目标库地址的变量，写成 ${DATABASE_URL}，不加默认值。缺变量时，claude mcp list 和 /mcp 会点名警告，变量原样保留，连接通常会直接失败，逼着你在第一时间把环境配置补齐。还要留意一点：官方说明变量设为空字符串也算“已设置”，${VAR:-default} 这时展开为空，不会用默认值。

07 配置放在哪个作用域

MCP 配置有多个作用域：

配置位置取决于谁需要它：

• 团队代码托管 MCP：放在 Project 的 .mcp.json，共享连接配置，凭据分别注入。
• 个人笔记检索 MCP：放在 User，供本人跨项目使用。
• 数据分析子代理专用 MCP：放在该代理的 frontmatter，仅在对应角色执行时提供。

项目级 .mcp.json 可以提交到仓库，但 secrets 要由环境变量注入。出于安全考虑，交互会话第一次使用项目里 .mcp.json 定义的服务前会请你批准，需要重置这些批准时运行 claude mcp reset-project-choices。同一 server 出现在多个 scope 时，还要检查实际生效的覆盖关系。企业环境可以通过受管配置里的 allowedMcpServers、deniedMcpServers 控制允许或禁止的 server。

08 管理连接：按失败位置选动作

在 Claude Code 里用 /mcp 可以查看 MCP server、连接状态和认证状态，并触发相关操作。终端里的管理命令按当前需要选择：

日常维护可以顺着失败位置选动作。先用 list 和 get 确认配置；问题在认证，再检查登录状态；只有项目批准选择混乱时，才考虑重置。这样每次只改变有关的一层，后面也容易判断是哪项处理生效。

连接配好只是开始。接上数据库、文件系统这类服务后，账号权限、返回量和外部内容里的可疑指令怎样管住，接着看 用只读账号防止 Claude Code 误改数据。

第一步可以很小：挑一个只读的代码托管服务，用 --scope project 写进 .mcp.json，令牌留在环境变量里，再让它查一条最新的 PR 评论。查得到，再接下一个。