Claude Code的MCP协议实现拆解:claude-code-source-code如何让AI Agent接入外部工具
Claude Code的MCP协议实现拆解:claude-code-source-code如何让AI Agent接入外部工具
Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手(AI Agent),它通过 MCP(Model Context Protocol,模型上下文协议)接入数据库、API、文件服务等外部工具。本文基于 claude-code-source-code 仓库,用通俗的方式拆解 Claude Code 的 MCP 协议实现原理、外部工具接入流程和常见排查方法,帮助新手快速理解 AI Agent 是如何"长出双手"的。
一、先搞懂 MCP:AI Agent 连接外部工具的"通用插座"
在 MCP 出现之前,想让 AI 使用某个外部工具(比如查数据库、调公司 API),开发者要为每个工具单独写一套对接代码,就像每个电器都配一种专用插头。
MCP 的解决思路类似 USB:
- 定义一套标准接口:外部工具按统一协议暴露自己的能力(工具、资源、提示词)
- AI Agent 只需实现一次协议:即可接入任意符合协议的工具,即插即用
MCP 的 3 个核心角色
| 角色 | 通俗类比 | 在 Claude Code 中的对应 |
|---|---|---|
| Host(宿主) | 电脑主机 | Claude Code 本体,负责发现并管理所有外部服务器 |
| Client(客户端) | 每根 USB 线 | Claude Code 内部与每个 Server 一一对应的连接对象 |
| Server(服务器) | 外设/插头 | 你配置的外部进程或远程服务,提供具体能力 |
一个 Claude Code 实例(Host)可以同时挂多个 Client,每个 Client 连接一个 MCP Server,互不干扰。
MCP 能带来哪些能力?
- Tools(工具):让模型主动调用外部能力,例如"查询订单表""调用部署脚本"
- Resources(资源):把文件、数据库记录等以标准形式提供给模型阅读
- Prompts(提示词):服务器可以内置好用的提示模板,供用户一键调用
二、claude-code-source-code 仓库结构速览
clone 本仓库后,你会发现它目前是一个指针仓库(pointer repository)——仓库本身只保留了说明文档,完整源码已经迁移到了独立的主仓库中。这个设计对新手其实是好事:入口文件极少,能快速定位到真正的源码所在。
git clone https://gitcode.com/gh_mirrors/cla/claude-code-source-code
仓库核心内容见 README.md,其中"Main Projects"表格(约第 27-35 行)列出了主工作仓库和完整源码仓库,研究 MCP 源码时请先按 README.md 的指引切换到完整源码仓库:
| 说明 | 用途 |
|---|---|
| Main working repository | 日常开发与调试的主仓库 |
| Full source code repository | 包含 Claude Code 完整源码的仓库,MCP 实现就在这里 |
| Multi-model project | 多模型工作流项目 |
💡 提示:指针仓库的价值在于"可发现性"——搜索 claude-code-source-code 时能直接找到入口,再顺着 README 跳转到真正承载代码的仓库。
三、Claude Code 接入一个 MCP Server 的完整流程
这是本文的核心部分。以最常见的 stdio(本地命令)方式为例,Claude Code 接入外部工具共经历 5 步:
第 1 步:声明服务器
用户通过配置文件或命令声明 MCP Server,告诉 Claude Code:"我要连一个服务器,启动命令是 xxx"。配置通常区分三种作用域:项目级(随仓库共享)、用户级(本机所有项目生效)、本地级(仅当前会话)。配置内容大致长这样:
{
"mcpServers": {
"my-db": {
"command": "npx",
"args": ["-y", "@example/db-mcp-server"]
}
}
}
第 2 步:启动进程,建立传输通道
Claude Code 按配置启动外部命令(stdio 传输),通过标准输入/输出与服务器通信;若是远程服务器,则走 HTTP 通道。这一步的关键是生命周期管理:Claude Code 退出时也要负责把子进程干净地回收,避免留下僵尸进程。
第 3 步:初始化握手
连接建立后,双方先交换"自我介绍":协议版本、各自支持的能力(capabilities)。这是典型的请求-响应 + 通知机制,握手成功后这条连接才算"激活"。
第 4 步:工具发现(tools/list)
Claude Code 向服务器请求工具清单,拿到每个工具的名称、描述和参数结构(JSON Schema)。这份清单会被注入到模型可见的工具列表中——模型"知道"自己能调用什么,全部来源于这里。
第 5 步:工具调用(tools/call)
模型决定使用某个工具时,Claude Code 把调用参数转发给 Server,Server 执行后把结构化结果回传,Claude Code 再将结果格式化后交还模型继续推理。至此,一次完整的"思考 → 行动 → 观察"闭环完成。
🔍 源码阅读技巧:在完整源码仓库中,按
mcp、tools/list、tools/call、initialize这类关键词全文搜索,即可快速定位到协议实现的核心模块。
四、3 种常见传输方式对比
| 传输方式 | 适用场景 | 特点 |
|---|---|---|
| stdio | 本地工具、脚本类服务 | Claude Code 直接拉起子进程,通过 stdin/stdout 通信,配置最简单 |
| SSE | 旧的远程服务器 | 基于 HTTP + 服务器推送事件,兼容性最好 |
| Streamable HTTP | 新版远程服务器 | 可流式返回结果,是当前推荐的远程方案 |
新手建议:本地小工具一律用 stdio;需要多机共享的能力(如团队知识库、内网 API)再用 HTTP 方式部署为远程 Server。
五、MCP 接入失败的 4 个常见原因与排查方法
遇到问题时,可以按下面的顺序逐条排查:
-
命令找不到(command not found) stdio 方式下 Claude Code 使用的 PATH 可能与你终端不同。先用绝对路径验证命令能否手动运行。
-
服务器启动了但没有响应(超时) 手动运行服务器命令,确认它不会卡在读输入或依赖交互式登录;查看 Claude Code 的 MCP 状态输出,确认连接是否处于已连接状态。
-
环境变量缺失 很多服务器依赖 API Key、数据库地址等环境变量。配置中未声明
env时,服务器进程拿不到这些值,会在初始化阶段直接失败。 -
配置作用域不对 项目级配置写错了文件位置(例如放进了不生效的目录)时,服务器根本不会被加载。检查配置是否出现在当前项目/作用域中即可确认。
⚠️ 一个通用原则:先让服务器脱离 Claude Code 独立跑通,再谈接入。80% 的"协议问题"其实是服务器自身没起来。
六、总结
- MCP 的本质:给 AI Agent 和外部工具之间定义"USB 标准",Host / Client / Server 三层角色各司其职
- 接入五步走:声明配置 → 启动进程 → 初始化握手 → 工具发现 → 工具调用
- 源码入口:本仓库是指针仓库,请通过 README.md 的 Main Projects 表格进入完整源码仓库,按
tools/list、tools/call等关键词搜索即可找到 MCP 实现 - 排错心法:先独立验证服务器,再排查传输方式与环境变量
理解了这套机制,你不仅能看懂 Claude Code 如何接入外部工具,还能自己写一个 MCP Server,把团队的任意内部系统挂到 AI Agent 上。