用法

Claude Code MCP 配置教程：添加、共享和排查 MCP 服务器

发布于 2026 年 10 月 30 日 · 最后核对 2026 年 10 月 30 日

MCP（Model Context Protocol）是连接 AI 工具的开源标准，MCP 服务器能让 Claude Code 直接读写你的工具、数据库和 API，不用再把数据复制进对话。这一页是添加 MCP 服务器的操作步骤：三种连接方式各用哪条命令、配置存在哪里、怎么和团队共享、怎么认证、出错了看什么。内容按 Anthropic 的 Connect Claude Code to tools via MCP 中文整理，2026 年 10 月 30 日对照原文核对。

MCP 是什么，什么时候该接

MCP 服务器让 Claude Code 能访问你的工具、数据库和 API。当你发现自己在把另一个工具里的数据（比如工单系统或监控面板）复制进对话时，就适合接一个服务器：接上之后，Claude 可以直接读取、操作那个系统，不用再依赖你贴过来的内容。

安全提醒：连接任何服务器之前，先确认你信任它。会抓取外部内容的服务器可能让你暴露在提示词注入风险下。

三种连接方式怎么添加

所有方式都用 claude mcp add。先看服务器给的是什么：一个 https:// 地址是远程服务器，一条 npx 之类的启动命令是跑在你本机的服务器。

远程 HTTP 服务器

# 基本写法
claude mcp add --transport http <name> <url>

# 官方示例：连接 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带 Bearer token 的示例
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

在 JSON 里配置时，type 字段可以写 streamable-http，它是 http 的别名。有 url 却没有 type 的条目是配置错误，因为 Claude Code 会把没有 type 的条目当成 stdio 服务器，并跳过它。

远程 SSE 服务器

SSE（Server-Sent Events）传输已弃用，有 HTTP 的地方请用 HTTP。有些服务仍然只提供 SSE 端点：这时仍然用上面的 claude mcp add --transport http <name> <url>，Claude Code 会先尝试 HTTP，服务器不接受时自动切到 SSE。这个自动切换需要 Claude Code v2.1.265 或更高版本。更早的版本，或想直接用 SSE，传 --transport sse：

# 基本写法
claude mcp add --transport sse <name> <url>

# 官方示例：连接 Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 带认证 header 的示例
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

本地 stdio 服务器

stdio 服务器作为本地进程运行在你的机器上。

# 基本写法
claude mcp add [options] <name> -- <command> [args...]

# 官方示例：添加 Airtable 服务器
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• --（双横线）把 Claude 自己的选项（比如 --transport、--env、--scope）和启动服务器的命令分开，-- 之后的内容原样交给服务器。不写 --，Claude Code 会把服务器的参数（比如 --port）当成自己的选项去解析。
• claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 会运行 python server.py --port 8080，并把 KEY=value 放进环境变量。
• --env 可以接多个 KEY=value。如果服务器名紧跟在 --env 后面，命令行会把名字当成又一对参数而报错，所以在 --env 和服务器名之间至少放一个别的选项，比如 --transport stdio。

从别的客户端的安装说明改写

服务器的安装说明可能是为 Claude Desktop、Cursor 或其他 MCP 客户端写的，没有 claude mcp add 命令。这时在说明里找一个 URL、一条启动命令或一段 JSON：

• URL（例如 https://mcp.example.com/mcp）：远程服务器，用 claude mcp add --transport http example https://mcp.example.com/mcp。
• 启动命令（例如 npx -y @example/mcp-server）：跑在本机，把整条命令放在 -- 后面：claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server。
• mcpServers JSON 块：把 mcpServers 里面的对象（不含外层）交给 claude mcp add-json：

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

用 add-json 时，没有 type 的 url 条目要先补上 "type": "http"、"type": "sse" 或 "type": "ws"。WebSocket 服务器只能用 .mcp.json 或 claude mcp add-json 配置，claude mcp add --transport 不接受 ws。服务器名只能包含字母、数字、连字符和下划线。

作用域：配置存在哪里

MCP 服务器有三个作用域，决定它在哪些项目里加载，以及配置是否和团队共享。用 -s 或 --scope 选择，默认是 local。

# local 作用域（默认）
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

# project 作用域
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# user 作用域
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

local 作用域的服务器存在 ~/.claude.json 里该项目路径下，不会出现在你的其他项目里，适合个人开发服务器、实验性配置，以及带凭据、不想进版本控制的服务器。注意，这里的 “local” 和一般设置里的 .claude/settings.local.json 不是一回事。

同一个服务器在多个地方定义时，Claude Code 只连一次，用优先级最高的那份，整条配置原样采用，不会跨作用域合并字段。优先级从高到低：local、project、user、插件提供的服务器、claude.ai 连接器。

用 .mcp.json 和团队共享

