本文目录

想让 Claude Code 查 issue、读数据库或访问监控服务，不必每次都把结果复制进对话。MCP 是开放的工具接入协议，服务器把相应能力交给 Claude Code 使用。能读什么、能改什么，取决于服务器提供的工具和你授予的权限。

第一次接入，最容易混在一起的是三个问题：地址或启动命令有没有登记、服务器能不能连上、工具有没有真的被调用。把这三步分开，比一次加很多服务更容易找出问题。我们暂时未实际运行这些示例。

先用文档服务器走完一遍

先安装 Claude Code 并完成它自身的登录，再在准备使用 MCP 的项目目录打开终端。空目录也可以。下面的命令要在终端执行，不要贴到已经打开的 claude 会话里：

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

这是官方 quickstart 用来演示首次连接的文档 MCP，提供 Claude Code 文档全文检索，不需要额外账号或 token。claude-code-docs 是你给服务器起的名字，不是固定关键字；--transport http 表示按 URL 连接托管服务，而不是在本机启动进程。

命令成功时会显示 Added ...，并用 File modified: 告诉你写入哪个文件。先别把它当作“接通了”：Added 只代表配置已保存，添加时不会替你验证凭证。接着执行：

bash
claude mcp list
claude mcp get claude-code-docs

文档服务器预期显示 ✔ Connected。再运行 claude，输入 Use the claude-code-docs server to look up what MCP_TIMEOUT does。这里特地点名，是为了让这次请求明确使用刚加的服务器。若出现工具权限提示，读清内容后再批准；看工具调用旁有没有服务器名，不要只凭答案像是对的就认定走了 MCP。

试完不想保留，可以运行 claude mcp remove claude-code-docs。每个服务器的工具名称和说明会占一些上下文，没用的服务器不用一直留着。

拿到的是 URL，还是一条启动命令？

先看服务提供方给的接入说明，再选传输方式。远程地址与本机命令不是同一种输入。

手上的配置通常怎么选需要注意
HTTPS MCP 地址HTTP，使用 --transport http优先选远程服务提供的 HTTP 接口
SSE 地址HTTP 自动回退，或 --transport sse自动回退需要 v2.1.265 或更新版本
npx、uvx 或可执行程序命令stdio启动命令完整放在 -- 后面
要主动推送事件的 WebSocket 地址JSON 的 "type": "ws"不接受 --transport ws，也不支持 OAuth

远程优先 HTTP。 JSON 中可以写 "type": "http"，也接受别名 "streamable-http"。只写 url 却省掉 type 会出错：Claude Code 把没有 type 的条目当成 stdio，因而跳过这条远程配置。

SSE 非推荐，但并非不能用。 官方标记为 deprecated，意思是有 HTTP 就优先 HTTP。Claude Code v2.1.265 起，--transport http 会先试 HTTP，对方不接受再改走 SSE；更早版本，或者明确要直接走 SSE，可以用 --transport sse。旧版请直接指定 SSE，不要依赖自动回退。

本地进程用 stdio。 官方 quickstart 的例子是 Playwright，需要 Node.js 18 或更新版本：

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

-- 后面的内容原样交给服务器启动命令。漏掉分隔符，服务器自己的选项可能被 Claude Code 当成自己的参数。第一次检查状态时，npx 可能还在下载包，出现失败可以等下载完成再查。选择包之前也要确认信任来源，因为这会在你的电脑上运行程序。

WebSocket 不等于普通远程 HTTP。 它适合服务器主动推事件；如果只是你发请求、服务回结果，HTTP 更直接。WebSocket 要通过 .mcp.json 或 claude mcp add-json 配置 "type": "ws"，认证只走请求头，可使用 headers 或连接时生成请求头的 headersHelper。claude mcp add --transport 不接受 ws，浏览器 OAuth 也不能套到 WebSocket 上。

local、project、user 选错，会像是配置丢了

传输方式决定怎么连接，作用域决定这份配置在哪儿生效。local 范围的 HTTP 服务器仍在远端，“local”不是“本机 stdio”的另一个名字。

作用域谁能用、在哪儿用配置位置
local，默认只有你，只在当前项目~/.claude.json 里这个项目的条目
project当前项目的使用者，可随仓库共享项目根目录 .mcp.json
user只有你，所有项目~/.claude.json 顶层 mcpServers

个人先试用选 local；团队要复用同一组服务选 project；你在不同项目都要用的个人工具选 user。MCP 的 local 配置不在 .claude/settings.local.json。Windows 的 ~/.claude.json 对应 %USERPROFILE%\.claude.json；设了 CLAUDE_CONFIG_DIR，则到指定目录下找 .claude.json。

作用域在添加时确定。要把刚才的文档服务器从 local 改成 user，先删原条目，再按新范围添加：

bash
claude mcp remove claude-code-docs --scope local
claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

共享给项目成员则改用 --scope project。同名服务器同时存在时，local 优先于 project，project 优先于 user；采用的是整条定义，不是把几份配置的字段拼起来。其他普通来源低于这三种作用域，组织通过 managedMcpServers 提供的定义则在 v2.1.259 起优先于它们。改了 URL 却没变化时，先确认实际生效的是哪一份，而不是反复修改被覆盖的配置。

手写 JSON 时，文件位置和外层键都要对

项目配置应放在仓库根目录 .mcp.json，不是 .claude/ 目录。只添加文档服务器可以写成：

