学了大半个月MCP看了十几篇教程文档翻来覆去啃了几遍但真正上手写代码的时候脑子里还是一团浆糊Host、Client、Server、Tool、Resource、Prompt、Transport、SDK……每个词单独拿出来都认识拼在一起就不知道谁先谁后、谁调谁。直到有一天我把它们硬生生捋成一条线才发现之前学不懂不是因为我笨是教程都按“概念清单”讲没人告诉我MCP其实就只是一条调用链而已。这篇文章不打算从协议规范讲起我只想把我脑子里最后留下的那条核心链路拆给你看再把这条链上对应的高频疑问、实操代码、踩坑记录一次说清楚保证你用这条链去套网上任何一篇MCP文章都能一眼看懂它在讲哪一环。1. 学了半天没学懂是因为你一直在背单词而不是找主线我先坦白一下自己的学习过程估计跟很多人一模一样。最开始接触MCP是在社区看到有人发“AI Agent接入MCP之后能自己查数据库、操作浏览器、读文件了”感觉这是个很牛的东西。于是开始查资料然后迎面撞上一堆概念MCP是Model Context Protocol由Anthropic开源它有Host、Client、Server三类角色工具支持Tool、Resource、Prompt三种原语传输方式有stdio和HTTP还涉及到JSON-RPC、Session、Initialize握手、能力协商……每个名词我都花时间看了每个都能在帖子里找到对应的解释。可一到自己动手写点东西的时候我就卡住了我到底应该先写Server还是先写ClientAI应用是怎么知道我定义了工具的它调用工具的时候数据流是怎么走的配置了但没生效问题出在哪这个阶段我管它叫“背单词阶段”。单词背得再熟不知道它们在一句话里的位置和关系永远读不懂文章。后来我发现所有概念其实都能被收纳到一条简单的链路上这条链路就是AI应用Host→ MCP Client →协议/传输层→ MCP Server → 工具/资源/提示词AI应用收到用户的自然语言指令之后由内部的大模型判断“要不要使用工具、使用哪个工具”决定要用就通过MCP Client向MCP Server发起请求Server执行对应的工具代码把结果沿原路返回AI再把结果整理成用户能看懂的回复。看起来平平无奇但MCP的一切设计几乎都是为了把这条链路用标准协议固化下来。工具、资源、提示词是Server“能提供什么”的三个维度stdio和HTTP是Client和Server之间“怎么传话”的两种方式JSON-RPC是传话的语法规则Initialize握手是双方见面先对暗号互相确认身份和能力……一旦你建立了这条链的认知再去回看那些概念它们就全部各就各位了完全不需要死记硬背。所以这篇文章的野心其实很小帮你在脑子里装下这条主线然后带着你顺着这条链走一遍完整流程。后面再看到哪个概念觉得眼生你只需要问一句它是这条链上哪个环节的东西2. 调用链上的每个角色到底在干什么既然核心是条链我们先把这个链条的两头搞清楚再补中间的部分。整条链的角色拆开来看其实就四个Host、Client、Server、Tool外加Resource和Prompt两个变体。2.1 AI应用只做“选择题”真正干活的是Client和Server很多人第一次看MCP的角色划分会觉得奇怪Host和Client不是一回事吗为什么要拆成两个词我的理解是Host是那个你直接面对的应用比如Claude Desktop、Cursor、你正在开发的智能体项目它负责接住用户的话、维护对话上下文、调用大模型。Client不是独立部署的服务它更像Host内部内置的一个“连接模块”负责按MCP协议跟外部的Server通信。也就是说Host是大楼Client是楼里统一标准的插座面板Server是各种接入插座的家电。用户在Host输入“帮我查一下杭州今天的天气然后提醒我明天带伞”这句话并不会直接发给天气Server。Host内部的大模型先做判断题这件事需不需要调用外部能力需要的话应该调哪个工具大模型通过工具描述知道有个get_weather工具可以查天气于是生成一次函数调用请求Host再把这次调用委托给MCP Client由Client去跟Server完成JSON-RPC通信。AI应用的角色本质是“决策者”负责判断调哪个工具、怎么组织参数Client和Server才负责把决策变成实际动作。我在写Agent的时候最大的领悟就是不要指望模型真的会“操作工具”它只是根据工具的元数据描述生成一个调用意图真正执行的是代码。2.2 MCP Server是工具箱Tool是具体工具MCP Server可以理解为一个独立运行的“工具箱进程”。它可能是个本地Python脚本跑在stdio上也可能是个远程HTTP服务部署在服务器上C端应用通过网络连接。不管哪种形态它的职责是固定的把自己能提供的工具告诉Client然后等着Client来调用。这里有个容易踩的认知误区很多人以为MCP Server是个“固定的服务”一旦启动就一直运行。实际上在本地stdio模式下Server的生命周期是由Client拉起的子进程来承载的——你的AI应用启动时连上它应用退出时它也就退出了。而远程HTTP模式的Server才是常驻服务。所以你要根据场景选传输方式而不是哪种火用哪种。Tool是Server暴露给AI的最小执行单元一个Server可以挂多个工具。每个工具在代码里就是个函数但它跟普通函数的区别在于它必须附带一份机器可读的描述也就是JSON Schema。这份描述包含工具叫什么、是干什么用的、需要哪些参数、参数是什么类型。为什么必须有这个因为大模型本身不具备“直接看到函数代码”的能力模型是通过文本和结构化数据理解世界的工具的name、description、inputSchema就是模型理解工具的全部素材。我见过很多新手写工具只给name不给description或者description写得像文档一样冗长结果模型要么不会调用它要么老是传错参数。工具描述写得够不够清楚直接决定这条链的上限。2.3 Transport是连接方式stdio和HTTP怎么选Client和Server之间“传话”用的管道在MCP里叫Transport目前主流两种stdio和HTTP。stdio就是Server以子进程方式运行Client通过标准输入输出跟它通信。这种模式的特点是简单、安全不用开端口适合本地工具比如读写本地文件、操作数据库、控制浏览器这类敏感操作。我平时在Claude Desktop里配置本地的文件整理工具、代码分析工具用的都是stdio。HTTP模式则是Server跑在远程Client通过URL访问。适合把公司内部的API封装成MCP服务供多个Agent调用也适合团队共享一套工具。HTTP模式还支持无状态请求和流式响应能力上限更高但你需要自己处理鉴权、部署、跨域这些问题。还有一个更具象的理解方式stdio模式下Server和你的AI应用住在一台机器上Client通过管道跟它喊话HTTP模式下Server住在云端Client通过HTTP请求去敲门。清晰了这点后面看代码就不会困惑“为什么要用subprocess去起一个服务”。对比项stdio模式HTTP模式Server部署位置本地子进程远程服务器适合场景本地文件、数据库、敏感操作团队共享、多Agent复用安全要求低本机通信高需鉴权和治理生命周期跟随Host启动/退出常驻服务上手难度低中3. 用天气服务demo把链路串起来概念讲再多不如代码直观。我用一个最简单的天气查询工具做例子把Server定义、Client连接、AI应用配置三段代码贴出来大家对照着链路看。3.1 先定义一个MCP Server注册工具现在官方Python SDK提供了FastMCP这个封装写Server流程被简化了很多。第一步是创建一个Server实例注册工具函数然后让它跑起来from mcp.server.fastmcp import FastMCP # 创建名为 weather-server 的MCP服务 mcp FastMCP(weather-server) mcp.tool() def get_weather(city: str) - str: 查询指定城市的当前天气返回温度、天气状况和风力信息 # 这里省略真实API调用实际开发中可以调第三方天气接口 return f{city}晴25°C东南风2级 if __name__ __main__: mcp.run(transportstdio)这个文件就是完整的MCP Server。只做了三件事创建服务、用装饰器注册工具、启动服务。函数名get_weather会变成工具的namedocstring会变成工具的description参数city会被自动解析成inputSchema。也就是说大模型看到的工具描述是从函数签名和注释里推算出来的。这解释了一个常见疑问为什么我在mcp.tool()这个装饰器下面写注释模型好像能“看懂”因为SDK在启动时扫描了函数结构把它编译成了JSON Schema注册到了Server的工具清单里。如果想启动成HTTP服务只需要把transportstdio改成transporthttp并指定端口。FastMCP底层会自动创建一个流式HTTP端点。3.2 再用Client连过去Client是怎么跟Server对接的Server跑起来了怎么确认它能被调用最直接的办法是写个独立的小Client去连它。这里我分别给出stdio和HTTP两种连接方式的Client代码import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): # 定义要启动的本地Server进程 server_params StdioServerParameters( commandpython, args[weather_server.py] ) # 启动子进程拿到读写流 async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: # 1. 握手Client和Server互换协议版本与能力 await session.initialize() # 2. 列出全部工具 tools await session.list_tools() print(可用工具:, [t.name for t in tools]) # 3. 调用指定工具 result await session.call_tool(get_weather, {city: 杭州}) print(调用结果:, result.content[0].text) asyncio.run(main())如果Server是HTTP模式Client代码改成这样import asyncio from mcp import ClientSession from mcp.client.http import http_client async def main(): url http://localhost:8000/mcp async with http_client(url) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() print(可用工具:, [t.name for t in tools]) result await session.call_tool(get_weather, {city: 杭州}) print(调用结果:, result.content[0].text) asyncio.run(main())细心的人会发现两种连接方式在ClientSession之后的代码完全一样。这就是MCP协议带来的最大好处传输层被抽象掉了上层代码不用关心Server是本地进程还是远程服务只要对接的是同一个协议代码就是同一套。这也是为什么很多人说MCP是AI界的“USB-C接口”——不管后端接的是数据库、浏览器还是设计稿工具Client这端的接口形态统一了。3.3 AI应用层配置让模型在对话中主动使用工具SDK层面的Client演示只是验证链路通不通真正的应用场景是把Server配置到AI应用里让模型在对话中自动决定调用时机。以Claude Desktop为例配置文件是claude_desktop_config.json把刚才写的天气服务挂上去{ mcpServers: { weather: { command: python, args: [/绝对路径/weather_server.py] } } }IDE类的AI编程工具配置大同小异只不过多了个界面化的MCP管理面板。配置完成重启应用后在对话里输入“杭州天气怎么样”应用会先通过Client拿到工具列表把get_weather的JSON Schema塞进提示词上下文里模型一看“有个工具能查天气我该用它”于是生成调用参数Client去Server实际执行结果返回后模型组织语言输出“杭州今天晴25°C”。这就是整条调用链在应用层的完整形态。这里要特别提醒一个大多数新手会忽略的点模型选择工具依赖的是工具描述和当前对话的语义匹配度。如果你给工具的description是英文对话是中文模型也能匹配但描述写得模糊比如只写“查询天气”不写参数含义模型就会乱猜。我建议每个工具描述里都要写明工具什么时候用、每个参数的格式、返回结果长什么样。这跟写函数注释的原则一致但要求更高因为读者不是人是大模型。4. 那些社区里的高频疑问其实都卡在这条链的某个环节上学习MCP的过程里我相信你一定刷到过这类问题“MCP和Skills有什么区别”“工具市场在哪里”“MCP怎么做鉴权”“MCP是不是AI版的API网关”。这些问题单独看很散但如果你把它们放到调用链上就瞬间有答案了。4.1 Skills和MCP的区别一个在Agent内一个在Agent外这个问题几乎是MCP讨论区的日经贴。我的理解是这样的Skills是Agent“自己身上”的技能它活在Agent内部本质是一套预置的指令、提示词或内部工具不需要外部通信Agent天生就会MCP则是一个标准化的“外接能力通道”Agent要使用的能力并不在自身内部而是通过Client去请求一个独立Server。拿人做类比Skills是你自己的手艺比如你会做饭MCP是外卖平台你自己不做但可以通过平台叫到各种餐厅的菜。Skill的优点是快、稳定、无需网络缺点是能力和Agent打包在一起换Agent就得迁移MCP的优点是松耦合、可复用、可跨Agent共享缺点是多了网络通信和部署成本。实际项目中两者不是二选一而是配合使用固定的、重内部逻辑的做成Skill需要外部数据、跨系统协作的做成MCP。4.2 工具市场/工具商店对应的是链上的哪个点社区都在讨论“MCP工具市场在哪”其实这个问题的答案藏在供应链的上游。调用链本身并没有“市场”这个环节工具市场是开发者生态层面的东西它的作用是方便你发现别人写好的MCP Server然后把Server的地址或安装命令复制到自己的应用配置里。换句话说工具市场帮你省掉的是“自己开发Server”这步但Server一旦被配置进应用它依然处在链路的末端。所以没必要纠结市场这种东西更核心的能力是自己能写出、能部署一个Server市场只是锦上添花。4.3 鉴权、超时和容错发生在链路的哪个位置链路清晰了可靠性设计就有了着力点。鉴权发生在Client请求Server之前要么在HTTP请求头里带token要么在Server内部做API Key校验如果你走的是公司内网还可能用OAuth。超时控制发生在Client调用Session.call_tool的时候SDK一般有timeout参数而容错则要分几层Server要处理工具抛出的异常把错误信息转为结构化返回Client要处理连接失败、响应超时的情况Host要处理模型生成非法参数的情况。很多人做MCP只关心“让链路通”却忽略了链路的每一段都可能断生产级Agent和demo的差距就在这里。4.4 为什么说MCP是“AI界的USB-C”之前我用“插座面板”类比过Client这个类比还能延伸在没有USB-C的年代不同设备有不同充电口你得带一堆线MCP做的事就是把“AI应用需要外部能力”这件事的接口统一成一个标准协议。任何AI应用只要内置MCP Client就能连接任何MCP Server任何工具开发者只要实现MCP Server就能被所有支持MCP的AI应用使用。这种网络效应是这个协议最迷人的地方。现在很多公司内部已经在做“单点接入全局复用”的MCP治理平台了——一个服务封装好全公司的Agent都能调。高频疑问对应调用链位置一句话答案Skills和MCP有什么区别Agent内部 vs 链路末端Skills是内置能力MCP是外接通道鉴权怎么做Client到Server之间HTTP头加token/OAuthServer在哪里买/找链路外部生态工具市场只是分发渠道核心是Server本身为什么配置了没生效通常是Client到Server的连接段先检查Transport类型、地址、子进程启动日志一个Agent能接多少个MCPHost这一层不限数量但会影响模型上下文长度和决策速度5. 踩坑记录和实测心得链路通了问题往往出在这几处理论理清楚之后动手过程中还是会有各种各样的问题。我把自己和身边朋友踩过的坑整理成几条每条都是真金白银换来的经验。第一个坑配置了MCP ServerAI应用的工具列表却是空的。这个问题九成出在stdio模式下Server的启动路径。Claude Desktop如果通过command: python启动Server它的python指的是应用内置环境的Python不是你系统里的那个。解决方式是写绝对路径或者直接用.venv/bin/python这样的路径去启动。排查手段就是在Client代码里打印一下工具列表看SDK能不能正常列出来这一步能过滤掉很多问题。第二个坑工具调用经常超时。原因多半是你执行的操作本身耗时长比如查数据库、请求外部API而MCP默认超时时间比较短。我测试过一个数据同步工具单次执行要30秒Client早就超时了。MCP的Session调用是可以配置timeout的我一般会在SDK层调大超时时间。还有一个思路是把长任务拆成“创建任务轮询状态”两个工具Server端实现异步逻辑Client端先拿到任务号再轮询结果这样链路更稳。第三个坑工具的返回结果格式太随意。有些Server会直接返回一个只有文本内容的对象模型拿到之后虽然能读懂但结构化信息丢失了后续想再做一步操作比如把查询结果存进表格就很费劲。注意MCP的Tool结果是可以带结构化内容content的。我推荐工具返回时尽量用结构化JSON并配合一个markdown格式的展示文本。举个实际例子数据库查询工具返回时我会返回两部分内容一部分是文本描述“查询到3条记录”另一部分是结构化内容包含字段名和JSON数据。AI既能直接引用结构化数据做进一步处理也能给用户展示可读性强的文本结果。第四个坑调试困难。本地stdio模式下Server跑在子进程里它的print输出会被Client当协议数据解析一旦你写了print调试整个通信就直接崩了。这个坑特别隐蔽因为本地单独运行Server时一切正常一挂到Client上就报协议错误。正确的调试姿势是在Server代码里用logging模块输出到独立文件或者把日志写到stderr因为MCP协议走的是stdout。只有理解了Client和Server之间的数据通道是什么才能解释为什么那个print会引发灾难性后果。第五个坑模型总是传错参数。前面提到过工具描述是模型的“使用说明书”但很多人不重视。我见过一个工具定义了city参数description是“城市名”模型却经常传一个包含经纬度的对象过去。后来我把参数description改成“城市中文名例如杭州、北京、上海”再在inputSchema里加上枚举值约束调用准确率直接上来了。模型不是人它没有常识所有关于参数的约束你都得显式写清楚。第六个坑Server端反复重启导致的资源堆积。本地模式每次启动都是新进程还好HTTP模式的Server通常常驻如果工具函数里创建了数据库连接池、文件句柄一定要做好复用和释放不然连续调用几十次之后Server响应会越来越慢最终拒绝连接。这是日常测试中容易被忽略的稳定性问题。6. 站在调用链高度重新规划学习路线如果让我重新学一遍MCP我会完全改变之前的思路先建立链路认知再逐环深入。按这条链的顺序学习可以分成五步。第一步先用现成的MCP Server跑通一个完整链路。这一阶段的目标是感受“从用户在对话框说话到工具被执行再回到用户看到结果”的全过程。不要写代码只需要在Claude Desktop或Cursor的MCP市场里装一个现成的Server比如文件管理或待办事项的跟它对话让它真实操作文件。这个过程帮你建立直觉工具在哪、谁在执行、返回的形态是什么。第二步自己实现一个最简单的Server和Client。文章前面的天气服务代码已经给了照着跑通。跑通之后再思考一个问题Server定义的工具Client是怎么拿到的答案是Client先发一个tools/list请求Server返回工具描述列表。想验证的话可以自己在Client代码里print一下session.list_tools()的原始返回结构。这一步是把链路从“黑盒”变成“白盒”的关键。第三步深入协议细节重点吃透JSON-RPC的报文格式和Initialize握手。这个阶段你会发现网上很多源码分析文章都能看懂了。你不需要背下所有消息类型的字段但至少要看得懂一次会话里的关键报文。我的建议是给本地Server加一层日志把Client和Server之间互相发送的消息记录下来对照协议文档看一遍收获很大。第四步学习SDK的封装逻辑。官方Python SDK用了很多抽象比如给函数加个装饰器就能变成工具。这阶段你应该自己尝试不依赖FastMCP用最底层的SDK手写一个Server或者读FastMCP源码看它底层是如何把函数签名转成JSON Schema的。搞明白了这些以后遇到SDK升级导致行为变化的时候你不会一头雾水。第五步实战扩展。接上真实数据库、真实API、长耗时任务、鉴权体系把小demo变成生产可用工具。到了这个阶段你遇到的问题基本就是链路各环节的质量问题了Server稳定不稳定、请求慢不慢、工具描述准不准、模型调用策略对不对。这些问题没有统一的参考答案需要你回到链路中定位用排错方法论去解决而不是搜一个“标准答案”。回到最初的问题MCP的核心到底是什么毫无疑问就是这条调用链。它没多玄乎一端是AI应用一端是工具中间的MCP协议把所有连接规则标准化了。搞懂了谁在哪一环、数据怎么流动、故障发生在哪一段你在任何社区看到任何关于MCP的讨论都能快速定位到对应的环节然后有针对性地研究。希望我这段时间的思考和踩坑记录能帮你省下一些在概念泥潭里挣扎的时间。后面我还会整理一份我实际用过的MCP Server清单和配置模板下一篇继续聊。
学了大半个月MCP看了十几篇教程文档翻来覆去啃了几遍但真正上手写代码的时候脑子里还是一团浆糊Host、Client、Server、Tool、Resource、Prompt、Transport、SDK……每个词单独拿出来都认识拼在一起就不知道谁先谁后、谁调谁。直到有一天我把它们硬生生捋成一条线才发现之前学不懂不是因为我笨是教程都按“概念清单”讲没人告诉我MCP其实就只是一条调用链而已。这篇文章不打算从协议规范讲起我只想把我脑子里最后留下的那条核心链路拆给你看再把这条链上对应的高频疑问、实操代码、踩坑记录一次说清楚保证你用这条链去套网上任何一篇MCP文章都能一眼看懂它在讲哪一环。1. 学了半天没学懂是因为你一直在背单词而不是找主线我先坦白一下自己的学习过程估计跟很多人一模一样。最开始接触MCP是在社区看到有人发“AI Agent接入MCP之后能自己查数据库、操作浏览器、读文件了”感觉这是个很牛的东西。于是开始查资料然后迎面撞上一堆概念MCP是Model Context Protocol由Anthropic开源它有Host、Client、Server三类角色工具支持Tool、Resource、Prompt三种原语传输方式有stdio和HTTP还涉及到JSON-RPC、Session、Initialize握手、能力协商……每个名词我都花时间看了每个都能在帖子里找到对应的解释。可一到自己动手写点东西的时候我就卡住了我到底应该先写Server还是先写ClientAI应用是怎么知道我定义了工具的它调用工具的时候数据流是怎么走的配置了但没生效问题出在哪这个阶段我管它叫“背单词阶段”。单词背得再熟不知道它们在一句话里的位置和关系永远读不懂文章。后来我发现所有概念其实都能被收纳到一条简单的链路上这条链路就是AI应用Host→ MCP Client →协议/传输层→ MCP Server → 工具/资源/提示词AI应用收到用户的自然语言指令之后由内部的大模型判断“要不要使用工具、使用哪个工具”决定要用就通过MCP Client向MCP Server发起请求Server执行对应的工具代码把结果沿原路返回AI再把结果整理成用户能看懂的回复。看起来平平无奇但MCP的一切设计几乎都是为了把这条链路用标准协议固化下来。工具、资源、提示词是Server“能提供什么”的三个维度stdio和HTTP是Client和Server之间“怎么传话”的两种方式JSON-RPC是传话的语法规则Initialize握手是双方见面先对暗号互相确认身份和能力……一旦你建立了这条链的认知再去回看那些概念它们就全部各就各位了完全不需要死记硬背。所以这篇文章的野心其实很小帮你在脑子里装下这条主线然后带着你顺着这条链走一遍完整流程。后面再看到哪个概念觉得眼生你只需要问一句它是这条链上哪个环节的东西2. 调用链上的每个角色到底在干什么既然核心是条链我们先把这个链条的两头搞清楚再补中间的部分。整条链的角色拆开来看其实就四个Host、Client、Server、Tool外加Resource和Prompt两个变体。2.1 AI应用只做“选择题”真正干活的是Client和Server很多人第一次看MCP的角色划分会觉得奇怪Host和Client不是一回事吗为什么要拆成两个词我的理解是Host是那个你直接面对的应用比如Claude Desktop、Cursor、你正在开发的智能体项目它负责接住用户的话、维护对话上下文、调用大模型。Client不是独立部署的服务它更像Host内部内置的一个“连接模块”负责按MCP协议跟外部的Server通信。也就是说Host是大楼Client是楼里统一标准的插座面板Server是各种接入插座的家电。用户在Host输入“帮我查一下杭州今天的天气然后提醒我明天带伞”这句话并不会直接发给天气Server。Host内部的大模型先做判断题这件事需不需要调用外部能力需要的话应该调哪个工具大模型通过工具描述知道有个get_weather工具可以查天气于是生成一次函数调用请求Host再把这次调用委托给MCP Client由Client去跟Server完成JSON-RPC通信。AI应用的角色本质是“决策者”负责判断调哪个工具、怎么组织参数Client和Server才负责把决策变成实际动作。我在写Agent的时候最大的领悟就是不要指望模型真的会“操作工具”它只是根据工具的元数据描述生成一个调用意图真正执行的是代码。2.2 MCP Server是工具箱Tool是具体工具MCP Server可以理解为一个独立运行的“工具箱进程”。它可能是个本地Python脚本跑在stdio上也可能是个远程HTTP服务部署在服务器上C端应用通过网络连接。不管哪种形态它的职责是固定的把自己能提供的工具告诉Client然后等着Client来调用。这里有个容易踩的认知误区很多人以为MCP Server是个“固定的服务”一旦启动就一直运行。实际上在本地stdio模式下Server的生命周期是由Client拉起的子进程来承载的——你的AI应用启动时连上它应用退出时它也就退出了。而远程HTTP模式的Server才是常驻服务。所以你要根据场景选传输方式而不是哪种火用哪种。Tool是Server暴露给AI的最小执行单元一个Server可以挂多个工具。每个工具在代码里就是个函数但它跟普通函数的区别在于它必须附带一份机器可读的描述也就是JSON Schema。这份描述包含工具叫什么、是干什么用的、需要哪些参数、参数是什么类型。为什么必须有这个因为大模型本身不具备“直接看到函数代码”的能力模型是通过文本和结构化数据理解世界的工具的name、description、inputSchema就是模型理解工具的全部素材。我见过很多新手写工具只给name不给description或者description写得像文档一样冗长结果模型要么不会调用它要么老是传错参数。工具描述写得够不够清楚直接决定这条链的上限。2.3 Transport是连接方式stdio和HTTP怎么选Client和Server之间“传话”用的管道在MCP里叫Transport目前主流两种stdio和HTTP。stdio就是Server以子进程方式运行Client通过标准输入输出跟它通信。这种模式的特点是简单、安全不用开端口适合本地工具比如读写本地文件、操作数据库、控制浏览器这类敏感操作。我平时在Claude Desktop里配置本地的文件整理工具、代码分析工具用的都是stdio。HTTP模式则是Server跑在远程Client通过URL访问。适合把公司内部的API封装成MCP服务供多个Agent调用也适合团队共享一套工具。HTTP模式还支持无状态请求和流式响应能力上限更高但你需要自己处理鉴权、部署、跨域这些问题。还有一个更具象的理解方式stdio模式下Server和你的AI应用住在一台机器上Client通过管道跟它喊话HTTP模式下Server住在云端Client通过HTTP请求去敲门。清晰了这点后面看代码就不会困惑“为什么要用subprocess去起一个服务”。对比项stdio模式HTTP模式Server部署位置本地子进程远程服务器适合场景本地文件、数据库、敏感操作团队共享、多Agent复用安全要求低本机通信高需鉴权和治理生命周期跟随Host启动/退出常驻服务上手难度低中3. 用天气服务demo把链路串起来概念讲再多不如代码直观。我用一个最简单的天气查询工具做例子把Server定义、Client连接、AI应用配置三段代码贴出来大家对照着链路看。3.1 先定义一个MCP Server注册工具现在官方Python SDK提供了FastMCP这个封装写Server流程被简化了很多。第一步是创建一个Server实例注册工具函数然后让它跑起来from mcp.server.fastmcp import FastMCP # 创建名为 weather-server 的MCP服务 mcp FastMCP(weather-server) mcp.tool() def get_weather(city: str) - str: 查询指定城市的当前天气返回温度、天气状况和风力信息 # 这里省略真实API调用实际开发中可以调第三方天气接口 return f{city}晴25°C东南风2级 if __name__ __main__: mcp.run(transportstdio)这个文件就是完整的MCP Server。只做了三件事创建服务、用装饰器注册工具、启动服务。函数名get_weather会变成工具的namedocstring会变成工具的description参数city会被自动解析成inputSchema。也就是说大模型看到的工具描述是从函数签名和注释里推算出来的。这解释了一个常见疑问为什么我在mcp.tool()这个装饰器下面写注释模型好像能“看懂”因为SDK在启动时扫描了函数结构把它编译成了JSON Schema注册到了Server的工具清单里。如果想启动成HTTP服务只需要把transportstdio改成transporthttp并指定端口。FastMCP底层会自动创建一个流式HTTP端点。3.2 再用Client连过去Client是怎么跟Server对接的Server跑起来了怎么确认它能被调用最直接的办法是写个独立的小Client去连它。这里我分别给出stdio和HTTP两种连接方式的Client代码import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): # 定义要启动的本地Server进程 server_params StdioServerParameters( commandpython, args[weather_server.py] ) # 启动子进程拿到读写流 async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: # 1. 握手Client和Server互换协议版本与能力 await session.initialize() # 2. 列出全部工具 tools await session.list_tools() print(可用工具:, [t.name for t in tools]) # 3. 调用指定工具 result await session.call_tool(get_weather, {city: 杭州}) print(调用结果:, result.content[0].text) asyncio.run(main())如果Server是HTTP模式Client代码改成这样import asyncio from mcp import ClientSession from mcp.client.http import http_client async def main(): url http://localhost:8000/mcp async with http_client(url) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() print(可用工具:, [t.name for t in tools]) result await session.call_tool(get_weather, {city: 杭州}) print(调用结果:, result.content[0].text) asyncio.run(main())细心的人会发现两种连接方式在ClientSession之后的代码完全一样。这就是MCP协议带来的最大好处传输层被抽象掉了上层代码不用关心Server是本地进程还是远程服务只要对接的是同一个协议代码就是同一套。这也是为什么很多人说MCP是AI界的“USB-C接口”——不管后端接的是数据库、浏览器还是设计稿工具Client这端的接口形态统一了。3.3 AI应用层配置让模型在对话中主动使用工具SDK层面的Client演示只是验证链路通不通真正的应用场景是把Server配置到AI应用里让模型在对话中自动决定调用时机。以Claude Desktop为例配置文件是claude_desktop_config.json把刚才写的天气服务挂上去{ mcpServers: { weather: { command: python, args: [/绝对路径/weather_server.py] } } }IDE类的AI编程工具配置大同小异只不过多了个界面化的MCP管理面板。配置完成重启应用后在对话里输入“杭州天气怎么样”应用会先通过Client拿到工具列表把get_weather的JSON Schema塞进提示词上下文里模型一看“有个工具能查天气我该用它”于是生成调用参数Client去Server实际执行结果返回后模型组织语言输出“杭州今天晴25°C”。这就是整条调用链在应用层的完整形态。这里要特别提醒一个大多数新手会忽略的点模型选择工具依赖的是工具描述和当前对话的语义匹配度。如果你给工具的description是英文对话是中文模型也能匹配但描述写得模糊比如只写“查询天气”不写参数含义模型就会乱猜。我建议每个工具描述里都要写明工具什么时候用、每个参数的格式、返回结果长什么样。这跟写函数注释的原则一致但要求更高因为读者不是人是大模型。4. 那些社区里的高频疑问其实都卡在这条链的某个环节上学习MCP的过程里我相信你一定刷到过这类问题“MCP和Skills有什么区别”“工具市场在哪里”“MCP怎么做鉴权”“MCP是不是AI版的API网关”。这些问题单独看很散但如果你把它们放到调用链上就瞬间有答案了。4.1 Skills和MCP的区别一个在Agent内一个在Agent外这个问题几乎是MCP讨论区的日经贴。我的理解是这样的Skills是Agent“自己身上”的技能它活在Agent内部本质是一套预置的指令、提示词或内部工具不需要外部通信Agent天生就会MCP则是一个标准化的“外接能力通道”Agent要使用的能力并不在自身内部而是通过Client去请求一个独立Server。拿人做类比Skills是你自己的手艺比如你会做饭MCP是外卖平台你自己不做但可以通过平台叫到各种餐厅的菜。Skill的优点是快、稳定、无需网络缺点是能力和Agent打包在一起换Agent就得迁移MCP的优点是松耦合、可复用、可跨Agent共享缺点是多了网络通信和部署成本。实际项目中两者不是二选一而是配合使用固定的、重内部逻辑的做成Skill需要外部数据、跨系统协作的做成MCP。4.2 工具市场/工具商店对应的是链上的哪个点社区都在讨论“MCP工具市场在哪”其实这个问题的答案藏在供应链的上游。调用链本身并没有“市场”这个环节工具市场是开发者生态层面的东西它的作用是方便你发现别人写好的MCP Server然后把Server的地址或安装命令复制到自己的应用配置里。换句话说工具市场帮你省掉的是“自己开发Server”这步但Server一旦被配置进应用它依然处在链路的末端。所以没必要纠结市场这种东西更核心的能力是自己能写出、能部署一个Server市场只是锦上添花。4.3 鉴权、超时和容错发生在链路的哪个位置链路清晰了可靠性设计就有了着力点。鉴权发生在Client请求Server之前要么在HTTP请求头里带token要么在Server内部做API Key校验如果你走的是公司内网还可能用OAuth。超时控制发生在Client调用Session.call_tool的时候SDK一般有timeout参数而容错则要分几层Server要处理工具抛出的异常把错误信息转为结构化返回Client要处理连接失败、响应超时的情况Host要处理模型生成非法参数的情况。很多人做MCP只关心“让链路通”却忽略了链路的每一段都可能断生产级Agent和demo的差距就在这里。4.4 为什么说MCP是“AI界的USB-C”之前我用“插座面板”类比过Client这个类比还能延伸在没有USB-C的年代不同设备有不同充电口你得带一堆线MCP做的事就是把“AI应用需要外部能力”这件事的接口统一成一个标准协议。任何AI应用只要内置MCP Client就能连接任何MCP Server任何工具开发者只要实现MCP Server就能被所有支持MCP的AI应用使用。这种网络效应是这个协议最迷人的地方。现在很多公司内部已经在做“单点接入全局复用”的MCP治理平台了——一个服务封装好全公司的Agent都能调。高频疑问对应调用链位置一句话答案Skills和MCP有什么区别Agent内部 vs 链路末端Skills是内置能力MCP是外接通道鉴权怎么做Client到Server之间HTTP头加token/OAuthServer在哪里买/找链路外部生态工具市场只是分发渠道核心是Server本身为什么配置了没生效通常是Client到Server的连接段先检查Transport类型、地址、子进程启动日志一个Agent能接多少个MCPHost这一层不限数量但会影响模型上下文长度和决策速度5. 踩坑记录和实测心得链路通了问题往往出在这几处理论理清楚之后动手过程中还是会有各种各样的问题。我把自己和身边朋友踩过的坑整理成几条每条都是真金白银换来的经验。第一个坑配置了MCP ServerAI应用的工具列表却是空的。这个问题九成出在stdio模式下Server的启动路径。Claude Desktop如果通过command: python启动Server它的python指的是应用内置环境的Python不是你系统里的那个。解决方式是写绝对路径或者直接用.venv/bin/python这样的路径去启动。排查手段就是在Client代码里打印一下工具列表看SDK能不能正常列出来这一步能过滤掉很多问题。第二个坑工具调用经常超时。原因多半是你执行的操作本身耗时长比如查数据库、请求外部API而MCP默认超时时间比较短。我测试过一个数据同步工具单次执行要30秒Client早就超时了。MCP的Session调用是可以配置timeout的我一般会在SDK层调大超时时间。还有一个思路是把长任务拆成“创建任务轮询状态”两个工具Server端实现异步逻辑Client端先拿到任务号再轮询结果这样链路更稳。第三个坑工具的返回结果格式太随意。有些Server会直接返回一个只有文本内容的对象模型拿到之后虽然能读懂但结构化信息丢失了后续想再做一步操作比如把查询结果存进表格就很费劲。注意MCP的Tool结果是可以带结构化内容content的。我推荐工具返回时尽量用结构化JSON并配合一个markdown格式的展示文本。举个实际例子数据库查询工具返回时我会返回两部分内容一部分是文本描述“查询到3条记录”另一部分是结构化内容包含字段名和JSON数据。AI既能直接引用结构化数据做进一步处理也能给用户展示可读性强的文本结果。第四个坑调试困难。本地stdio模式下Server跑在子进程里它的print输出会被Client当协议数据解析一旦你写了print调试整个通信就直接崩了。这个坑特别隐蔽因为本地单独运行Server时一切正常一挂到Client上就报协议错误。正确的调试姿势是在Server代码里用logging模块输出到独立文件或者把日志写到stderr因为MCP协议走的是stdout。只有理解了Client和Server之间的数据通道是什么才能解释为什么那个print会引发灾难性后果。第五个坑模型总是传错参数。前面提到过工具描述是模型的“使用说明书”但很多人不重视。我见过一个工具定义了city参数description是“城市名”模型却经常传一个包含经纬度的对象过去。后来我把参数description改成“城市中文名例如杭州、北京、上海”再在inputSchema里加上枚举值约束调用准确率直接上来了。模型不是人它没有常识所有关于参数的约束你都得显式写清楚。第六个坑Server端反复重启导致的资源堆积。本地模式每次启动都是新进程还好HTTP模式的Server通常常驻如果工具函数里创建了数据库连接池、文件句柄一定要做好复用和释放不然连续调用几十次之后Server响应会越来越慢最终拒绝连接。这是日常测试中容易被忽略的稳定性问题。6. 站在调用链高度重新规划学习路线如果让我重新学一遍MCP我会完全改变之前的思路先建立链路认知再逐环深入。按这条链的顺序学习可以分成五步。第一步先用现成的MCP Server跑通一个完整链路。这一阶段的目标是感受“从用户在对话框说话到工具被执行再回到用户看到结果”的全过程。不要写代码只需要在Claude Desktop或Cursor的MCP市场里装一个现成的Server比如文件管理或待办事项的跟它对话让它真实操作文件。这个过程帮你建立直觉工具在哪、谁在执行、返回的形态是什么。第二步自己实现一个最简单的Server和Client。文章前面的天气服务代码已经给了照着跑通。跑通之后再思考一个问题Server定义的工具Client是怎么拿到的答案是Client先发一个tools/list请求Server返回工具描述列表。想验证的话可以自己在Client代码里print一下session.list_tools()的原始返回结构。这一步是把链路从“黑盒”变成“白盒”的关键。第三步深入协议细节重点吃透JSON-RPC的报文格式和Initialize握手。这个阶段你会发现网上很多源码分析文章都能看懂了。你不需要背下所有消息类型的字段但至少要看得懂一次会话里的关键报文。我的建议是给本地Server加一层日志把Client和Server之间互相发送的消息记录下来对照协议文档看一遍收获很大。第四步学习SDK的封装逻辑。官方Python SDK用了很多抽象比如给函数加个装饰器就能变成工具。这阶段你应该自己尝试不依赖FastMCP用最底层的SDK手写一个Server或者读FastMCP源码看它底层是如何把函数签名转成JSON Schema的。搞明白了这些以后遇到SDK升级导致行为变化的时候你不会一头雾水。第五步实战扩展。接上真实数据库、真实API、长耗时任务、鉴权体系把小demo变成生产可用工具。到了这个阶段你遇到的问题基本就是链路各环节的质量问题了Server稳定不稳定、请求慢不慢、工具描述准不准、模型调用策略对不对。这些问题没有统一的参考答案需要你回到链路中定位用排错方法论去解决而不是搜一个“标准答案”。回到最初的问题MCP的核心到底是什么毫无疑问就是这条调用链。它没多玄乎一端是AI应用一端是工具中间的MCP协议把所有连接规则标准化了。搞懂了谁在哪一环、数据怎么流动、故障发生在哪一段你在任何社区看到任何关于MCP的讨论都能快速定位到对应的环节然后有针对性地研究。希望我这段时间的思考和踩坑记录能帮你省下一些在概念泥潭里挣扎的时间。后面我还会整理一份我实际用过的MCP Server清单和配置模板下一篇继续聊。
