Claude Code MCP

---

0. 定位声明

适用版本：Claude Code（2025年11月发布稳定版），MCP 协议规范 2025-03-26 及之后版本
前置知识：了解 JSON-RPC 基础、熟悉命令行操作、了解 Node.js 进程模型、具备 HTTP/API 基本概念
不适用范围：不涵盖 MCP 服务端开发；不适用于 Claude Desktop MCP 配置；SSE 传输方式将逐步废弃

---

1. 一句话本质

Claude Code MCP 就是给 AI 编程助手装上"插座"——你把各种外部工具（GitHub、数据库、Slack、Figma 等）做成"插头"（MCP Server），Claude Code 就能直接调用这些工具去完成工作，而不需要你手动复制粘贴数据。它解决的是"AI 只懂说话、但不会直接操作外部系统"的问题，让 Claude Code 能在一个对话里把整条开发工作流串起来。

---

2. 背景与根本矛盾

历史背景： 2024年前，每个 AI 工具接入外部服务都需要单独写集成代码。200个 AI 工具 × 50个数据源 = 10,000 种集成排列，碎片化且维护成本极高。2024年11月 Anthropic 开源 MCP，到2025年已成为 AI 工具集成的事实标准，社区构建了数千个 MCP Server。

根本矛盾（Trade-off）：

对立面	具体表现
灵活性 vs 安全性	MCP Server 可访问任意 API，灵活度极高；但也意味着恶意 Server 可能读取敏感数据。Claude Code 通过每次工具调用前请求用户确认来平衡。
上下文丰富度 vs Token 消耗	接入越多 Server，获取的外部信息越丰富；但工具定义本身消耗上下文窗口。当工具定义超过上下文 10% 时自动触发 Tool Search 延迟加载。
本地化 vs 团队共享	stdio 模式本地最简单安全；团队协作需要远程 Server，带来认证和网络配置复杂性。

---

3. 核心概念与领域模型

关键术语表：

术语	费曼式解释	正式定义
MCP	一套通用插头规范，让 AI 工具和外部系统能互相理解对方	Anthropic 发布的开放标准，定义 AI 应用与外部数据源/工具间的标准通信协议
MCP Server	把外部工具"翻译"成 AI 能理解的接口的小程序	实现 MCP 协议服务端的进程，向 Client 暴露 Tools、Resources、Prompts
MCP Client	AI 工具这一侧，负责发出请求并使用外部工具能力	在 Claude Code 语境下即 Claude Code 本身
Tool（工具）	MCP Server 能做的每一件具体的事	具有 JSON Schema 定义的输入/输出规范的原子操作单元
stdio	像父子进程通信一样，通过标准输入输出传消息	服务端作为 Claude Code 子进程运行的进程间通信模式
HTTP Streamable	通过 HTTP 双向传输，一个端点搞定所有通信（推荐方式）	MCP 2025-03-26 规范引入，使用单一 HTTP 端点支持双向流式通信
Tool Search	当工具太多装不下时，用到哪个再加载哪个	工具定义超过上下文 10% 时自动启用的智能延迟加载机制

领域模型：

Claude Code（MCP Client）
        │ JSON-RPC (stdio / HTTP Streamable)
        ▼
   MCP Server（Tools + Resources + Prompts）
        │ 原生 API 调用
        ▼
   外部系统（GitHub / PostgreSQL / Slack / Figma...）

配置作用域层级：

~/.claude/settings.json       ← user（跨项目全局）
[项目根]/.mcp.json            ← project（团队共享，提交 Git）
[项目本地]/.claude/           ← local（个人本地，不提交 Git）
优先级：local > project > user

---

4. 传输模式选型对比

特性	stdio	SSE（已废弃）	HTTP Streamable（推荐）
适用场景	本地工具、自定义脚本	远程服务器（旧）	远程服务器（现行标准）
延迟	50~150 ms	100~500 ms	100~300 ms
安全机制	进程隔离	HTTPS + Header	OAuth 2.0 / Bearer Token
团队共享	❌ 依赖本地环境	✅	✅
2026年推荐	✅ 本地优先场景	❌ 逐步废弃	✅ 远程集成首选