project 作用域把配置存进项目根目录的 .mcp.json。添加 project 作用域的服务器时，Claude Code 会自动创建或更新这个文件。把它提交进版本控制，团队里每个人都会得到同样的 MCP 工具。

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

出于安全考虑，交互会话在使用 .mcp.json 里的服务器之前会先请你批准。想重置这些批准的选择，运行 claude mcp reset-project-choices。

在 .mcp.json 里用环境变量

.mcp.json 支持环境变量展开，团队可以共享同一份配置，而每台机器上不同的路径和 API key 这类敏感值留在各自的环境里。可以在服务器的 command、args、env、url 或 headers 里引用：

• ${VAR}：展开为环境变量 VAR 的值。
• ${VAR:-default}：VAR 已设置时取它的值，未设置时取 default。

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

引用的变量没设置又没有默认值时，配置仍会加载，Claude Code 在 claude mcp list 里给出缺少变量的警告，并按字面使用未展开的 ${VAR}。在远程服务器的 url 和 headers 里，ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 这类凭据变量会被读成空值，不会展开。要给服务器这类凭据，先把它复制到一个自己命名的变量里，再引用这个变量。

查看、检查和删除服务器

# 列出所有已配置的服务器
claude mcp list

# 查看某个服务器的详情
claude mcp get notion

# 删除服务器
claude mcp remove notion

# （在 Claude Code 里）查看服务器状态
/mcp

claude mcp add 成功时会打印一行 Added ...，表示配置已写入；它不验证凭据，所以填一个占位的 token 也会通过，但之后连接会失败。要确认 Claude Code 真的连上了，运行 claude mcp get <name>，或在 Claude Code 里运行 /mcp，看那个服务器那一行有没有对勾。

claude mcp list 在每个服务器旁边显示健康状态：

删除远程服务器时，Claude Code 会同时删掉它为该服务器保存的 OAuth 令牌和客户端注册，但不会去授权服务器上吊销令牌。如果授权服务器支持吊销，先在 shell 里运行 claude mcp logout <name>，再运行 claude mcp remove <name>。

想暂时停用而不删除配置，在 /mcp 面板里把服务器关掉，Claude Code 就不再连接它，配置保留。

远程服务器的认证

很多云端 MCP 服务器需要认证，Claude Code 支持 OAuth 2.0。服务器返回 401 Unauthorized 或 403 Forbidden 时，Claude Code 会把它标成需要认证。

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

然后在 Claude Code 里运行 /mcp，按浏览器里的步骤登录。

• 认证令牌会被安全保存并自动刷新。
• 在 /mcp 菜单里选 “Clear authentication” 可以撤销访问。
• 浏览器没有自动打开时，复制给出的 URL 手动打开。
• 认证后浏览器重定向报连接错误时，把浏览器地址栏里完整的回调 URL 粘贴到 Claude Code 弹出的 URL 提示里。
• OAuth 认证适用于 HTTP 服务器。

不想进会话，可以直接在 shell 里登录：

claude mcp login sentry

清除已保存的凭据用 claude mcp logout <name>。在 SSH 会话或没有显示服务器的 Linux 上，claude mcp login 检测到没有本地浏览器，会打印授权 URL 而不是去打开浏览器：在你本机打开这个 URL，再把浏览器地址栏里完整的重定向 URL 粘贴回提示处，这一步需要交互终端，所以用 ssh -t 连接。加 --no-browser 可以强制使用 URL 提示。

如果你给服务器配置了 headers.Authorization 而服务器拒绝了它，Claude Code 会报连接失败，不会退回到 OAuth。检查令牌对这个 MCP 端点是否有效，或者删掉这个 header 改走 OAuth 流程。claude -p 和 Agent SDK 运行里没有 /mcp 面板，需要先在交互会话里（或用 claude mcp login <name>）完成登录。

超时和输出限制

• 启动超时用 MCP_TIMEOUT 环境变量设置，例如 MCP_TIMEOUT=10000 claude 是 10 秒。
• 给某个服务器设置单次工具调用的超时：在它的 .mcp.json 条目里加一个以毫秒为单位的 timeout 字段，例如 "timeout": 600000 是十分钟。它只对这个服务器覆盖 MCP_TOOL_TIMEOUT 环境变量。
• MCP 工具输出超过 10,000 token 时 Claude Code 会警告，默认上限是 25,000 token。要调高，在启动 Claude Code 之前设置 MAX_MCP_OUTPUT_TOKENS：

export MAX_MCP_OUTPUT_TOKENS=50000
claude

警告阈值是固定的。成功的文本结果超过 50,000 个字符时，无论这个变量设多少，都会被保存到文件里（除非服务器自己调高了该工具的上限）。

常见问题排查

常见问题

来源

• Claude Code：Connect Claude Code to tools via MCP（claude mcp add、作用域、.mcp.json、认证、输出限制，2026 年 10 月 30 日核对）