MCP（外部工具/数据）

MCP（Model Context Protocol）是一套开源标准，让 Claude Code 连接外部工具、数据库和 API，直接读取并操作这些系统而不用手动复制粘贴。

你的真实配置

你当前正在用 5 个 MCP server，全部由插件自带（plugin-provided scope），所以 ~/.claude.json 里看不到它们——它们随对应插件启用而连接：

MCP server	来自插件	干什么	代表性工具（真实工具名）
serena	`serena@claude-plugins-official`	语义级代码检索/编辑（LSP 式）	`find_symbol`、`find_referencing_symbols`、`replace_symbol_body`、`get_symbols_overview`
context7	`context7@claude-plugins-official`	查第三方库/框架最新文档	`resolve-library-id`、`query-docs`
playwright	`playwright@claude-plugins-official`	真浏览器自动化（E2E/抓取）	`browser_navigate`、`browser_click`、`browser_snapshot`、`browser_fill_form`
figma	`figma@claude-plugins-official`	设计稿读写/Code Connect	`get_design_context`、`get_screenshot`、`get_code_connect_map`
chrome-devtools	`chrome-devtools-mcp@claude-plugins-official`	性能/内存/LCP 调试	DevTools 协议相关工具

工具的完整名字格式是 mcp__plugin_<plugin>_<server>__<tool>，例如你环境里的：

mcp__plugin_serena_serena__find_symbol
mcp__plugin_context7_context7__query-docs
mcp__plugin_playwright_playwright__browser_navigate

关键点：因为你装了这么多 server，工具默认是 deferred（只加载工具名、不加载完整 schema），要用时才通过 ToolSearch 调入上下文——这就是为什么你接一堆 MCP 也不会撑爆上下文窗口（与「上下文管理」「提示词缓存」两节同一个道理）。

去真实体验（在你自己的 Claude Code 里敲）

想验证什么	这样做
看 5 个 server 连没连上、要不要认证	输入 `/mcp`
看某个 server 当前可用工具	`/mcp` 里展开，或让 Claude「列出 serena 的工具」
serena 实战：在你 SpringBlade 后端里找一个类/方法	先 `activate_project`，再「用 serena 找 `BladeUser` 这个符号的定义和所有引用」
context7 实战：查你前端栈最新文档	「用 context7 查 Vue 3 `<script setup>` 的最新写法」或「查 SpringBlade 4.7 的鉴权配置」
playwright 实战：测你本地前端	先 `pnpm dev` 起 :8000，再「用 playwright 打开 http://localhost:8000 登录页并截图」
这些 server 从哪来	`/plugin` 看已启用插件；它们随插件启用，不在 `~/.claude.json`

你没有项目级 .mcp.json。如果以后要给团队共享一个项目专属 server（比如连你们的 Nacos/数据库网关），就用 claude mcp add --scope project ...，它会写进项目根的 .mcp.json 入版本控制。

真实案例：serena vs 普通文件读取

你在改 SpringBlade 后端时，与其让 Claude Read 整个大文件再 grep，不如用 serena 的符号检索——它走 LSP，直接定位符号、列引用、按符号替换函数体，省上下文也更准：

# 低效：读整文件
Read blade-system/.../UserServiceImpl.java   → 几千行进上下文

# 高效：serena 语义检索
find_symbol "UserServiceImpl/getUser"        → 只取这个方法
find_referencing_symbols "getUser"           → 谁调用了它
replace_symbol_body "UserServiceImpl/getUser" → 精确替换函数体，不碰其它

这也呼应你 AGENTS.md 里「探索代码库用 Explore agent，不要 grep 全仓库」的约定——serena 是更强的语义版。

官方文档要点

以下为按官方文档整理的系统性参考。

是什么

MCP（Model Context Protocol）是一个面向 AI-工具集成的开源标准（modelcontextprotocol.io）。通过连接 MCP server，Claude Code 可以访问你的工具、数据库和 API——例如从 JIRA 读 issue、查 Sentry 错误、查 PostgreSQL 数据库、读 Figma 设计稿。连接方式分四种传输：远程 HTTP（推荐）、远程 SSE（已废弃）、本地 stdio（本地进程）、远程 WebSocket（持久双向连接，server 可主动推事件）。当你发现自己在反复从别的工具（issue tracker、监控面板）往对话里复制数据时，就该接一个 MCP server。