---

5. 工作原理

Session 启动时序：

1. 读取配置文件（三级合并）
2. 并行启动所有 MCP Server（stdio 子进程 / HTTP 连接）
3. 发送 initialize 请求，获取工具列表（stdio < 200ms，HTTP < 500ms）
4. 若工具定义 > 上下文 10%，启用 Tool Search 延迟加载
5. 就绪

工具调用时序（核心流程）：

用户输入 → Claude 意图识别 → 权限确认弹出 → 用户确认
→ JSON-RPC 请求发送至 MCP Server → Server 调用外部 API
→ 结构化响应返回 → Claude 自然语言回答

三个关键设计决策：

1. 为什么用 JSON-RPC 而不是 REST？ 工具调用是"动作导向"而非"资源导向"，JSON-RPC 的过程调用语义更自然；且支持同一连接多路复用，适合 stdio 持久连接场景。

2. 为什么每次调用都要用户确认？ MCP Server 能力上限等于其访问的外部系统权限。默认确认防止提示注入攻击，代价是操作摩擦，收益是安全边界清晰。可通过 permissions 配置特定工具自动审批。

3. 为什么设计三级作用域？ 解决"配置共享 vs 凭证安全"的矛盾：团队共享 Server 地址（project 作用域进 Git），每个人自己管理 API Token（local/user 作用域不进 Git）。

---

6. 可观测性与高可用

会话内诊断命令：

/mcp
# 输出：github: connected (stdio) - 23 tools available
#       notion: error (connection refused)

关键指标阈值：

指标	正常范围	异常信号
stdio 工具发现延迟	< 200 ms	> 500 ms 说明 Server 启动慢
HTTP 工具响应延迟	50~300 ms	> 1000 ms 需检查网络/Server 负载
MCP 输出警告阈值	< 10,000 tokens	超过此值 Claude Code 发出警告
MCP 输出默认上限	25,000 tokens	超过后输出被截断
工具定义上下文占比	< 10%	超过触发 Tool Search

---

7. 使用实践与故障手册

场景一：连接 GitHub（最常用配置）

# 环境：Node.js 18+，Claude Code 最新版
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token

# stdio 模式（本地）
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# 生产环境建议锁定版本，避免破坏性变更
claude mcp add github -- npx -y @modelcontextprotocol/server-github@1.2.3

claude mcp list  # 验证：github: connected (stdio)

场景二：PostgreSQL 数据库（生产级安全配置）

# ⚠️ 建议使用只读账号，防止误执行 DDL/DML
claude mcp add postgres \
  --env POSTGRES_URL="postgresql://readonly_user:pass@host:5432/db" \
  -- npx -y @modelcontextprotocol/server-postgres

场景三：团队共享配置

# project 作用域，生成 .mcp.json 提交进 Git
claude mcp add --scope project --transport http notion https://mcp.notion.com/mcp
# 每个成员自行配置 NOTION_TOKEN 环境变量，凭证不进版本控制

场景四：Windows 平台特殊处理

# 原生 Windows（非 WSL）必须添加 cmd /c 包装
claude mcp add --transport stdio myserver -- cmd /c npx -y @some/package

故障速查手册：

【故障1】Connection closed
现象：claude mcp list 显示 error: connection closed
原因：Node.js < 18 / Windows 未加 cmd /c / npm 网络不通
处理：node -v 确认版本；Windows 加 cmd /c；检查网络

【故障2】工具调用返回空或超时
原因：输出超过 25,000 tokens 被截断；外部 API 超时
处理：MAX_MCP_OUTPUT_TOKENS=50000 claude；在提示词中要求分批查询

