Claude Code的MCP协议实现拆解:claude-code-source-code如何让AI Agent接入外部工具

原创2026-10-23 11:45:101,821 阅读

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 个常见原因与排查方法

遇到问题时,可以按下面的顺序逐条排查:

  1. 命令找不到(command not found) stdio 方式下 Claude Code 使用的 PATH 可能与你终端不同。先用绝对路径验证命令能否手动运行。

  2. 服务器启动了但没有响应(超时) 手动运行服务器命令,确认它不会卡在读输入或依赖交互式登录;查看 Claude Code 的 MCP 状态输出,确认连接是否处于已连接状态。

  3. 环境变量缺失 很多服务器依赖 API Key、数据库地址等环境变量。配置中未声明 env 时,服务器进程拿不到这些值,会在初始化阶段直接失败。

  4. 配置作用域不对 项目级配置写错了文件位置(例如放进了不生效的目录)时,服务器根本不会被加载。检查配置是否出现在当前项目/作用域中即可确认。

⚠️ 一个通用原则:先让服务器脱离 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 上。

登录后查看全文
claude-code-source-code