在 Claude Code 里接入 MCP 服务器

这篇适合谁

适合已经在用 Claude Code、希望它直接读取工单系统、查询数据库或操作浏览器，而不是把内容粘贴进对话的人。读完你能添加一个服务器，确认它已连接，在会话里调用它，决定它的配置应该放在哪里，并排查最常见的几类失败。

MCP 能加什么

模型上下文协议（MCP，Model Context Protocol）让 Claude Code 使用内置工具之外的工具。这些工具来自 MCP 服务器，服务器可以是你本机运行的程序，也可以是托管在网上的服务^[1]。接入的常见原因是：你发现自己总在把另一个工具里的数据复制进对话。服务器接入后，Claude 就能直接读取那个系统并进行操作^[2]。

准备

需要 Claude Code，并在一个项目目录里打开终端。空目录也可以^[1]。本机 stdio 服务器有各自的要求：Playwright 例子通过 npx 运行，需要 Node.js 18 或更高版本^[1]。

第一步：添加一个托管服务器

快速入门用的是 Claude Code 文档 MCP 服务器。它托管在网上，不需要认证或额外配置，适合做第一次测试^[1]。这条命令要在终端里运行，不要放在 claude 会话里面：

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

名字 claude-code-docs 由你自己取。Claude Code 用它给服务器的工具加标签，也用它指代服务器，例如 claude mcp remove 命令^[1]。输出里的 local config 表示服务器只为你、只在当前项目生效，换一个项目打开就不会生效^[1]。

第二步：检查状态

claude mcp list

连接正常的服务器显示 ✔ Connected。! Needs authentication 表示需要浏览器登录或令牌，✘ Failed to connect 表示服务器没有响应，✘ Connection error 表示连接过程中出了错^[1]。先看状态，再动配置。

第三步：在会话里使用

启动 claude，在请求里点名这个服务器。文档的示例是让 Claude 通过 claude-code-docs 查询 MCP_TIMEOUT 的作用。点名可以保证答案来自这个服务器，而不是其他工具。第一次调用时 Claude Code 可能会请求许可；输出里的工具调用会带上服务器名，据此可以确认答案的来源^[1]。

同时接入多个服务器时，工具调用的标签会带上各自的服务器名，答案来自哪个服务器一眼就能看出^[1]。用完可以删除。每个已连接的服务器都会占用一部分上下文窗口，因为它的工具名和服务器说明会载入每一个会话^[1]：

claude mcp remove claude-code-docs

选择作用域

--scope 决定配置存在哪里、谁能看到。local 是默认值：只属于你，只在当前项目生效。user 也只属于你，但在你所有项目里都生效。project 写入项目根目录的 .mcp.json，团队可以共享^[1]^[2]。

三种作用域的存储位置不同。本地作用域存在 ~/.claude.json 里该项目的条目下；项目作用域存在 .mcp.json；用户作用域存在 ~/.claude.json 顶层的 mcpServers 键下^[1]。同一个服务器如果在多处定义，Claude Code 只用优先级最高的那一处的完整条目，字段不会跨作用域合并。优先级从高到低依次是：本地、项目、用户、插件提供的服务器，最后是 claude.ai 连接器^[2]。

选哪个作用域可以按用途判断。只在自己机器上试一试的服务器用 local，它只对当前项目生效。想在你所有项目里都能用的个人工具用 user。需要团队一起用的服务器用 project，把 .mcp.json 提交进版本控制，团队就能共享同一份配置^[1]^[2]。

用 .mcp.json 和团队共享

.mcp.json 可以提交进代码仓库。下面的例子同时定义了文档服务器（HTTP）和 Playwright 服务器（本机 stdio 进程）：

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

HTTP 服务器的 url 是 Claude Code 连接的端点；stdio 服务器的 command 和 args 是它启动的程序^[1]。Claude Code 在会话开始时读取这个文件，所以修改后要重启会话^[1]。

团队成员第一次遇到项目作用域的服务器时，Claude Code 会请求审批。这个提示是为了避免克隆下来的仓库未经同意就在你的机器上启动进程^[1]。审批记录可以重置：

claude mcp reset-project-choices

在 claude -p 运行、Agent SDK 会话，或项目线程之外的云端会话里，这个审批提示无法显示。这种场景应改用 disabledMcpjsonServers、--setting-sources 或 --strict-mcp-config^[2]。

本机 stdio 服务器：以 Playwright 为例

stdio 服务器是 Claude Code 作为子进程启动的程序。Playwright MCP 是通过 npx 启动的本机程序，适合作为 stdio 服务器的例子^[1]：

claude mcp add playwright -- npx -y @playwright/mcp@latest

其中的 -- 很关键。它前面的内容是 Claude 自己的选项，例如 --transport、--env 和 --scope；它后面的内容是启动服务器的命令和参数，会原样传给服务器^[2]。环境变量用 --env 传入：

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

需要登录的托管服务：以 Sentry 为例

有些托管服务把 MCP 服务器放在 OAuth 后面。添加 Sentry 的方式和添加文档服务器相同：

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

这时 claude mcp list 会显示 ! Needs authentication，这是正常的。在会话里打开 /mcp，选中 sentry，选择 Authenticate，然后在弹出的浏览器里批准连接^[1]。只用静态令牌的服务，在添加时用 --header "Authorization: Bearer <token>" 传入^[1]^[2]。

连接失败时怎么查

先看状态。HTTP 服务器可以先确认地址能否访问：

curl -I https://mcp.sentry.dev/mcp

返回 404 或 405，说明服务器在线，这对只接受 POST 请求的端点是正常的。返回 401 或 403，说明服务器在线但需要认证。完全没有响应，就检查地址和网络^[1]。

✘ Failed to connect 表示服务器没有响应，✘ Connection error 表示连接尝试本身报错。两种状态的排查方向不同，先分清楚是哪一种^[1]。服务器启动慢的话，调大启动超时。默认是 30 秒，MCP_TIMEOUT 以毫秒为单位设置。例如下面的命令允许 60 秒：

MCP_TIMEOUT=60000 claude

这个变量只作用于该命令启动的会话^[1]。

脚本和 CI 里要注意的地方

-p 运行无法弹出项目服务器的审批，所以要提前在设置里处理^[2]。stream-json 输出会把被跳过的 --mcp-config 条目记录在 system/init 事件的 mcp_server_errors 字段里，CI 任务可以读取这个字段，服务器没有加载时直接失败^[2]。