首页 / Claude Code 入门教程 / MCP 集成

← 上一篇 下一篇 →
Claude Code 入门教程

MCP 集成

本教程共 34 篇 · 第 19 篇 · 更新于 2026-07-26 · 约 9 分钟阅读

Claude CodeClaude Code 入门教程MCPModel Context Protocol工具集成

19. MCP 集成

本节目标：搞懂 MCP（Model Context Protocol）是什么、为什么 Claude Code 需要它。学会用 claude mcp add 添加 HTTP、SSE、stdio 三种服务器，搞清三种配置范围（本地/项目/用户）怎么选，了解工具搜索怎么省上下文。学完你能把 Claude Code 连上数据库、工单系统、监控平台等外部工具，从”只能看本地代码”变成”全链路协作”。

MCP 到底解决什么问题

没有 MCP 之前，Claude Code 的能力被锁在你当前打开的项目文件夹里。它看不到你的 Jira 工单、查不了你的数据库、不知道 Sentry 上报了啥错误。你要让它干这些事，只能手动复制粘贴数据进对话框。

MCP（Model Context Protocol，模型上下文协议）是 Anthropic 推出的开放标准，专门解决这个痛点。它的核心思路是：别让 AI 去学所有工具的用法，而是让所有工具都提供一个统一接口给 AI。

打个比方：MCP 像现实中的通用插座。不用让每个电器适配不同插座，只要插座统一标准，所有电器都能直接用。Claude Code 装上 MCP 服务器后，就能直接读 Jira 工单、查 PostgreSQL 数据库、看 Sentry 错误、操作 Figma 设计。

连接 MCP 服务器后，你能让 Claude Code 干这些事：

  • 从 Jira 工单实现功能，再在 GitHub 上创建 PR
  • 分析 Sentry 和监控数据，定位生产错误
  • 查 PostgreSQL 数据库，找符合条件的用户
  • 基于 Figma 设计更新代码模板
  • 创建 Gmail 草稿，邀请用户参加反馈会

三种传输方式

MCP 服务器按运行位置分三种传输方式。选哪种看服务器是托管的还是本地的。

HTTP 服务器（推荐）

远程 HTTP 服务器是连接托管服务的推荐方式，云服务最广泛支持。

# 基本语法
claude mcp add --transport http <名字> <url>

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

# 带 Bearer 令牌认证
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

JSON 配置里 type 字段写 http（或 streamable-http，是别名，跟 MCP 规范一致，从服务器文档复制配置不用改）。

Warning

JSON 配置里没 type 但有 url 是配置错误—Claude Code 会把没 type 的条目当 stdio 服务器读。会跳过并报错让你加 "type": "http"。

SSE 服务器（已弃用）

SSE（Server-Sent Events）传输已弃用，能用 HTTP 就用 HTTP。

# 基本语法
claude mcp add --transport sse <名字> <url>

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

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

stdio 服务器（本地）

stdio 服务器在你机器上作为本地进程运行，适合需要直接系统访问或自定义脚本的工具。

# 基本语法
claude mcp add [选项] <名字> -- <命令> [参数...]

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

必须用 -- 分隔服务器参数。-- 把 Claude 自己的选项（--transport、--env、--scope）跟运行服务器的命令和参数分开。-- 之后的所有内容原封不动传给服务器。

  • claude mcp add --transport stdio myserver -- npx server 跑 npx server
  • 没 --，Claude Code 会把服务器的标志（如 --port）当自己的选项解析，报错。

Claude Code 在生成的服务器环境里设了 CLAUDE_PROJECT_DIR 指向项目根目录，你的服务器能用它解析项目相对路径。注意这变量在服务器环境里设，不是 Claude Code 自己的环境，所以 .mcp.json 里 ${VAR} 扩展引用它得带默认值：${CLAUDE_PROJECT_DIR:-.}。

WebSocket 服务器

WebSocket 保持持久双向连接，适合主动推送事件的远程服务器。只响应请求的服务器用 HTTP 更好—HTTP 支持 OAuth 和 claude mcp add --transport 标志，WebSocket 都不支持。

只能用 JSON 配置：

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

四步上手：添加、验证、使用、清理

以 Claude Code 文档 MCP 服务器为例（不用认证，适合测试）：

1. 添加服务器

在终端（不是 claude 会话内）跑：

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

命令拆开看：claude mcp add 注册服务器，--transport http 是托管 URL，claude-code-docs 是你起的名字，URL 是服务器地址。

2. 检查连接状态

claude mcp list

状态指示器含义：

状态含义
✓ Connected就绪
! Connected · tools fetch failed连上了但列不出工具，跑 claude mcp get <name> 看详情
! Needs authentication要浏览器登录或传 --header 令牌
✗ Failed to connect服务器没响应
⏸ Pending approval项目范围服务器还没批准

3. 在会话里用

claude
Use the claude-code-docs server to look up what MCP_TIMEOUT does

