MCP协议架构与原语实战：从零实现Server到多客户端接入

做Agent开发这段时间我最大的感受是工具接入正在从每个Agent一套API走向一套协议走天下。你去看各个大模型客户端的设置页Claude Desktop、Cursor、Trae、Cherry Studio这些都有统一的MCP配置入口说明大家已经不再争论要不要接MCP了而是直接进入怎么把MCP用扎实的阶段。这篇文章就围绕MCP协议本身的架构分层和几个核心原语展开把我自己从零实现一个MCP Server、再把它接到不同客户端里的过程完整拆开讲一遍包括那些踩过的坑和排查思路希望能给正在肝Agent项目的朋友省点时间。1. MCP协议的出现背景Agent工具接入的战国时代该结束了1.1 我在实际项目里遇到的碎片化痛点在做Agent应用之前我维护过几个内部自动化工具它们分别服务不同的模型编排框架。每个工具都要单独处理函数调用Function Call解析、参数校验、结果回传、错误处理等于同一个逻辑写了三遍。更麻烦的是当这些工具要同时暴露给多个客户端使用时——比如既要在命令行里跑又要通过Web界面操作还要让智能体在会话中自动调用——接口格式稍微不一致联调成本就成倍上涨。这其实就是MCP出现之前工具调用的真实状态模型要干活就得为每个工具定制一套接入方式工具要升级所有对接方都要跟着改新工具想接入生态得先看对方用什么协议、什么SDK。你可以把它想象成每个家电都配一个专属遥控器桌面上堆满了遥控器谁来了都得先学一遍怎么按。MCP要解决的就是一个遥控器控制所有家电的问题。1.2 MCP的协议出发点和设计哲学MCPModel Context Protocol模型上下文协议由Anthropic在2024年底开源定位是模型与外部工具、数据源之间的通用语言。它在设计上借鉴了很多成熟的通信协议思路比如LSPLanguage Server Protocol的架构模型。LSP当年统一了编辑器与语言服务器之间的交互方式MCP则把这个思路搬到了模型与工具之间客户端负责发现能力服务端负责提供能力两边通过标准化的消息格式对话。协议本身基于JSON-RPC 2.0作为消息帧JSON-RPC的好处是轻量、无状态、容易实现几乎没有学习门槛。MCP在设计上非常克制它不规定工具要怎么写业务逻辑只规定工具如何被描述、如何被调用、结果如何返回。这种管连接不管业务的设计哲学让MCP能够在一个相对精简的规范内保持极高的扩展性。1.3 Host、Client、Server三层角色到底怎么分工MCP协议中最重要的架构概念是三个角色。Host是用户直接面对的应用程序比如Claude Desktop、Cursor、VS Code插件、我们自己的Agent应用它负责管理用户会话、决定什么时候调用工具、展示工具返回的结果。Client是Host内部与某个MCP Server建立连接的组件一个Host可以同时管理多个Client每个Client对应一个独立的Server连接。Server是暴露工具、资源、提示词模板的服务进程它可以是本地的子进程也可以是远程的HTTP服务。我最初对这三层有点绕后来用一个比喻就理顺了Host是公司前台Client是前台分配给访客的接待员Server是各个部门的负责人。访客模型有问题前台把任务分配给对应接待员接待员再去找对应部门的负责人拿到答复。每个接待员只对接一个部门但前台可以管理很多接待员。在实现层面Host和Client通常是同一个进程内的代码逻辑但开发MCP Server的时候必须清楚我写的这个进程到底是被谁拉起、由谁管理生命周期这是后面排查很多问题的关键。2. MCP的架构关键链路从连接建立到一次消息请求的完整传递2.1 初始化握手与能力协商不是连上就能聊MCP的会话建立不是简单的TCP连接建立。客户端发起连接后第一件事是发送initialize请求携带协议版本号、客户端能力声明、客户端识别信息。服务端收到后需要确认协议版本是否兼容同时返回服务端的能力声明和识别信息。这个阶段的目的是让双方在正式通信之前就知道对方会什么。我在自己实现Server时一开始漏掉了能力协商的响应处理结果Claude Desktop连上后没有任何提示只是所有工具调用都超时。后来抓日志才发现客户端一直在等我返回capabilities字段我返回了空对象客户端认为服务端不支持任何能力干脆就不发后续请求了。这里要特别注意initialize阶段返回的capabilities不只是一种声明它还起着开关的作用。比如支持工具的Server要返回tools字段支持资源读取的要返回resources字段字段不全或者格式不对对应功能就是不可用。2.2 通信的消息结构JSON-RPC 2.0的请求、响应与通知握手完成后双方进入正常消息阶段。MCP的消息类型分为请求Request、响应Response和通知Notification三类。请求必须带有id响应通过匹配同一个id来对应请求通知没有id也不需要对方回复。这种设计非常像HTTP的请求响应模型加上WebSocket的双向推送简单但够用。在封装SDK时我最开始没搞清楚响应和主动推送的区别把服务端的日志通知也写成带id的请求结果客户端一直在等待响应服务端又没收到后续请求整个会话就卡死了。教训是需要对方回执的才用请求-响应模式像日志、进度这类单向消息用Notification即可这样协议层才不会被无效的等待阻塞。2.3 Transport传输层的取舍本地用stdio远程用HTTP/SSEMCP目前最常用的两种传输方式是标准输入输出stdio和HTTP SSEServer-Sent Events。stdio模式适合本地的进程间通信Host或Client在本地启动一个MCP Server子进程通过进程的标准输入和标准输出传递JSON-RPC消息。它的优势是无需网络端口、安全性高、延迟低在Claude Desktop这类桌面应用里跑本地文件工具非常合适。HTTPSSE模式则适合远程服务Client通过HTTP向Server发送post请求通过SSE持续接收Server推送的事件。SSE很多人不熟悉简单说就是一种服务端向客户端单向推流的机制比WebSocket更轻量浏览器原生支持不需要额外的心跳和重连逻辑。在选择传输方式时我的建议是优先使用各语言SDK内置的传输适配层先跑通stdio再考虑远程化远程化时要注意SSE事件流可能需要配合代理层处理超时缓冲尤其是工具执行耗时超过60秒的场景默认的SSE连接很容易被网关断开。3. MCP原语拆解Tools、Resources、Prompts各自的职责边界3.1 Tools原语让模型能动手干活的关键操作MCP协议中我最常接触的原语是Tools。一个Tool其实就是模型可以调用的一个函数但它不是普通函数它必须按照协议要求提供结构化的描述信息名称、功能说明、输入参数JSON Schema、输出结果。模型在工作时会根据系统提示中的工具清单决定调用哪个工具、传什么参数然后把返回结果作为后续推理的依据。这里有几个容易踩的细节。第一个是工具描述一定要详细。很多刚开始写MCP Server的人用一句话描述工具模型经常选错工具或者不调用。我在一个文件操作工具里把描述写了三行明确说明该工具用于以UTF-8编码读取本地文本文件适用于读取配置、日志、源码文件不适用于二进制文件实测下来模型调用准确率明显提升。第二个是参数Schema的严格程度要适度。过度使用required字段会导致模型传参困难过度宽松又会让工具收到缺字段的参数。我的经验是必要字段用required可选字段给默认值枚举用enum约束而不是让模型自由发挥。3.2 Resources原语给模型提供可供读取的上下文素材Resources表示可以被读取的外部数据源比如一个本地文件的URI、一份数据库查询结果、一个API返回的json。模型的上下文窗口有限它不可能把所有数据都装进对话里通过Resources原语模型可以在需要时主动读取指定URI的内容相当于给模型开了一扇按需取数的门。Resources与Tools最大的区别是Tools是动作会产生副作用或结果Resources是素材只负责提供数据。在设计Server时应该把这两个原语的边界划清楚。比如一个项目文档工具文档列表、文件内容用Resources提供文档搜索、文档转换用Tools提供。实际使用中我发现客户端的UI对Resources和Tools的展示策略也不同Resources通常呈现为可浏览的资源列表Tools则整合进模型的可用函数列表混用会导致体验不一致。3.3 Prompts原语把复杂任务的模板固化下来Prompts原语是MCP协议里比较有特色的一个它提供了一套可复用的提示词模板。与客户端自身的系统提示词不同Prompts通常与特定的工具或数据源绑定当用户从MCP Server获取一个Prompt模板时模板内可以包含占位参数由客户端在应用时填充。我写过的一个例子是代码评审Prompt它接收分支名称和评审重点两个参数渲染后的模板会引导模型依次检查这个分支的改动、潜在风险、测试覆盖情况最后按固定格式输出评审报告。如果没有Prompts原语这些模板就得硬编码在客户端代码里换一个客户端就维护一套。有了Prompts模板跟着Server走业务逻辑和提示策略就完成了分离。这种模式在团队内部分享提示词时特别有用把组织内部的做事方法沉淀成了可调用的资产。3.4 三个原语如何协同以及它们与Messages/Sampling的关系在一次真实的任务中三个原语常常是配合使用的。比如用户要求分析这份项目日报并生成新一周计划流程可能是模型先通过Resources读取日报文件内容再调用Tools执行数据统计逻辑最后参考Prompts提供的周报模板生成回复。MCP协议允许客户端在实现上对原语进行组合和编排这比让模型自由出生地调用更可控。另外协议中还提到了Sampling机制即服务端可以请求客户端让模型生成内容。这是一种反向的能力调用我的理解是它为场景化的Agent间通信预留了接口但在实际项目中用得不多因为多数场景下模型都由Host侧统一管理Server侧再反过来请求模型会引入复杂的鉴权和成本控制问题。我做项目时没有落地Sampling因为涉及费用归属和责任边界团队讨论后决定先保持Server的纯能力提供方定位这一点供大家参考。4. 从零搭建一个MCP Server我用Python走通的完整过程4.1 环境准备与SDK选型我用的语言是PythonMCP官方提供了mcp Python SDK安装很方便。当前生态里还有TypeScript SDK和Java SDK选型时主要看团队技术栈。在Python项目里我推荐使用uv这个包管理器来管理依赖和虚拟环境因为最终Server需要以独立进程方式启动依赖隔离很重要。在动手之前先明确需求我要做一个操作git仓库的Server它暴露两个工具一个是查看当前分支状态另一个是获取最近几条提交记录。选这个场景是因为它足够简单又不脱离真实需求适合作为MCP Server的入门样例。回到人群里很多人问mcp是什么我给他们的回复是你只要记住三件事它定义了工具怎么描述、模型怎么调用工具、结果怎么回传这三件事的规范就是MCP的全部核心。框架层的东西再多也都是围绕这三件事展开的。4.2 核心代码结构Server定义、工具注册、输入输出处理先看代码。我使用的是FastMCP这个高层封装它比直接用底层Server简单很多适合快速上手。from mcp.server.fastmcp import FastMCP import subprocess mcp FastMCP(git-helper) # 注册一个Tool返回当前git分支和状态 mcp.tool() def git_status() - str: 获取当前git仓库的分支和工作区状态 result subprocess.run( [git, status, --short, --branch], capture_outputTrue, textTrue ) return result.stdout or result.stderr mcp.tool() def git_log(count: int 5) - str: 获取最近n条提交记录n默认为5 result subprocess.run( [git, log, f-{count}, --oneline], capture_outputTrue, textTrue ) return result.stdout or result.stderr if __name__ __main__: mcp.run(transportstdio)代码量不大但几个细节要认真讲清楚。FastMCP的装饰器会自动把函数的docstring转换成工具的description把类型注解转换成JSON Schema参数定义。所以写好函数签名和文档字符串就是写好了一个工具声明。4.3 在Claude Desktop和Cursor里完成联调代码写完之后我的联调路线是先直接用MCP官方提供的调试方式验证Server能接手请求再把Server配置进客户端。因为这篇文章不需要依赖特定客户端我以通用的配置思路来说明。需要注意的核心问题是Server的启动路径和启动命令。因为MCP Server是被客户端作为子进程拉起的客户端需要知道用什么命令、在哪个目录下启动。配置stdio类型Server时command字段通常是python或uv runargs列表则是入口脚本路径。路径写相对路径特别容易出错因为工作目录取决于客户端从哪个路径启动最稳妥的做法是用绝对路径或者用一个启动脚本统一处理。联调通过后建议给两个工具分别构造几个不同的输入来测试包括参数缺失、类型错误、超时等情况。很多问题只有把客户端、模型、工具串在一起时才暴露出来单测过了不算数。5. 跑通之后实测遇到的坑从现象到根因的排查记录5.1 现象1工具返回结果被截断模型只能看到前半段我遇到的第一个问题是让模型调用git_log查看提交记录时返回的内容被截断了。开始我怀疑是模型上下文窗口被占满但同样的请求在写了更多系统提示词且没有调用工具的会话里输出并没有问题。后来查看SDK源码发现MCP对单条消息的文本长度有限制。这个限制在协议规范里有对应说明但容易在开发中被忽略。解决思路不是盲目调大限制而是引导工具返回更精炼的结果。我给git_log工具加了一个format参数让模型可以选择紧凑输出还是完整输出同时在工具描述里明确说明如果记录较多模型应当使用compact格式侧后再判断是否需要进一步完整输出。经过这样调整截断问题消失模型也能基于摘要做下一步决策。5.2 现象2Server进程收到请求后无响应客户端一直转圈这个问题困扰了我一个下午。我在本地终端里手动运行Server发测试请求一切正常但通过客户端启动Server工具调用就是超时。后来我在Server代码里把所有print语句去掉才发现问题根因MCP通过stdio传输JSON-RPC消息任何非协议内容的打印输出比如print(server started)都会污染标准输出流导致消息解析失败。排查思路是先确认传输使用stdout而非stderr然后逐一排查是否有非协议的stdout输出。这个坑在开发阶段几乎必踩尤其是项目里已经有日志框架的前提下。解决办法是把业务日志全部写到stderr或者统一走文件日志保证stdout只输出JSON-RPC消息。这里也提醒大家如果在Server内接入第三方SDK它们中间的print行为也要警惕。5.3 现象3JSON Schema参数校验过于严格导致模型反复报错有次我定义了一个参数的枚举mcp.tool() def analyze_mode(mode: str) - str: 按指定模式分析代码 if mode not in [simple, deep]: return funsupported mode: {mode} ...我以为在函数内部做判断已经足够但客户端在传给模型工具描述时会根据类型注解和默认值生成SDK的Schema这个Schema没有对mode做枚举约束模型在自由生成参数时就会编造出类似detailedthorough这样的值。解决办法是在工具包装层显式声明参数枚举而不是把校验逻辑放在函数内部。实际这里也要注意Schema的字段要和函数的docstring对应因为工具描述和参数约束是两条独立的描述路径靠Python注解自动生成的Schema可能和你预期的能力有差异。5.4 现象4本地Server跨机器调度时工具访问的是错误的工作目录当我把同一个Server部署到另一台机器时git_status工具突然返回not a git repository。排查后发现工具返回的是不同路径下的状态而不是我预期操作的仓库。这是因为Client启动Server时使用的是默认cwd而不是仓库所在目录。处理方法是给Server增加工作目录初始化逻辑。在这种场景下通过配置指定根目录并明确提示用户支持绝对路径或相对路径同时在工具描述中写明如果当前目录不是git仓库请先用路径解析工具定位仓库。6. 实测环境下的性能与质量观察6.1 调用延迟分析工具的启停开销比通信本身更大我测量了MCP调用中几个阶段的耗时。使用stdio模式时JSON-RPC消息在本机进程间传输本身开销很小单次消息round trip大概百微秒级别。但工具方法内部如果执行的是冷启动型的任务比如起一个隐士进程或者加载一个大模块延迟就会被拉高到秒级。所以我在部署MCP Server时把高频工具和低频工具拆到了两个Server进程里或者用懒加载方式让低频工具调用时才初始化。这样可以避免一个工具拖垮整个Server的响应。对于远程SSE模式通信耗时主要在网络和HTTP层面单体消息性能和本地stdio差一个数量级但好处是Server可以复用到多个客户端。6.2 并发与资源控制单进程Server需要注意的瓶劲默认情况下FastMCP的stdio模式是单进程单流的即一个Client连接对应一个Server进程。如果你的Host会同时发起多个工具请求Server的并发能力取决于你用的是同步执行还是异步执行。用同步def声明的工具在FastMCP中默认走的是线程池用async def则走事件循环。我在一个并发场景下测试时发现线程池模式的线程数量有限如果工具方法内部是阻塞IO任务会排队。优化方向是把耗时任务改成异步非阻塞实现或者用线程池参数调大并发度。还有一点是共享变量并发访问的问题多个线程操作同一个内存变量时要用锁或避免写操作我在做缓存时就因为没加锁出现过双写覆盖。6.3 安全与权限边界MCP工具是特权入口MCP Server本质上是一个模型可以远程调用的函数这个设计带来了一个严肃的安全话题模型并不是每一次生成的参数都符合预期如果工具内部执行了危险操作会造成严重后果。我在Server中刻意做了权限分级不直接用root权限启动Server文件操作限定在一个指定根目录内命令执行工具必须经过白名单校验。对于共享出去的MCP Server还建议做能力收敛一个Server只暴露一个业务域的工具遵循最小权限原则。同时认真检查工具的输入参数是否可能导致路径穿越、命令注入等问题。比如git仓库工具里用户可能传一个目录参数如果不校验就可能读到仓库外的文件。7. MCP生态观察从协议演进看工具接入的未来把我自己见到的现象摆一摆7.1 多模态与更复杂的参数类型从JSON到二进制数据的传输现阶段MCP的工具参数主要通过JSON传递意味着二进制内容图片、音频、视频文件、文件对象等很难直接作为参数传入。目前常见的做法是把文件写入临时路径工具通过路径定位文件。这个方案在本地用没问题但远程化之后就需要分布式存储支持了。MCP规范后续有可能显式支持二进制数据的Base64编码传输或者支持blob对象引用。大家在设计工具API时尽量把操作对象ID与加载对象内容拆成两个阶段不要指望一次性把所有参数都传到工具里。7.2 客户端Agent化MCP Server成为多Agent协作的基础设施我在Agent项目中看到的一个趋势是MCP Server正越来越多地被当作组件服务来使用而不是简单绑定在某一个大模型客户端里。多个Agent可以通过共享MCP Server来访问同一组工具和数据源Server层面做统一的权限和审计。这有点像微服务架构里把通用能力下沉成基础服务只不过这里的能力编排者是模型而不是开发人员。我的判断是未来Agent开发的架构分层会越来越清晰最上层是Agent编排逻辑中间是工具服务层底层才是具体系统API。MCP恰好卡在中间这一层协议的价值会随着Agent开发标准化程度的加深而放大。7.3 团队内部私有MCP Server的治理如果要在团队内落地MCP我建议先建立三个机制工具注册与文档同步机制、权限审批机制、调用审计机制。这些听起来像制度建设的事和协议无关但在真实工程里占的比重比协议本身还大。因为MCP让工具接入变得太容易了如果没有治理Server会快速膨胀成难以维护的工具沼泽。我的做法是每周固定审视一次Server清单清理调用量过低且能力重合的工具合并部分粒度太细的工具。另外对于需要升级的Server尽量通过协议版本和Capabilities配置来平滑过渡客户端和服务端的版本对齐在MCP中是一个需要显式管理的环节千万别轻视。7.4 末段说一点我的亲身体会做MCP项目之前我也纠结过要不要使用更加内部化的接口来对接工具。毕竟这些接口实现起来也不难何必引入新依赖。真做了MCP之后最大的收获不是技术本身而是接入成本的降低——我只需要实现一次协议完成了三个客户端的接入后来团队把多个内部工具开放给不同Agent用也都走MCP统一起来了。现在在写新的Agent工具时我第一反应不再是这个工具用什么接口暴露出来而是这个能力用一个什么样的MCP Server来描述。开发心智已经悄悄转变了。MCP的成熟度还没有到无所不能的程度但方向已经摆得很明白未来几年你可能不会再看到给Agent接入XX服务这种费时费力的对接文档取而代之的是一句它支持MCP吗如果支持五分钟接完如果不支持你大概率才会开始考虑适配层怎么写。