怎么工作

四种传输：HTTP（远程云服务首选，spec 名为 streamable-http）、SSE（已废弃）、stdio（本地进程，直接系统访问）、WebSocket（type:"ws"，持久双向连接，适合 server 主动推事件）。
WebSocket（Option 4）：只能用 claude mcp add-json 或 .mcp.json 配，接受与 http 相同的 url/headers/headersHelper/timeout/alwaysLoad 字段；认证仅支持 header（静态 token 或 headersHelper），不支持 OAuth，claude mcp add --transport 也不接受 ws——只需请求-响应就用 HTTP。
stdio server 启动时，Claude Code 会在其环境注入 CLAUDE_PROJECT_DIR（指向 project root），server 内用 process.env.CLAUDE_PROJECT_DIR / os.environ 读取；也可调 MCP roots/list 请求拿到启动目录。
配置按三个 scope 解析，同名 server 只连一次、取最高优先级来源的整条定义（不跨 scope 合并字段）。优先级：local > project > user > plugin-provided > claude.ai connectors。前三个按名字匹配重复，后两个按 endpoint(URL/command) 匹配。
Tool Search 默认开启：session 启动只加载 tool 名字，tool 定义延迟到 Claude 需要时通过 ToolSearch 搜索调入 context，所以加再多 server 对 context window 影响极小。
若请求需要某个仍在后台连接的 server，Claude 会等它连上；开启 tool search 时等待发生在 ToolSearch 调用内，否则（Vertex AI / 自定义 ANTHROPIC_BASE_URL / ENABLE_TOOL_SEARCH=false）用 WaitForMcpServers tool。
HTTP/SSE server 中途断开会自动重连：指数退避，最多 5 次，从 1 秒延迟开始每次翻倍；5 次失败后标记 failed，可在 /mcp 手动重试。stdio 是本地进程，不自动重连。
启动初连失败也用同样退避；v2.1.121 起对 5xx、connection refused、timeout 等瞬时错误最多重试 3 次（认证错误和 not-found 不重试）。
支持 MCP list_changed 通知：server 可动态更新 tools/prompts/resources，Claude Code 自动刷新，无需断开重连。
远程 server 返回 401 Unauthorized 或 403 Forbidden 时被标记为需认证，用 /mcp 走 OAuth 2.0 流程；token 安全存储并自动刷新。
MCP resources 用 @ 引用（@server:protocol://resource/path），引用时自动抓取并作为附件加入；MCP prompts 变成 slash command，格式 /mcp__servername__promptname。

怎么配置 / 用法

三种 scope 的存储位置：local 与 user 存在 ~/.claude.json（local 写在该 project 路径下的 mcpServers，user 跨所有 project），project 存在项目根的 .mcp.json（入版本控制、团队共享，首次使用需审批）。

添加命令（所有 options 必须在 server name 之前，再用 -- 分隔传给 server 的命令）：

HTTP: claude mcp add --transport http <name> <url>，加认证头 --header "Authorization: Bearer your-token"
SSE（已废弃）: claude mcp add --transport sse <name> <url>
stdio: claude mcp add [options] <name> -- <command> [args...]，例 claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server
JSON: claude mcp add-json <name> '<json>'
从 Claude Desktop 导入: claude mcp add-from-claude-desktop（仅 macOS / WSL）

scope: --scope local|project|user（local 为默认；旧版 local 叫 project、user 叫 global）。

.mcp.json 标准格式（stdio 例）：

json

{ "mcpServers": { "shared-server": { "command": "/path/to/server", "args": [], "env": {} } } }

HTTP 例（type 可写 http 或别名 streamable-http）：

json

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

env 变量展开支持 ${VAR} 和 ${VAR:-default}，可用于 command/args/env/url/headers；必需变量未设且无默认值会导致解析失败。

管理：claude mcp list / claude mcp get <name> / claude mcp remove <name> / 交互内 /mcp（认证、看状态、清除认证）。重置 project 审批：claude mcp reset-project-choices。把 Claude Code 自身当 server：claude mcp serve。

什么时候用