Claude 第一次调服务器时会问你要权限。批准后，工具调用标着服务器名字，你能确认答案来自 MCP 服务器而不是 Claude 的内置知识。

Tip

平时不用在提示里点名服务器，Claude 会自动选相关工具。点名是演示时为了确保走新服务器。

4. 删除服务器（可选）

claude mcp remove claude-code-docs

每个连上的服务器在上下文窗口里占点空间（工具名和说明加载进每个会话）。不用的删掉，保持上下文清爽。

管理服务器

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

# 看某个服务器详情
claude mcp get github

# 删服务器
claude mcp remove github

# 在会话里检查状态
/mcp

/mcp 面板在每个连上的服务器旁边显示工具计数，还会标记声称有工具功能但没公开任何工具的服务器。

自动重连

HTTP 或 SSE 服务器会话中途断了，Claude Code 自动用指数退避重连：最多五次尝试，从 1 秒延迟开始每次加倍。重连时服务器在 /mcp 里显示待处理。五次失败后标记为失败，你能从 /mcp 手动重试。stdio 服务器是本地进程，不自动重连。

启动时初始连接失败也用同样退避。瞬时错误（5xx、连接被拒、超时）最多重试三次；认证和未找到错误不重试—得改配置才能解决。

动态工具更新

Claude Code 支持 MCP list_changed 通知，服务器能动态更新可用工具、提示和资源，不用断开重连。

三种配置范围

添加服务器时用 --scope（或 -s）指定范围，控制服务器在哪加载、配不配共享：

范围加载位置跟团队共享吗存哪
local（默认）仅当前项目不~/.claude.json 该项目条目下
project仅当前项目是，通过版本控制项目根目录的 .mcp.json
user你的所有项目不~/.claude.json 顶级 mcpServers 键下

local：个人私有，仅此项目

默认范围。服务器只在你添加它的项目里加载，对你私密。个人开发服务器、实验配置、含不想进版本控制的凭证的服务器用这个。

# 默认就是 local
claude mcp add --transport http stripe https://mcp.stripe.com

# 显式指定
claude mcp add --transport http stripe --scope local https://mcp.stripe.com
Note

MCP 的”本地范围”跟一般本地设置不一样。MCP 本地范围存 ~/.claude.json（主目录），一般本地设置用 .claude/settings.local.json（项目目录）。

project：团队共享

通过项目根目录的 .mcp.json 文件共享，设计成检入版本控制，团队成员都能用同样的工具。

claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

生成的 .mcp.json：

{
  "mcpServers": {
    "paypal": {
      "type": "http",
      "url": "https://mcp.paypal.com/mcp"
    }
  }
}

出于安全，Claude Code 用 .mcp.json 里的项目范围服务器前会提示批准。要重置批准选择，跑 claude mcp reset-project-choices。

Warning

v2.1.196 起，克隆的仓库不能批准自己的服务器。提交到 .claude/settings.json 的 enableAllProjectMcpServers 或 enabledMcpjsonServers 在不受信任的文件夹里被忽略，服务器保持 ⏸ Pending approval 状态。得先信任工作区（跑 claude 接受信任对话框），才能批准。

user：个人私有，所有项目

claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

存在 ~/.claude.json 顶级 mcpServers 键下，你机器上所有项目都能用。

范围优先级

同名服务器在多个范围定义时，Claude Code 连一次，用最高优先级的定义（整个条目来自那个源，字段不跨范围合并）：

  1. 本地范围
  2. 项目范围
  3. 用户范围
  4. 插件提供的服务器
  5. claude.ai 连接器

.mcp.json 支持环境变量扩展

团队共享配置但敏感值（API 密钥、路径）因机器而异时，用环境变量扩展：

  • ${VAR} — 展开为环境变量 VAR 的值
  • ${VAR:-default} — 设了 VAR 就用 VAR，否则用 default

能扩展的位置：command、args、env、url、headers。

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

没设环境变量又没默认值，Claude Code 保留字面 ${VAR} 文本并报缺失变量警告。配置照样加载，你设好变量或加 :-default 回退，服务器就能用想要的值启动。

工具搜索：让上下文不被 MCP 吃光

每连一个 MCP 服务器，它的工具名和说明就加载进上下文窗口。连多了，光工具定义就占掉大半上下文。

工具搜索（Tool Search）解决这个：延迟工具定义，等 Claude 需要时再加载。会话启动时只加载工具名和服务器说明，加更多 MCP 服务器对上下文窗口影响最小。Claude Code 不对每个服务器设固定工具上限，实际限制是你的上下文窗口预算。

工具搜索默认开启。想基于阈值加载，设 ENABLE_TOOL_SEARCH=auto，工具在上下文窗口 10% 以内时预加载架构，只延迟溢出部分。

用 ENABLE_TOOL_SEARCH 环境变量控制：

