为什么 `.mcp.json` 里明明写了服务，却还是不能用？

常见原因是当前工作区尚未信任，服务还处于 `Pending approval`，或者 JSON 配置缺少 `type` 导致被错误解析。

Claude Code 里 `http` 和 `streamable-http` 有什么关系？

官方文档说明 JSON 配置中可以把 `streamable-http` 当作 `http` 的别名，用来兼容 MCP 规范文档里的命名。

新手该优先选哪种远程传输？

如果服务方提供 HTTP，优先选 HTTP。官方已经提示 SSE 弃用，WebSocket 则更适合特殊的实时推送场景。

Claude Code接入MCP：添加、启用、Pending approval与排错

Claude Code 是目前使用 MCP 比较积极的客户端之一，但它的接入方式也比很多人想象中更细：既有 `claude mcp add` 这种命令式接入，也支持 `.mcp.json`、`~/.claude.json` 和 `claude mcp add-json` 这类 JSON 配置方式；既支持本地 stdio，也支持 HTTP、SSE 和 WebSocket。很多排错问题并不是服务器本身坏了，而是你用错了传输类型、没有通过项目信任、或者把远程服务写成了没有 `type` 的 JSON 项。

先理解 Claude Code 的三种常见接入路径

第一种是命令行添加，适合快速试一个服务；第二种是 JSON 配置，适合团队共享或项目固定接入；第三种是在会话里通过 `/mcp` 查看和管理状态。官方文档非常强调：项目级服务器如果放在 `.mcp.json`，还会涉及审批和工作区信任，不是把文件提交进仓库就自动生效。这一点是很多新手最容易忽略的。

本地 stdio 服务怎么加

对本地服务，Claude Code 官方 quickstart 里给出的可复制示例是 `claude mcp add playwright — npx -y @playwright/mcp@latest`。这也说明了两个关键点：本地 stdio 默认不需要 `–transport`，而 `–` 之后的整段才是 Claude Code 真正拿来启动服务器的命令。很多人接入失败，就是因为把服务器参数写到了 Claude 自己的参数段里，或者忘了用双横线做分隔。只要服务需要访问本地项目、脚本或工具链，本地 stdio 依然是最稳的一类方案。

远程 HTTP 服务怎么加

远程 HTTP 服务同样有官方可复制示例：`claude mcp add –transport http claude-code-docs https://code.claude.com/docs/mcp`。如果服务需要登录或鉴权，再在此基础上补 `–header`、OAuth 相关参数，或者进入 `/mcp` 完成浏览器认证流程。官方文档同时提醒：SSE 已被标记为 deprecated，能用 HTTP 就优先用 HTTP；如果 `.mcp.json` 里写了 `url` 却没写 `type`，Claude Code 会把它当成错误配置跳过。

为什么会看到 Pending approval

这是 Claude Code 接入 MCP 很有代表性的一个状态。官方文档写得很明确：项目级 `.mcp.json` 里的服务器，如果还没被当前工作区批准，会在 `claude mcp list` 中显示 `Pending approval`。也就是说，配置文件存在，不等于服务已经启用。你需要在交互式会话里信任工作区并完成审批，相关状态才会变化。这个机制的意义在于避免仓库把高权限服务偷偷带进你的本地环境。

JSON 配置最容易踩的坑

有 `url` 但没有 `type`，结果被当成 stdio 错误处理。
把 `streamable-http`、`http`、`sse`、`ws` 混着写，却没搞清服务端真正支持哪种。
把认证头直接硬编码进共享文件，导致安全风险和团队协作问题。
以为提交 `.mcp.json` 后同事会自动生效，忽略了信任与审批流程。

SSE 和 WebSocket 还该不该用

Claude Code 官方文档已经明确提醒：SSE 传输已被弃用，能用 HTTP 就优先用 HTTP；WebSocket 适合需要持久双向连接、主动推送事件的场景，但它不适合当作新手默认选项。对绝大多数用户来说，如果服务方同时给了 HTTP 和 SSE，优先选 HTTP 会更省心。

排错时要分层处理

如果连 `claude mcp list` 都看不到服务，问题大多在配置层；如果能看到但状态异常，通常是审批、认证或传输层；如果状态正常却没有工具，要回头看服务器能力、过滤规则或工具描述。这样分层后，你就不会一碰到问题就重装客户端，或者反复修改并不相关的提示词。

别忽略工作区信任这一步

很多人以为项目级 MCP 配置的目标只是“方便团队共享”，却忘了共享本身也是安全边界。Claude Code 把审批和工作区信任放进流程里，目的是让你在真正启用前知道：这个仓库想让你的本地环境连接哪些服务、拿到哪些权限。站在使用者角度看，这一步也许多了几秒，但站在安全治理角度，它能挡掉很多误接入和暗中放权的风险。

一个符合当前官方结构的 .mcp.json 示例

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

这段 JSON 本身可以直接被 `JSON.parse` 解析，结构也和 Claude Code 官方 quickstart 一致：HTTP 条目用 `type + url`，stdio 条目用 `type + command + args`。其中 `${VAR}` 和 `${VAR:-default}` 是官方文档支持的环境变量展开写法，可放在 `url`、`headers`、`env`、`command` 或 `args` 里；真正要传 API Key 时，应按服务文档把值放进 `headers` 或 `env`，而不是把密钥硬编码进版本库。

总结

Claude Code 接入 MCP，核心不是背多少命令，而是分清四件事：你用的是哪种传输、配置写在什么范围、当前项目是否已经批准、以及服务的认证是否完成。把这四步理顺，绝大多数“加了却不能用”的问题都能快速定位。

Claude Code接入MCP：添加、启用与排错