该用：当你反复从外部系统（issue tracker、监控面板、数据库、设计工具）往对话里复制数据时——接 server 让 Claude 直接读写。
该用 HTTP transport：连接云端远程服务（最广泛支持）。
该用 stdio transport：需要直接系统访问或自定义本地脚本的工具。
团队共享配置时用 --scope project（写进 .mcp.json 入版本控制）；个人跨项目工具用 --scope user；个人/含密钥/实验性配置用默认 local scope（不进版本控制）。
别用 SSE transport：已废弃，有 HTTP 的地方一律用 HTTP。
连接前务必确认信任该 server：会抓外部内容的 server 有 prompt injection 风险。
用 alwaysLoad: true 仅限每轮都要用的极少数 tool，因为每个 upfront tool 都占 context。

限制 / 坑

SSE transport 已 deprecated，有 HTTP 就别用 SSE。
stdio server 是本地进程，断开后不会自动重连（只有 HTTP/SSE 自动重连）。
project-scoped server（.mcp.json）出于安全每次使用前需审批，未批的在 claude mcp list 显示 ⏸ Pending approval，拒绝的显示 ✗ Rejected。
server name 'workspace' 为内部保留名，定义了会被跳过并警告改名。
同名/同 endpoint 的 server 只取最高优先级整条定义，字段不跨 scope 合并——容易误以为会合并。
MCP 输出超 10,000 tokens 会告警；默认上限 25,000 tokens，超限内容会落盘并替换为文件引用。
tool description 和 server instructions 各自在 2KB 处被截断，关键信息要放前面。
anthropic/maxResultSizeChars 注解的硬上限是 500,000 字符；且对返回 image 的 tool 无效，图片只能靠调 MAX_MCP_OUTPUT_TOKENS。
headersHelper 执行任意 shell 命令，10 秒超时、无缓存、每次连接都重跑；在 project/local scope 下需先通过 workspace 信任对话框。
OAuth 相关 flag（--client-id/--client-secret/--callback-port）只对 HTTP 和 SSE 有效，对 stdio 无效。
claude.ai connectors 仅在认证方式为 Claude.ai 订阅时加载；设了 ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN / apiKeyHelper 或用 Bedrock/Vertex 时不加载。
tool search 需要支持 tool_reference 的模型：Sonnet 4+ 或 Opus 4+，Haiku 不支持；Vertex AI 上需 Sonnet 4.5+ 或 Opus 4.5+。在 Vertex AI 及非一方 ANTHROPIC_BASE_URL 上默认关闭。
add 命令所有 options 必须在 server name 之前，否则会和 server 自身的 flag 冲突。
add-from-claude-desktop 仅支持 macOS 和 WSL；同名导入会加数字后缀如 server_1。
claude mcp serve 暴露的是 Claude Code 的 tools，单次 tool 调用的用户确认由你的 MCP client 负责实现。

硬事实速查（28 条）

