先抛个引子你是不是也见过这种场景同一个AI编程助手有的人拿它只能聊天翻译有的人却能指挥它直接查数据库、改Figma设计稿、调浏览器自动化跑E2E测试。差距不在模型智商而在“连接”这件事上做没做对。2024年底Anthropic把MCP协议推向开源社区之后AI Agent的玩法一下子变了——从“单聊”进化成“即插即用地接入各种系统”。这篇文章我就以自己的实战过程为例把MCP是什么、Server和Client之间怎么对话、怎么从零手写一个MCP服务、以及怎么接到AI Agent里跑起来完整过一遍重点讲那些文档里不写、但你实际动手一定会踩的坑。1. 内容整体设计与思路拆解1.1 MCP到底是什么给AI插上“通用U盘接口”MCP全称Model Context Protocol中文常叫模型上下文协议。我更喜欢叫它“AI外设的USB接口”。你想想电脑要接键盘、鼠标、打印机靠的是USB口加驱动AI Agent要接数据库、设计工具、浏览器、监控系统以前靠每家各写各的插件现在MCP把这个过程统一成了标准协议。标准协议解决什么解决重复造轮子。在MCP出现之前AI Agent接入一个工具基本是这么干的写一段Python脚本调API、把返回结果拼进Prompt、再告诉模型“这个JSON是这个意思”。每接一个新系统这套逻辑就得重写一遍。而且工具之间还不能共享A项目写的MySQL查询函数B项目没法直接用。MCP把这个问题拆成三层协议层规定消息格式和传输方式Server层负责暴露工具和数据源Client层负责跟AI模型对接。做出一个MCP Server之后只要客户端支持MCP不管是Claude Desktop还是Cursor还是自研Agent都能直接“插上就用”这才是“即插即用”的真实含义。1.2 为什么2025年这一年MCP突然火起来你看现在的热搜词里从“cursor连接蓝湖mcp”到“wazuh mcp服务器”再到“burpsuite mcp”覆盖了设计、安全、游戏引擎、数据可视化这么多领域说明MCP不是小众技术而是正在变成AI Agent的标配接口。原因其实不复杂。第一AI编程工具打得火热Cursor、Codex、Trae都需要连用户的私有数据MCP提供了一套统一的方式开发者写一次就能到处用。第二MCP是Anthropic开源并推动的Claude生态带动了热度其他厂商跟得也快。第三MCP把“Agent能干什么”的边界问题交给工具去定义模型只负责决策和调用这个分工让复杂任务变得可拆解、可调试。这里要强调一个容易混淆的点MCP和Function Calling不是一回事也不是替代关系。Function Calling是模型API层的能力让模型输出一个结构化调用指令MCP是应用层协议解决的是工具“怎么注册、怎么被发现、怎么被调用”的统一标准。两者可以配合使用也可以单独存在。1.3 我的MCP实战目标做一个能查GitHub星标的Server纸上谈兵没用我这次实战选了一个最典型、最能说明问题的场景做一个MCP Server功能只有一个——输入仓库名返回它的Star数和最近更新时间。为什么选这个第一GitHub API免费、无需鉴权也能用降低了门槛第二它调用的是外部HTTP接口能完整展示MCP里“Agent发出请求→Server解析参数→Server调外部API→返回结构化结果→Agent理解结果”这条完整链路第三这个Server做完之后不管是Claude Desktop还是Cursor都能接能直观体会“即插即用”。为了让过程更有参考性我还会配一个MySQL查询的Server做对比说明MCP在私有数据场景下的价值。咱们不搞花活就一步步把Server写出来、跑起来、接进去。2. 核心细节解析与实操要点2.1 MCP协议里的三个核心角色Server、Client、Agent先理清概念后面写代码才不迷糊。MCP架构里一共有三个角色。MCP Server暴露能力的一方。它声明“我能做什么”提供三种能力——工具Tools、资源Resources、提示词Prompts。工具是最常用的就是可调用的函数资源是暴露给模型读取的上下文数据提示词是预定义好的对话模板。MCP Client连接Server和Agent的中间层。它负责跟Server建立连接、拉取工具清单、发起调用请求。Claude Desktop、Cursor内置的MCP支持本质就是内置了一个MCP Client。AI Agent决策大脑。它从Client拿到工具清单后根据用户的任务决定“该调哪个工具、传什么参数”然后把调用结果拼回上下文继续推理。我用一个生活化类比来帮你记Agent是老板Server是供应商Client是秘书。老板不知道供应商的联系方式秘书负责维护通讯录工具清单老板说要查数据秘书打电话给供应商发起调用拿到结果再转述给老板返回上下文。2.2 MCP的传输与消息格式JSON-RPC 2.0MCP目前主流的传输方式是Streamable HTTP早期是stdio消息格式走JSON-RPC 2.0。这意味着什么意味着所有交互都是“发一个JSON请求、收一个JSON响应”跟你调普通HTTP接口没有本质区别。具体来说Client和Server建立连接之后会先发一个tools/list请求Server返回工具名、描述、参数结构Agent根据这个清单生成调用意图Client再发tools/call请求带上工具名和参数Server执行完返回结果结果里可以带结构化内容JSON、文本内容甚至是图片资源。这个设计的好处是传输层只负责搬JSON业务逻辑全在Server端所以传输层以后就算从HTTP换成WebSocketServer端的核心代码也不用大变。我后面写Server时你会看到真正要写的核心逻辑其实是“处理tools/call”那部分。2.3 工具选型Python FastMCP还是TypeScript SDKMCP官方SDK有Python和TypeScript两套社区还有各种封装。我个人建议想做原型验证、快速跑通的选Python的FastMCP库想深度集成前端生态、做生产级服务选TypeScript官方SDK。我这次用Python FastMCP理由是FastMCP把SDK的样板代码简化得很干净一个装饰器就能定义一个工具十行左右就能跑起一个Server。对新手来说这个上手体验非常重要不至于被协议细节劝退。如果你要在Cursor或VS Code Copilot里用MCP客户端侧的配置方式略有不同但Server侧完全通用。记住这句话MCP Server不挑客户端只要客户端支持MCP协议接谁都能用。3. 实操过程与核心环节实现3.1 从零搭建FastMCP开发环境先准备环境我假设你已经装好了Python 3.10以上版本。在终端里建一个项目目录和一个虚拟环境mkdir mcp-demo cd mcp-demo python -m venv .venv # Windows .venv\Scripts\activate # macOS / Linux source .venv/bin/activate pip install fastmcp httpx这里装了两个依赖fastmcp是核心库httpx用来调GitHub API。有人会问为什么用httpx而不是requests因为httpx支持异步FastMCP原生支持异步工具后面写并发请求时不用改架构。装完之后可以验证一下python -c import fastmcp; print(fastmcp.__version__)看到版本号输出就说明环境OK。这一步我建议不要跳过很多人后面报错发现是环境没装对白白浪费半小时。3.2 手写一个GitHub星标查询Server在项目目录下新建github_star_server.py这是整个Server的核心文件。我先把完整代码贴出来再逐段拆解import httpx from fastmcp import FastMCP mcp FastMCP(GitHub Star Server) mcp.tool() def get_github_stars(repo: str) - dict: 获取指定GitHub仓库的星标数和最近更新时间。 Args: repo: GitHub仓库名格式为 owner/repo例如 anthropics/anthropic-sdk-python url fhttps://api.github.com/repos/{repo} response httpx.get(url, timeout10) if response.status_code 404: return {error: 仓库不存在请检查名称是否正确} if response.status_code ! 200: return {error: fGitHub API返回异常状态码: {response.status_code}} data response.json() return { repo: repo, stars: data[stargazers_count], description: data.get(description, ), last_updated: data[updated_at], html_url: data[html_url], } if __name__ __main__: mcp.run(transportsse)不要小看这几十行它包含了几个很关键的实践细节。细节一docstring不是注释是给模型看的“工具说明书”。FastMCP会把函数名和docstring发给LLM模型通过这些描述判断“这个工具是干嘛的、什么情况下该调用”。我在docstring里明确写了格式是owner/repo还给了示例这样模型就知道怎么从用户的话里提取参数。很多人写的工具明明能用但模型就是不调用十有八九是描述不清晰。细节二错误处理要返回给人看的消息而不是抛异常。如果GitHub API返回404我直接返回一个带error字段的字典这样Agent拿到结果后能自行推理出“仓库不存在”然后转告用户。如果这里直接抛异常很多客户端会显示一长串堆栈体验很差而且模型无法理解到底发生了什么。细节三transportsse表示用SSEServer-Sent Events传输方式。这是目前MCP客户端兼容性最好的一种方式。早期推荐的streamable-http在某些老版本客户端上有兼容问题所以我建议新手先用SSE跑通之后再考虑换其他传输。3.3 把Server接到Claude Desktop里Server写好了先本地跑一下确认没有语法错误python github_star_server.py看到类似“Started SSE server on /mcp”的日志就说明Server在跑了。接下来把它接到客户端里。我用Claude Desktop举例因为它的配置最直观。打开Claude Desktop的配置文件路径通常是~/Library/Application Support/Claude/claude_desktop_config.json加一段{ mcpServers: { github-stars: { command: python, args: [/绝对路径/你项目目录/github_star_server.py], env: {} } } }注意这里不是填http://localhost:8000这种地址而是填启动命令。Claude Desktop会自己拉起子进程运行这个Python脚本。这也是MCP的灵活之处——Server既可以是远程HTTP服务也可以是本地子进程。保存配置文件重启Claude Desktop然后在对话框里输入“查一下anthropics/anthropic-sdk-python这个仓库有多少star”。正常情况下模型会调用get_github_stars工具然后告诉你结果。第一次跑通这个流程时我确实感觉“通了、真的通了”——不是聊聊天是它在按我的要求主动查外部数据还自己决定用什么参数。这个体验跟以前纯靠Prompt工程是完全不一样的。3.4 扩展实战做一个MySQL查询Server光查GitHub星标还不够过瘾我再加一个能体现“连接私有系统”的Server。假设你本地有个MySQL数据库里面有张订单表你想让Agent帮你查订单数量。先装依赖pip install pymysql然后写mysql_server.pyimport pymysql from fastmcp import FastMCP mcp FastMCP(MySQL Query Server) DB_CONFIG { host: 127.0.0.1, user: root, password: your_password, database: shop, } mcp.tool() def query_orders(status: str None) - dict: 查询订单表数据。 Args: status: 订单状态可选值为 pending、paid、shipped、completed。不传则查询全部。 sql SELECT id, customer, amount, status FROM orders params [] if status: sql WHERE status %s params.append(status) sql LIMIT 50 conn pymysql.connect(**DB_CONFIG) try: with conn.cursor() as cursor: cursor.execute(sql, params) rows cursor.fetchall() columns [desc[0] for desc in cursor.description] result [dict(zip(columns, row)) for row in rows] return {total: len(result), rows: result} except Exception as e: return {error: str(e)} finally: conn.close() if __name__ __main__: mcp.run(transportsse)这个例子想说明一个事MCP Server最大的价值不是接公开API而是把私有数据安全地暴露给AI Agent。你的数据库密码、连接串都写在Server端模型只看到工具名和返回结果接触不到底层细节。这就比“把SQL拼接进Prompt”安全得多。接MySQL这个Server时配置文件和前面GitHub那个完全一样只是换个名字和路径。你可以在同一份配置里同时挂两个ServerClaude Desktop会自动合并所有工具给模型用。多个Server之间互不干扰这就是“即插即用”最直观的体现。3.5 在Cursor里玩MCP几种常见连接的配置方式Cursor是我日常用得最多的AI编程工具它支持MCP的方式跟Claude Desktop略有不同。在Cursor里点开Settings → Tools → MCP可以看到所有已连接的Server。添加一个远程MCP Server比如有人部署好的公开Server直接在URL框里填SSE地址比如https://example.com/mcpCursor会自动探测并连接。添加一个本地脚本Server选择“Add local MCP Server”填启动命令和参数跟Claude Desktop里的配置逻辑一样。用VS Code Copilot连接Figma MCP这种操作本质也是给编辑器配置一个MCP服务器。你需要在Copilot的配置目录下指定MCP服务器的地址或命令然后它就会自动把Figma设计文件的信息作为上下文喂给AI。从热搜来看这个问题问的人很多注意一点Figma MCP通常需要你提供Figma的Access Token这个Token要放在Server端的环境变量里不要写死在对话里发给模型。我实测下来一个感受Cursor对MCP工具的支持已经相当成熟模型自动决定调用工具的成功率比Claude Desktop还要高一点因为它把工具描述和当前代码上下文融合得更好。4. 常见问题与排查技巧实录4.1 Server连接上了但模型就是不调用工具这是我被问得最多的问题也是我被坑得最惨的问题。现象很统一配置没报错工具清单也拉到了但模型就是“视而不见”该自己瞎编还自己瞎编。排查思路按顺序来第一步检查工具描述是否够具体。模型的调用决策完全依赖工具名和docstring。如果你的工具描述写的是“查询数据”这种模糊描述模型根本不敢用。我自己的经验是docstring要写清楚“什么时候用、参数格式是什么、返回什么”。你可以故意把描述写得长一点把边界情况也写进去。第二步检查是否同时挂了太多Server。工具清单越长模型的选择成本越高。你挂了20个Server每个3个工具模型要在一堆工具里挑容易挑错或挑不出来。建议只保留当前任务需要的Server。第三步给模型一个明确的触发场景。有些客户端默认不太喜欢主动调工具你得在对话里带上明确的意图词。比如直接说“用工具查一下”比说“帮我看看”更容易触发。4.2 调用工具后报超时或“Connection reset”这个大概率是网络问题但要注意区分两种情况。本地Serverstdio方式报连接重置先看子进程有没有崩溃。直接在终端手动运行那个Python文件看看能不能正常启动、有没有报错。很多本地Server配置看着没问题一跑就发现端口被占、依赖缺失、路径写错这些错误在客户端里都被统一显示成“connection reset”很误导人。远程ServerHTTP/SSE方式报超时先确认Server确实在跑、端口没被防火墙挡着。可以用curl测一下MCP的SSE端点看能不能拿到预期响应。如果你部署在云服务器上记得检查安全组有没有放行对应端口。4.3 工具返回了结果但模型理解错了这个问题比较隐蔽。比如我的get_github_stars返回的last_updated字段是字符串2025-06-01T12:00:00Z模型读出来之后如果用户问“最后更新是什么时候”它能正常回答但如果用户问“最后更新是几号”有些模型会把整个字符串念出来不会主动换算时区。解决思路是在Server端就把数据清洗到“人类可直接读”的程度。我在实际版本里会把updated_at先格式化一遍再返回给模型不给它自由发挥的空间。另外返回的字段名也很重要尽量用语义化名称比如display_last_updated比updated_at更不容易让模型产生误解。4.4 MCP配置改了但没生效改了claude_desktop_config.json重启客户端之后发现还是老样子——这个通常不是配置问题而是JSON格式错了。MCP配置如果解析失败客户端默认会静默忽略而不是弹窗报错。你可以在终端里跑一下python -m json.tool claude_desktop_config.json有输出说明JSON合法。如果没有输出且报错那就是多了逗号、少了括号这类低Level错误改对了再重启客户端。4.5 常见问题速查表现象可能原因快速排查方案配置了但工具列表为空JSON格式错误或Server启动失败手动运行脚本检查输出日志模型不调用工具工具描述不够清晰重写docstring加入触发场景和参数示例调用返回超时网络不通或子进程崩溃curl测试SSE端点检查安全组返回数据能被看到但回答错误返回字段语义不明确在Server端格式化数据精简字段多个Server工具互相干扰工具名冲突或清单过长给每个工具加统一前缀减少Server数量4.6 还有几个容易踩的暗坑暗坑一Python版本太老。FastMCP要求Python 3.10以上用3.8、3.9跑会直接报语法错误。装之前先确认python --version。暗坑二端口冲突。你本地跑了多个MCP Server如果都用了默认端口第二个就会起不来。建议在mcp.run()里显式指定端口比如port8001避免冲突。暗坑三工具名称冲突。如果两个Server都定义了query这个工具客户端合并工具清单时可能互相覆盖。我的习惯是给工具名加前缀比如github_get_stars和mysql_query_orders名字长一点没关系但一定要唯一。暗坑四别在生产环境犯的错——把数据库密码硬编码在Server脚本里。用环境变量传连接串或者用本地密钥管理服务否则一个不小心把配置文件提交到Git仓库密码就暴露了。MCP Server虽然是本地跑的但它也是程序同样要按生产标准来。5. 更多场景与扩展玩法5.1 不只是编程工具安全测试、游戏引擎、设计工具里的MCPMCP的火爆远远超出编程辅助工具的范围。从热搜词里你就能看到它在往各种垂直领域渗透。安全测试领域的Burp Suite MCP渗透测试人员把Burp抓到的包通过MCP暴露给AI AgentAI就能直接分析请求、对比响应、甚至尝试生成测试Payload。这极大减少了人在测试工具和AI助手之间来回Copy-Paste的工作量。游戏引擎里的Unity MCP和Cocos Creator MCP游戏开发者在编辑器里通过MCP让AI直接操作场景对象、查询组件状态、生成C#或TypeScript脚本。设计资源和AI编程之间第一次有了这么顺畅的通道。设计工具里的Figma MCP、蓝湖MCP前端开发最大的痛点是“设计稿和代码对不上”。有了Figma MCPAI能直接读Figm文件的图层结构、尺寸、颜色变量然后生成更精准的还原代码。蓝湖MCP的逻辑类似但对国内团队更友好很多人从热词里找它也是因为这个。运维安全领域的Wazuh MCP把Wazuh的安全告警通过MCP暴露给AI让AI做初步的告警研判。这是安全运营自动化一个很好的方向。这些场景共同说明一件事MCP是AI Agent的“通用接口层”谁支持谁就进Agent的“工具库”。学会做一个MCP Server等于你掌握了一种不管接什么系统都能用同一套思路搞定问题的能力。5.2 Skills和MCP怎么配合还有一个高频问题Skills和MCP是什么关系我的理解是Skills偏“流程编排”MCP偏“工具接入”。Skill定义的是“遇到这类任务要按什么步骤做”MCP定义的是“有哪些原子能力可用”。比如你在Cursor里配了一个“从Figma设计稿还原登录页”的Skill里面可能规定第一步读取Figma图层第二步提取颜色变量第三步生成React组件第四步做响应式适配。而每一步真正去执行的时候调的还是Figma MCP暴露出来的那些工具。所以Skill带着模型做规划MCP给模型提供弹药两者是配合关系不是替代关系。5.3 未来的Agent开发MCP会变成标配吗从整个行业的热度和工具链的成熟度来看MCP正在走向“AI Agent的水电煤”。2026年之后Agent开发可能不再需要关心“怎么去接某个具体服务”直接找现成的MCP Server就行。就像现在写Web应用不需要自己实现HTTP协议一样。但这并不意味着深入理解底层机制没意义。恰恰相反真正能做出差异化价值的是那些把私有工具封装成高质量MCP Server的人。协议本身很快会变成基础设施但怎么把自己团队的数据库、API、内部系统安全高效地封装给AI用这个能力会越来越值钱。我在实际运用中还有一个小技巧做MCP Server时不要一上来就追求把所有功能都暴露出去先只暴露两三个高频工具跑通再迭代。模型在工具数量少的时候调用准确率会高很多这对新项目调优特别有帮助。另外每次修改Server代码之后记得在客户端里重连一次有时候工具列表缓存不会自动刷新会让人误以为改动没生效。最后想提醒一点MCP目前的版本协议还在快速演进中你写Server时尽量用官方维护的SDK跟着大版本走不要自己去实现底层协议细节否则升级时很容易踩兼容性的坑。