json
{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    }
  }
}

外层键叫 mcpServers，不是其他客户端可能使用的 servers；把 mcpServers 放进 settings.json 也不会被读取。保存后退出并重开会话，Claude Code 在启动时读取 .mcp.json。

交互会话第一次使用项目级服务器，会要求批准。先检查仓库里给出的 URL 或启动命令再决定，不要因为文件随代码一起克隆下来就直接信任。关掉过批准提示，可以到 /mcp 处理；要重置之前的选择，使用 claude mcp reset-project-choices。非交互的 claude -p 无法弹出这种提示，会直接加载项目服务器，因此自动运行之前尤其要看过共享配置。

如果提供方只给了另一个客户端的 JSON，想改用 claude mcp add-json，应传入 mcpServers 里面单个服务器的定义，不要连最外层一起塞入。名称只用字母、数字、连字符或下划线。

登录要先分清 OAuth 与请求头 token

需要 OAuth 的远程服务，加完地址后显示 ! Needs authentication，往往只是提醒你还差登录一步。在 Claude Code 会话输入 /mcp，选服务器，再选 Authenticate，按浏览器提示完成授权。也可以在有交互终端的 shell 运行 claude mcp login <name>，把 <name> 换成刚才登记的名称。

浏览器没有自动打开，可以使用 Claude Code 显示的授权 URL。若授权后浏览器回跳失败，按 Claude Code 的提示粘贴地址栏中的完整回调 URL，不要把这个 URL 发进工单或聊天。claude -p 没有 /mcp 面板，应该先在交互会话或通过登录命令完成认证，再启动非交互任务。

另一类服务要求固定 token，通过 --header 添加。以下地址、名称和 token 都是占位示例，需要换成服务提供方给你的值，不能原样当作可用凭证：

bash
claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer your-token"

不要把真实 token 提交进共享配置。JSON 可以引用环境变量，例如 "Authorization": "Bearer ${API_KEY}"，API_KEY 是你为这个服务器单独准备的变量。检查粘贴内容有没有首尾空白或换行，这类隐藏字符会导致认证失败。

已经配置了 Authorization 请求头，连接时却被服务端以 401 或 403 拒绝，Claude Code 会显示连接失败，不会自动回退到 OAuth。该修的是这份请求头凭证；如果本来想走 OAuth，就先去掉手写的头。反复点浏览器登录，不会让错误的固定 token 变正确。

按状态排查，不要一上来就加超时

先用 claude mcp list 看当前项目的服务器状态，再用 claude mcp get <name> 看指定服务器。会话内也可以打开 /mcp。

完全没有服务器。 确认终端当前所在项目与添加时一致。默认 local 只跟当时的项目绑定，不在 Git 仓库里则跟当时的精确目录绑定。再查文件位置、JSON 语法和解析警告；坏掉的一条会被跳过，不代表整份文件都没读。

停在批准或被策略阻止。 Pending approval 要在交互会话里审阅并批准。企业策略拦截则要找管理员了解原因，调大超时解决不了权限问题。

Failed to connect。 先读状态后的 HTTP 状态码或失败详情，再用 get 查看完整 URL，特别是 MCP 路径。网站首页能打开，不代表配置的 MCP 地址正确。若是 Connection error，这个状态不会附上详情，需要继续检查网络或本机命令。

远程可按 quickstart 建议，用 curl -I <url> 看是否有响应；PowerShell 用 curl.exe，避免命中别名。404、405 仍说明主机有响应，部分 MCP 端点只接受 POST；这不等于路径正确或 MCP 协议已接通。401、403 指向认证，完全无响应则先查地址和网络。

stdio 启动失败。 把配置的命令与提供方说明对照，确认运行时已安装、没有漏 --。command、args 中的相对路径以启动 Claude Code 的目录为基准，不以 .mcp.json 所在位置为基准；本地脚本尽量写绝对路径，npx、uvx 这类在 PATH 上的命令可以保留原样。还要确认没有使用会禁用 MCP 的 --safe-mode。

启动超时。 默认启动时限是 30 秒。首次 npx 下载可能更慢，Bash、Zsh 可以用 MCP_TIMEOUT=60000 claude 放宽到 60 秒；PowerShell 用 $env:MCP_TIMEOUT = "60000"; claude。单位是毫秒。参考文档的 MCP_TIMEOUT=10000 claude 只是设成 10 秒的例子，不是默认值。v2.1.299 之前，一些实际仍在运作的 HTTP 服务器可能不受这个设置影响仍启动超时；符合这种情况就应更新 Claude Code，而不是不断加大数字。

连接了却没有工具。 在 /mcp 看工具列表，检查服务器要求的环境变量，再选 Reconnect。仍为空可以运行 claude --debug=mcp，在 ~/.claude/debug/ 下查看服务器 stderr，分享日志前移除秘密信息。连接状态只说明连接这一层，不保证服务器列出了你想要的工具。

接通后，也别一次放开所有权限

先确认服务器可信，再从一个小任务开始。会拉取外部内容的服务器可能带来提示注入风险，涉及写入、删除或外发的工具尤其要看清权限。MCP 也不会绕过 Claude Code 用量限制。

若下一步关心长任务怎么运行、任务途中如何要输入，可以再看 MCP Tasks 与任务中途提问；那是接入之后的使用方式，不是首次登记服务器的步骤。