三种 scope 存储：local→~/.claude.json（当前 project），project→项目根 .mcp.json（团队共享、入版本控制），user→~/.claude.json（跨所有 project）。
注意区分：MCP local-scope server 存 ~/.claude.json，而通用 local settings 存 .claude/settings.local.json（不是同一个）。
scope 优先级：1 Local 2 Project 3 User 4 Plugin-provided 5 claude.ai connectors。
传输类型（4 种）：http（推荐，别名 streamable-http）、sse（deprecated）、stdio、ws（WebSocket，仅 add-json/.mcp.json，header-only 认证）。
Channels（推送消息）：MCP server 声明 claude/channel capability、启动加 --channels flag，即可把 CI 结果/监控告警/聊天消息推进会话让 Claude 响应；用法见 /en/channels，自建见 /en/channels-reference。
核心命令：claude mcp add / add-json / add-from-claude-desktop / list / get <name> / remove <name> / reset-project-choices / serve。交互内 /mcp 与 /status。
--scope 取值：local（默认，旧名 project）/ project（旧名 global 是 user）/ user（旧名 global）。
stdio server 环境会被注入 CLAUDE_PROJECT_DIR（=project root）；plugin 配置可直接用 ${CLAUDE_PROJECT_DIR}，普通 .mcp.json 引用需给默认值如 ${CLAUDE_PROJECT_DIR:-.}。
env 展开语法：${VAR} 和 ${VAR:-default}；可展开位置：command、args、env、url、headers。
重连：HTTP/SSE 自动重连，指数退避，最多 5 次，初始 1 秒延迟、每次翻倍。stdio 不重连。
v2.1.121 起：初连瞬时错误（5xx / connection refused / timeout）最多重试 3 次；认证错误与 not-found 不重试。
超时：MCP_TIMEOUT 控制 server 启动超时（例 MCP_TIMEOUT=10000 = 10 秒）；.mcp.json 每 server 加 timeout 字段（毫秒，例 "timeout": 600000 = 10 分钟）覆盖 MCP_TOOL_TIMEOUT；小于 1000 取整为 1 秒；HTTP/SSE 首字节预算有 60 秒下限。
输出：超 10,000 tokens 告警；默认上限 25,000 tokens；用 MAX_MCP_OUTPUT_TOKENS 调整（例 MAX_MCP_OUTPUT_TOKENS=50000）。
server 作者可在 tool 的 tools/list 用 _meta["anthropic/maxResultSizeChars"] 提升单 tool 文本阈值，硬上限 500,000 字符；对 image 无效。
认证：401 或 403 触发标记需认证；支持 OAuth 2.0；/mcp 走流程，菜单内 Clear authentication 撤销；client secret 存 macOS keychain 或凭据文件，不进 config。
OAuth flag：--callback-port（固定回调端口，格式 http://localhost:PORT/callback）、--client-id、--client-secret（掩码输入），或环境变量 MCP_CLIENT_SECRET；只对 HTTP/SSE 有效。
OAuth 高级 .mcp.json oauth 字段：authServerMetadataUrl（需 v2.1.64+，必须 https）、scopes（空格分隔字符串，优先级最高）；默认发现链先查 RFC 9728 /.well-known/oauth-protected-resource 再 RFC 8414 /.well-known/oauth-authorization-server。
headersHelper：动态生成请求头，命令需向 stdout 输出 JSON 字符串键值对，10 秒超时、无缓存；注入 CLAUDE_CODE_MCP_SERVER_NAME 与 CLAUDE_CODE_MCP_SERVER_URL。
Tool Search 默认开启；ENABLE_TOOL_SEARCH 取值：unset（全部延迟）/ true（强制延迟，发 beta header）/ auto（装得下 10% context 就 upfront 否则延迟）/ auto:N（自定义百分比，N 0-100，如 auto:5）/ false（全部 upfront）。可在 settings.json env 设置，或用 permissions.deny ["ToolSearch"] 禁掉。
alwaysLoad：.mcp.json server 级字段（需 v2.1.121+，所有 transport 可用）或 tool _meta 内 "anthropic/alwaysLoad": true，让 tool 始终 upfront；设 true 还会阻塞启动直到连上，上限 5 秒连接超时。
MCP resources 引用格式：@server:protocol://resource/path，例 @github:issue://123、@docs:file://api/authentication。
MCP prompts 作为 command：/mcp__servername__promptname，参数空格分隔，例 /mcp__github__pr_review 456。
plugin 内 MCP 用 ${CLAUDE_PLUGIN_ROOT}（bundled 文件）、${CLAUDE_PLUGIN_DATA}（持久化状态）、${CLAUDE_PROJECT_DIR}；session 中改了 plugin 启停需 /reload-plugins。
禁用 claude.ai MCP server：ENABLE_CLAUDEAI_MCP_SERVERS=false claude；在 claude.ai/customize/connectors 添加（Team/Enterprise 仅 admin 可加）。
scaffold 自己的 server：/plugin install mcp-server-dev@claude-plugins-official，然后 /mcp-server-dev:build-mcp-server。
Claude Code 当 server：claude mcp serve，在 claude_desktop_config.json 配 command "claude" args ["mcp","serve"]，找路径用 which claude，否则报 spawn claude ENOENT。
Elicitation：server 可中途请求结构化输入（Form mode 表单 / URL mode 浏览器），无需配置自动弹窗；可用 Elicitation hook 自动应答。
企业集中管控见 Managed MCP：managed-mcp.json + allowedMcpServers / deniedMcpServers。

官方出处：https://code.claude.com/docs/en/mcp

MCP（外部工具/数据） ​

你的真实配置 ​

去真实体验（在你自己的 Claude Code 里敲） ​

真实案例：serena vs 普通文件读取 ​

官方文档要点 ​

是什么 ​

怎么工作 ​

怎么配置 / 用法 ​

什么时候用 ​

限制 / 坑 ​

硬事实速查（28 条） ​