值行为
true（默认）工具延迟，按需发现
auto阈值加载，能塞进 10% 上下文就预加载
false禁用，所有工具定义启动时全加载
Note

工具搜索需要支持 tool_reference 块的模型：Sonnet 4.5、Haiku 4.5、Opus 4.5 及更高。Google Cloud 的 Agent Platform 上默认禁用，ANTHROPIC_BASE_URL 指向非第一方主机时也禁用（多数代理不转发 tool_reference 块）。显式设 ENABLE_TOOL_SEARCH 覆盖回退。

也能单独禁用 ToolSearch 工具：

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

需要登录的服务器

很多托管 MCP 服务器要 OAuth 2.0 登录才能用。添加后，在会话里跑 /mcp，选要认证的服务器，浏览器会打开登录页。登录完，服务器就能用了。

# 添加需要登录的服务器
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
# 在会话里认证
/mcp

认证完就能直接问：

过去 24 小时内最常见的错误是什么？
显示我错误 ID abc123 的堆栈跟踪
Note

如果你配了 headers.Authorization 但服务器拒绝那个头，Claude Code 会报连接失败而不是回退到 OAuth。检查令牌对 MCP 端点是否有效，或删掉头用 OAuth 流程。

频道：让服务器主动推送

MCP 服务器还能直接把消息推进你的会话，让 Claude 对外部事件做反应—CI 结果、监控警报、聊天消息。服务器声明 claude/channel 功能，启动时用 --channels 标志选择加入。

这让 Claude Code 从”你问它答”变成”事件驱动”—Telegram 来消息、Discord 有聊天、webhook 触发，Claude 都能自动响应。

常用 MCP 服务器

服务器干啥添加命令
Claude Code 文档全文搜索官方文档claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
Notion读写 Notion 页面claude mcp add --transport http notion https://mcp.notion.com/mcp
Sentry查错误和堆栈claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
Playwright浏览器自动化claude mcp add playwright -- npx -y @playwright/mcp@latest
Airtable操作 Airtable 表claude mcp add --env AIRTABLE_API_KEY=KEY --transport stdio airtable -- npx -y airtable-mcp-server

在 Anthropic Directory 浏览已审核的连接器。Directory 连接器用跟 Claude Code 一样的 MCP 基础设施，列出的远程服务器都能用 claude mcp add 添加。

Warning

连接每个服务器前，验证你信任它。获取外部内容的服务器可能让你面临提示注入风险—服务器返回的内容里可能藏着恶意指令。

超时和输出限制

几个环境变量控制 MCP 行为：

变量作用示例
MCP_TIMEOUT服务器启动超时MCP_TIMEOUT=10000 claude 设 10 秒
MCP_TOOL_TIMEOUT工具执行超时（约 28 小时默认）每服务器可用 .mcp.json 里 timeout 字段覆盖（毫秒）
MAX_MCP_OUTPUT_TOKENS工具输出上限（默认 25000）MAX_MCP_OUTPUT_TOKENS=50000 提高
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT空闲超时（HTTP/SSE/WS 默认 5 分钟，stdio 默认 30 分钟）设 0 禁用检查

工具输出超 10000 token 时显示警告，默认限制 25000 token。

每个服务器的 timeout（至少 1000 毫秒）是每个工具调用的硬时钟限制，服务器发的进度通知不会延长它。HTTP/SSE/连接器服务器还有个每请求计时器（从请求到第一个响应字节），默认 60 秒。

插件提供的 MCP 服务器

插件能捆绑 MCP 服务器，启用插件时自动提供工具。跟手动配的服务器工作方式一样，但通过插件安装管理，不是 /mcp 命令。

插件 MCP 工具的名字格式是 mcp__plugin_<插件名>_<服务器名>__<工具名>。在权限规则、技能的 allowed-tools、子代理的 tools 字段、钩子匹配器里引用时，用这个完整名字。

好处是捆绑分发、自动设置、团队一致—装插件就拿到一样的工具。

安全要点

  • 信任验证：首次代码库运行和新 MCP 服务器要信任验证。用 -p 非交互模式时信任验证禁用。
  • 权限规则：能给 MCP 工具配权限。mcp__<服务器>__<工具> 格式，或用 mcp__* 匹配所有 MCP 工具。
  • 沙箱：MCP 工具的网络访问受沙箱网络隔离控制（如果开了沙箱）。
  • 提示注入：服务器返回的内容可能含恶意指令。WebFetch 用单独上下文窗口隔离，但 MCP 工具直接进主上下文。敏感操作靠权限规则兜底。

MCP 让 Claude Code 从”只能看本地代码”变成”全链路协作伙伴”。连上你常用的工具，Claude 就能直接读工单、查数据库、看监控、操作设计，不用你再来回复制粘贴。配好范围和权限，团队也能共享同一套工具配置。

上一篇
沙箱与安全
下一篇
子代理 subagents