【故障3】API 401/403
原因：环境变量未传递给子进程；Token 权限不足
处理：重新 claude mcp remove + add，用 --env 显式传入正确 Token

【故障4】上下文被占满
原因：注册了过多 MCP Server，工具定义超出上下文容量
处理：claude mcp remove 清理不用的 Server；依赖 Tool Search 机制

【故障5】提示注入攻击
原因：MCP Server 抓取了含恶意指令的外部内容注入对话
处理：立即中断会话；检查外部系统是否有未授权操作；
      预防：慎用 web scraping 类 Server，定期审查已安装 Server 来源

---

8. 性能调优

调优参数速查：

参数	默认值	推荐值	风险
MAX_MCP_OUTPUT_TOKENS	25,000	50,000（重型工作流）	过高耗尽上下文
MCP_TIMEOUT	⚠️存疑（官方未明确）	10,000 ms	过短导致频繁重启
ENABLE_TOOL_SEARCH	auto（10% 阈值）	auto:5（更激进）	过低频率增加延迟

调优优先级（按 ROI 排序）：

1. 精简 Server 注册数，只保留当前项目需要的
2. 锁定 npx 包版本，避免每次启动重新下载
3. 配置 Server 端分页参数，避免大结果集一次性返回
4. 使用 project 作用域精确到项目粒度

---

9. 演进方向

趋势1：HTTP Streamable 取代 SSE（中期影响）
MCP 2025-03-26 规范已将 HTTP Streamable 设为推荐，SSE 进入废弃周期。迁移：

# 旧：claude mcp add --transport sse my-server https://api.example.com/sse
# 新：claude mcp add --transport http my-server https://api.example.com/mcp

趋势2：Claude Code 作为 MCP Server（反向集成）
Claude Code 本身可作为 MCP Server 供其他 AI 工具调用，实现多智能体编排——外层编排 AI 调用 Claude Code 完成复杂编码任务，Claude Code 再调用各类工具，形成"AI 调用 AI"的分工协作工作流。

---

10. 面试高频题

【基础】MCP 和普通 API 调用有什么区别？
普通 API 每个 AI 工具需单独适配每个服务，N×M 种集成。MCP 是统一协议标准，只需 N+M 次实现，是接口标准化带来的乘数效应。

【原理】三级作用域设计解决了什么问题？
解决"团队共享配置 vs 凭证安全"矛盾：project 作用域（.mcp.json 进 Git）共享 Server 地址，local/user 作用域管理 API Token 不进版本控制。优先级：local > project > user。

【原理】Tool Search 机制是什么？
工具定义超过上下文窗口 10% 时自动启用，改全量加载为按需搜索加载。解决大型工作流中数百工具定义消耗大量上下文的问题。限制：需要 Sonnet 4 / Opus 4 以上，Haiku 不支持。

【生产】CI/CD 中 MCP 的三大安全风险？
①提示注入（外部内容诱导危险工具调用）→ 配置 allowedTools 白名单；②凭证泄露（API Token 被日志记录）→ 使用密钥管理服务；③不可控外部操作（创建 PR/发送消息等不可逆）→ CI 环境使用只读 Token。

---

11. 文档元信息

验证说明：
✅ 已核查官方文档：
   https://code.claude.com/docs/en/mcp
   https://modelcontextprotocol.io/introduction
   https://www.anthropic.com/news/model-context-protocol

⚠️ 未经本地验证，仅基于文档推断：
   - MCP_TIMEOUT 默认值（官方未明确标注毫秒数）
   - 并发调用上限（官方文档未说明）

参考资料：
- Claude Code MCP 官方文档：https://code.claude.com/docs/en/mcp
- MCP 协议规范 2025-11-25：https://modelcontextprotocol.io/specification/2025-11-25
- Anthropic 工程博客 Code Execution with MCP：https://www.anthropic.com/engineering/code-execution-with-mcp
- 社区 MCP Server 列表：https://github.com/modelcontextprotocol/servers

---