MCP 这个缩写最近在 AI 工具链的圈子里几乎天天被提起如果你翻过一些相关技术帖应该对 Model Context Protocol模型上下文协议有印象。我自己的感觉是MCP 正在把AI 接入外部工具这件事从手工作坊推进到标准件时代。以前接一个工具要写一堆胶水代码现在大家照着协议来就行。这篇文章不聊概念史直接聊开发——怎么从零开始写一个真正的 MCP Server 和 Tool顺便把我自己踩过的坑、测试下来好用的调试方式、以及上线部署前那些容易忽略的细节都梳理一遍。如果你正准备用 MCP 把自家业务能力开放给 AI 客户端或者想让本地 Agent 能调用几个内部工具这篇文章应该能让你少走不少弯路。1. 为什么是 MCP以及它的核心运行逻辑1.1 从集成地狱到统一协议在 MCP 出现之前AI 应用要接一个外部工具基本是每条链路单独对接。比如你的 AI 助手要查数据库、查工单系统、查内部文档那就得给每个系统各写一套函数调用逻辑还要处理认证、输入输出格式、错误重试这些重复工作。我见过不少团队维护着四五套互不兼容的工具适配层纯粹是为了让 LLM 能调用不同后端。MCP 的思路很朴素把AI 应用和外部工具/数据源之间的一致性接口抽出来做成一个标准协议。所有工具统一暴露成 MCP Server所有 AI 应用统一通过 MCP Client 去调用。这样工具只承担实现协议的成本AI 应用只承担连接协议的成本两边解耦。1.2 三个核心角色一次完整的 MCP 调用涉及三个角色Host承载 AI 应用的主体比如桌面端 AI 助手、IDE 插件、网关服务。它负责把用户意图交给模型再把模型想调用工具的意图转给 Client。Client就是 Host 内部集成的一个库负责和 Server 建立连接、发请求、收结果。Client 通常不需要你手写用官方 SDK 即可。Server真正干活的进程暴露出 tools、resources、prompts 三类能力核心是 tools。打个比方Host 是餐厅顾客Client 是服务员Server 是后厨。顾客说来一份少盐的番茄炒蛋服务员把需求转述给后厨后厨按标准流程做菜并端回来。这个标准流程就是 MCP 要定义的东西。1.3 通信机制JSON-RPC 2.0 与两种传输方式MCP 的通信协议基于 JSON-RPC 2.0这个消息格式本身不复杂——method、params、result、error 四个字段打天下。但真正影响开发体验的是传输层目前主流有两条路stdioServer 以子进程方式启动Host 通过标准输入输出跟它通信。好处是零网络配置、天然安全适合本地个人工具。HTTP SSEServer-Sent EventsServer 作为一个远程服务客户端通过 HTTP 发请求、通过 SSE 收推送。适合多客户端同时访问、需要鉴权、需要跨机器部署的生产场景。开发初期先用 stdio 跑通逻辑再迁移到 HTTP这是最稳妥的路径。直接上 HTTP 容易把协议实现和网络问题两个变量搅在一起排查起来头疼。2. 动手选型语言与 SDK 的取舍2.1 语言怎么选MCP 目前最成熟的官方 SDK 是 Python 和 TypeScript。Python 生态在 AI 领域积累深FastMCP 这类封装可以让你用更少的样板代码做更多事适合内部工具或快速原型。TypeScript 在前端和后端领域渗透率高如果团队已有 Node.js 基础设施那选 TypeScript 能更好地复用现有工程体系。其他语言比如 Java、Go、Ruby、PHP 也有社区版或官方出品的 SDK但是成熟度和文档完整度参差不齐。我的观点是第一优先选 Python 或 TS除非你的服务端基建非常单一比如全公司只有 Go那再用 Go 的 MCP 库。2.2 一个 Server 可以挂多种能力的组合不要把 Server 理解成一个工具它是一个能力容器。你可以把一个 Server 设计成统一的内部数据查询台里面同时注册数据查询 Tool、指标字典 Resource、对话排障 Prompt。这样客户端只需要连一个 Server就能得到一整组能力。开发时也可以按域拆多个 Server比如订单域库存域按需连接。2.3 选 FastMCP 还是底层 SDKPython 生态里直接用官方 SDK 写一个 MCP Server 会有不少模板代码比如初始化 Server 对象、注册 handler、做生命周期管理。而 FastMCP 这个库把注册工具的方式简化到一个装饰器几乎就是写普通函数。我用下来更推荐 FastMCP它把样板代码压得很低核心逻辑的辨识度很高后面接 HTTP 传输也只需要改一行。TypeScript 官方 SDK 目前做得也不错默认提供清晰的 Transport 抽象底层控制力更强。如果你对协议本身有定制需求用底层 SDK 会更顺手。3. 用一个 QueryTool 讲透 Server 开发全过程3.1 场景与目标我拿一个模拟场景来演示开发一个订单查询工具 MCP Server接收一个订单号返回订单状态、金额、下单时间。这个工具如果接入到 AI 客服系统里用户一句帮我看看我 20240401 的订单AI 就会自动查出来。放弃暴力的把数据库接入给 AI方案采用 QueryTool 方案的原因是数据库直接暴露给 LLM 风险极大表结构容易泄漏、SQL 容易被乱写、生产库有被拖垮的风险。而 Tool 方案有完全可控的入参、可限制的查询逻辑、可追加的权限校验。3.2 项目初始化和依赖安装先建一个干净的虚拟环境mkdir mcp-order-server cd mcp-order-server python -m venv .venv source .venv/bin/activate pip install mcp[cli]1.2.0 fastmcp装完确认版本python -c import fastmcp; print(fastmcp.__version__)如果启用了其他集成 Sdk比如生态工具包也一并装好。这是标准前置步骤。3.3 核心代码三层结构一次写清下面是一个结构清晰的最小实现代码可以直接复用骨架# server.py from fastmcp import FastMCP mcp FastMCP(订单查询服务) def _get_order_from_db(order_id: str) - dict: # 真实项目这里会走数据访问层控权限、加监控 # 示例中返回模拟数据 return { order_id: order_id, status: 已发货, amount: 299.00, created_at: 2024-04-01 10:22:00 } mcp.tool() def query_order(order_id: str) - dict: 根据订单号查询订单状态、金额和创建时间。 Args: order_id: 完整的订单号例如 2024040112034567。 if not order_id or len(order_id) 10: return {error: 订单号格式不正确} return _get_order_from_db(order_id) mcp.resource(order://{order_id}) def order_resource(order_id: str) - dict: 以 Resource 方式暴露只读数据便于描述性引用。 return _get_order_from_db(order_id) if __name__ __main__: mcp.run(transportstdio)这段代码里最需要注意的是mcp.tool()下面的函数注释。MCP 对工具的 JSON Schema 是根据函数的签名和注释自动生成的。docstring 里对参数的说明写得多清楚AI 调用工具时就有多明白。不少人图省事不写参数说明结果 AI 调用时总是把字段名猜错这就是常见的工具在模型眼里是黑盒问题。mcp.run(transportstdio)这行是入口告诉 FastMCP 用 stdio 模式启动。等代码跑通后把 transport 改成http即可切到远程模式我后面第 5 章会专门讨论部署切换的细节。3.4 启动并接入客户端本地验证最简单的办法是用 MCP Inspector 这个官方的调试界面。命令行执行mcp dev server.py这个命令会把服务启动到调试模式然后自动打开一个本地的 Inspector 页面。在页面里你可以直观地看到 Server 暴露出的工具名、工具描述、JSON Schema以及你直接模拟调用之后返回的结果。我自己的习惯是先在这里把函数调用通了再接到任何上层客户端。如果接到支持 MCP 的桌面端 AI 客户端在配置里填入命令python /path/to/server.pySSE 远程模式则填https://your-domain.com/mcp第一次接桌面端时注意看客户端有没有在工具列表里扫到query_order。如果迟迟扫不到优先怀疑 Server 启动时报错了正常启动的进程会有握手日志建议先用 Inspector 确认端口。3.5 一个突发的边界问题参数格式校验我实际测试这个 QueryTool 时遇到一个很有意思的情况AI 在调用query_order时传入的order_id是202404011203465这种长度但字段本身被偷偷加了空格或者带了前缀#ORD-。如果你不做入参清洗请求会打进数据库层才失败错误信息又长又难看。所以我在工具里加了一个显式的 clean 和校验逻辑mcp.tool() def query_order(order_id: str) - dict: 根据订单号查询订单状态、金额和创建时间。 Args: order_id: 订单号需要是纯数字字符串。 order_id order_id.strip().removeprefix(ORD-) if not order_id.isdigit() or len(order_id) ! 16: return {error: 订单号格式不正确应为16位纯数字} return _get_order_from_db(order_id)不要迷信AI 一定会传干净的参数LLM 的输出在格式上天然具有不确定性。一个 Tool 除了核心逻辑必须自己兜住入参校验。这个习惯能省掉大量下游异常排查。4. 调试、测试与为什么工具调用总是失败4.1 日志与输出的隔离陷阱开发 MCP Server 时最容易被表象迷惑的就是日志。你如果在代码里用了print()来调试在 stdio 模式下这些 print 内容会直接打到 stdout 上而 stdout 正是 MCP 协议通信的通道。这样会直接污染协议流导致客户端解析失败表现为连接成功但收不到工具列表或调用时超时。正确的做法是全部用logging模块并把日志打到 stderrimport logging logging.basicConfig(levellogging.DEBUG) logger logging.getLogger(mcp-order-server) logger.info(query_order called with %s, order_id)本地排查协议问题先分清三层第一层Server 有没有正常启动看进程日志。第二层工具的 JSON Schema 有没有生成看 Inspector。第三层工具调用结果是否正常返回看 Inspector 模拟调用。多数工具失效问题都卡在第二三层很少需要抓原始 TCP 包。4.2 测试策略单测之外补一轮带 LLM 的端到端测试传统的工具开发者容易犯的毛病是只做单元测试把函数逻辑测通了就以为大功告成。但 MCP 工具层的特殊性在于真正调用它的是 LLMLLM 对工具的理解与你代码里的 docstring 直接相关。你注释里写订单号需要是16位纯数字AI 如果是先脱敏后传参大概率是对的但如果文档描述模糊AI 可能会传余额字段来查订单或者把order_id写成了orderNumber。我的经验是加一层端到端测试准备 5-10 个真实风格的自然语言问句。跑一个带工具的客户端会话让它依次回答这些问题。人工检查 AI 每次调用工具时的参数是否如预期。这种做法能提前发现大量看起来工具能用、接上 AI 就不能用的问题。4.3 命名的坑use tool 名的语义要收敛工具命名直接影响 LLM 的识别准确率。比如你把一个查订单状态的工具命名为get_dataLLM 可能分不清它到底是查订单、查库存还是查物流调用成功率会明显下降。更推荐的做法是把工具名设计成动词业务对象如query_order_status、query_inventory_quantity。工具的 description 也可以写得像一句明确的能力声明比如查询订单的实时状态和配送进度输入订单号即可。我在多个命名实验中发现描述里把不支持的能力也顺带写进去如不包含物流轨迹物流轨迹另查 trade_logistics可以显著减少错误调用。5. 远程化部署stdio 转 HTTP 的完整过渡5.1 生命周期管理的变化本地 stdio 模式下Server 的生命周期跟客户端进程一致——客户端启动它启动客户端退出它退出。转成 HTTP 模式后Server 变成常驻服务需要考虑四个原来没有的问题并发多个客户端同时连上每个请求是否安全隔离。鉴权谁有权限调用工具。超时与重试网络请求什么时候算失败。审计工具被谁调用、每次传了什么参数。FastMCP 如果需要开启 HTTP 模式需要加一个额外的异步服务器入口from fastmcp import FastMCP mcp FastMCP(订单查询服务) # ... 工具定义 ... if __name__ __main__: mcp.run(transporthttp, host0.0.0.0, port8080)启动后HTTP 服务提供一个端点客户端通过配置这个 URL 建立 SSE 流式连接。注意这里跟普通 REST API 的区别MCP 的 HTTP 传输并不是每次请求打一次接口这么简单它需要建立一个持久化的 SSE 通道让服务端可以主动给客户端推送事件。这个语义的转变意味着你的负载均衡、健康检查配置也要跟着调整不能简单按 HTTP 请求数来压测。5.2 鉴权与多租户隔离远程化之后第一个要解决的问题是鉴权。MCP 官方协议目前提供的鉴权方案可以内嵌 OAuth 2.1 流程也可以直接加在反向代理层。我实际部署时的做法是统一走公司内部网关网关层完成单点登录认证生成短期 token。MCP Server 每次收到请求都验证 token并从 token 里解析出用户身份和角色。在 Tool 函数内部根据身份做数据权限过滤。举个具体场景同样是query_order普通客服角色只能查自己团队负责的订单而大区总监可以查整个大区订单。这一切不能靠 LLM 自觉必须在 Server 里硬编码权限边界。你要清楚一个事实LLM 可以骗一个没有鉴权的工具所以所有危险操作都必须有一层硬校验——比如只允许 SELECT、不允许 UPDATE。5.3 日志、监控、限流生产级部署别忘了打日志。我的建议是从第一版上线就只有意识地记录三个信息时间戳与唯一请求 ID。入参摘要注意脱敏千万别整单号全量打进去。响应状态、耗时、最终用户身份。限流层面面向内部使用可以先做全局限流比如每客户端每分钟最多 60 次调用。如果工具推动的是 LLM 调用LLM 的循环调用有时会产生突发流量不加限流底层数据库或第三方依赖很容易被打满。我在一台测试机上曾见过循环调用把第三方查询接口打到超时就是因为没有给工具加流量闸门。5.4 一个常见误区和进阶方向远程化还有一个常见误区以为 MCP Client 只能由一个 AI 应用来连。实际上你完全可以直接用 MCP Client SDK 把 Server 包一层做成一个内部命令行工具、一个定时任务甚至一个异步 Worker。MCP Tool 的本质是能力封装不是 AI 专属 API。这个点想通之后同一个 Server 可以复用在多个业务链路里工具函数变成一套可复用的中间层能力跨业务暴露价值。6. 进阶设计资源、提示词与复杂工具模式6.1 Resource 不只是数据还是上下文的引子Resource 在 MCP 里可以理解为只读数据的描述性入口。它和 Tool 最大的区别是Tool 是一次动作Resource 是一个可被引用的数据对象。比如我在 Server 里注册了一个order://{order_id}的 ResourceAI 在回答用户时可以在上下文里引用关于订单的资源然后让工具去查更多。Resource 很适合把数据模型、元数据、配置项这些内容暴露给模型让模型在交互时拥有足够的背景知识。6.2 Prompt 模块化沉淀调用经验MCP 的 Prompt 能力也值得善用。你可以把客服对话时如何查询订单的提示模板做到 Server 里客户端连接后自动拿到这些模板。每次接新客户端时不用重新从零调提示词直接在客户端侧选一个模板就能获得不错的效果。这对团队合作的价值很高相当于把怎么用这套工具最顺的经验沉淀成配置。6.3 复杂工具多输入参数的组合查询当工具的参数超过三个就要考虑设计成结构化的组合查询了。比如企业内部的订单查询工具除了订单号还支持客户名称时间范围状态的组合过滤。这种工具的输入要用 JSON 对象而不是平铺参数。我的实现方式from pydantic import BaseModel class OrderQueryParams(BaseModel): order_id: str | None None customer_name: str | None None date_from: str | None None date_to: str | None None status: str | None None mcp.tool() def query_orders_advanced(params: OrderQueryParams) - list[dict]: 按组合条件查询订单列表条件可任意组合至少需要提供一个字段。 return _query_orders(params)把它设置成 Pydantic Model 有两个好处FastMCP 能直接把 Model 转成结构良好的 JSON Schema 给 LLM。字段级校验在入口处就完成了非法值不会泄漏进下层。6.4 长耗时任务的模式选择MCP 工具是同步调用还是异步结果回传取决于传输方式。HTTP SSE 模式下可以采用立即返回一个任务 ID后续通过 Resource 或事件通道查询进度的方式stdio 模式下则建议保持同步调用设定合理的超时上限。我自己做数据重算类工具时倾向于异步任务模式——先让工具回一个任务已提交然后单独做一个查询进度的工具这样 LLM 不会因为长时间等待而误判调用失败。7. 上线前后一定要检查的十项清单开发接近尾声很多问题不是代码逻辑错而是部署形态没想全。下面这十项是我自己在每次部署之前都会过的清单也分享给你们照着检查基本能规避绝大部分上线事故Server 启动方式是否可被进程管理工具托管sudo systemd 或容器平台没有守护进程的话挂了没人拉。日志是否全量走 stderr 或独立文件没有污染 stdio 通道。Token 和密钥是否通过环境变量或密钥管理服务注入有没有硬编码进代码。工具入参是否做了基本校验尤其针对 LLM 输入的不确定性。数据库访问是否限定了最小权限集有没有按用户隔离数据范围。是否有审计字段可以追溯某次查询是哪个用户、哪个客户端触发的。超时时间是否合理过长会积累请求积压过短会误杀依赖的慢请求。并发数是否有压测数据支撑避免突发流量打满依赖。API 网关或负载均衡的会话保持是否适配 SSE 连接不然长连接容易被切断。配置文件是否有版本管理避免上线后改不回滚。其中第九条曾经让我费了不少时间。之前我把 MCP HTTP 服务部署到负载均衡后面结果发现客户端每隔几十秒就断连一次排查了很久才发现是网关的默认空闲超时时间太短把 SSE 长连接给掐了。这种问题在日志里特别隐蔽因为它不是报错只是连接被重置。如果你的网络拓扑里带有网关请务必检查空闲连接超时。8. 做 Tool 和做平台更长期的视角当你把第一个 Server 跑通之后建议退一步问自己一个问题团队里有多少场景其实可以抽象成同一种公共能力我的经验是与其给每个 AI 应用各自连一套独立 Server不如先梳理一下内部公共数据接口按业务域做成统一的 MCP Server 组。比如订单域、商品域、库存域、用户域每个域一个 Server所有上层应用按需连接。这能让团队沉淀出一层稳定的AI 可调用中间层后续做新的 AI 功能成本会肉眼可见地下降。从工程角度讲MCP 的标准化还带来一个隐性收益新员工入职后学习如何提供工具能力不再需要翻旧项目的胶水代码只需要看协议和 SDK 文档。这对团队长期维护的成本是很大的改善。如果你现在正处在要不要上车 MCP的观望期我的建议是先拿一个低频、只读、不敏感的工具跑通全链路比如查应用版本信息或者查配置字典。这个周期一般不会超过半天却能完整经历从开发、调试到接入客户端的全部过程比看十篇文章都有用。跑通之后再逐步扩大工具覆盖范围步步为营风险完全可控。