### [Claude Code接入MCP：添加、启用与排错](https://alyyhw.com/article/2055)

**Published:** 2026-07-13T04:40:41

**Author:** AI菜鸟网

**Excerpt:** 结合 Claude Code 官方文档，梳理本地、HTTP、JSON 配置和 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 会更省心。

## 推荐的验证步骤

1.  运行 \`claude mcp list\`，确认服务是否已登记。
2.  如果是项目级配置，检查是否处于 \`Pending approval\`。
3.  运行 \`claude mcp get \` 看详情，确认传输类型、URL 或命令是否正确。
4.  进入 Claude Code 会话，用 \`/mcp\` 查看当前状态。
5.  先做只读测试，例如列出工具或读取资源，再尝试高权限动作。

## 排错时要分层处理

如果连 \`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\`，而不是把密钥硬编码进版本库。

## 相关阅读

-   [Codex接入MCP服务：配置文件与验证步骤](/mcp-tutorials-04/)
-   [MCP认证怎么做？Token、Basic与OAuth入门](/mcp-tutorials-07/)
-   [MCP工具没有出现怎么办？完整排查清单](/mcp-tutorials-08/)

## 总结

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

**Tags:** Claude Code, JSON配置, MCP接入, 排错指南

**Categories:** AI编程, MCP教程

---