1. 为什么要把 REST API 封装成 MCP 服务手里有一套跑了很久的 REST API接口稳定、文档齐全、调用方也不少但最近半年我越来越频繁地遇到同一个尴尬想让 AI 助手直接帮我操作这些接口结果要么是手动写一堆胶水代码要么是让模型自己拼 URL 和参数十次里有三次拼错字段名。REST API 是给程序员的 HTTP 客户端设计的不是给模型设计的这两者的“使用姿势”根本不在一个频道上。MCPModel Context Protocol解决的正是这个错位问题。它本质上是一套让模型能够以结构化方式发现和调用外部能力的协议模型不需要猜你的接口长什么样而是通过 MCP 服务暴露出来的工具描述明确知道“有这么个工具、它接受哪些参数、每个参数是什么类型、返回什么”。这跟 REST 里靠 OpenAPI 文档 人工阅读的方式完全不同MCP 的工具描述是直接喂给模型的上下文模型可以自主决策调用哪个工具、传什么参数。把现有 REST API 封装成 MCP 服务核心价值有三个。第一是复用你不需要重写业务逻辑REST 层继续对外服务MCP 层只是加了一个“翻译适配器”。第二是可控哪些接口暴露给模型、参数怎么校验、返回怎么裁剪全在你手里而不是把整个 API 网关裸奔给模型。第三是可观测MCP 服务的调用日志、参数校验失败、超时重试都能按你的规范统一处理。这篇文章适合两类人一类是手里有成熟 REST API、想快速接入 AI 工具链的后端或平台工程师另一类是想理解 MCP 服务到底怎么落地、不想只看概念介绍的技术负责人。我会用 FastMCP Pydantic 这套组合把封装过程拆到能直接抄作业的程度包括参数映射、错误处理、鉴权透传、流式输出这些实际会踩坑的地方。需要先说明一点MCP 本身还在快速演进不同客户端对协议版本、传输方式的支持程度不一样。我下面讲的是基于当前主流实践的方案具体到你自己的环境传输层选型stdio 还是 HTTP需要根据客户端能力来定这一点后面会专门讲。2. 封装前的整体设计与关键取舍2.1 先想清楚MCP 服务不是 REST 的镜像很多人第一反应是“我有 20 个 REST 接口那就暴露 20 个 MCP 工具”。这个思路在接口少的时候没问题但接口一多就会出问题模型的上下文窗口是有限的工具描述太多会挤占推理空间而且模型在几十个相似工具里选错的概率会明显上升。我的做法是按业务场景聚合而不是按 REST 端点一一对应。举个例子假设你有一套订单相关的 REST API创建订单、查询订单、取消订单、修改地址。这四个接口在 REST 世界里是四个端点但在 MCP 世界里更合理的做法可能是暴露两个工具order_manage接受 action 参数区分 create/cancel/update_address和order_query按订单号或条件查询。这样模型只需要理解两个工具的语义而不是四个。当然聚合也有代价参数会变复杂Pydantic 模型需要处理条件必填。所以我的经验法则是如果两个接口的调用场景高度重叠、参数有 60% 以上重合就考虑合并否则保持独立。这个阈值不是拍脑袋是我在实际项目里试出来的——合并太多会导致参数校验逻辑爆炸合并太少又回到工具过多的问题。2.2 传输层选型stdio 还是 HTTPMCP 支持多种传输方式最常见的是 stdio标准输入输出和 HTTP包括 SSE 和 Streamable HTTP。这个选择直接决定了你的服务怎么部署、怎么被客户端发现。stdio 的优点是简单、无需网络配置、进程生命周期由客户端管理适合本地工具类场景比如你在 IDE 里让 AI 助手调用本地脚本。缺点是没法多客户端共享每个客户端都要自己拉起一个进程。HTTP 的优点是服务化、可多客户端复用、方便做鉴权和限流适合团队内部共享的服务。缺点是需要处理网络、认证、超时这些额外问题。我的建议是如果这个 MCP 服务是给团队多人用的直接上 HTTP如果只是个人本地辅助stdio 更省事。我自己的项目里对外共享的服务统一走 Streamable HTTP本地调试用 stdio 快速验证逻辑。2.3 工具描述怎么写才不让模型犯迷糊工具描述tool description是 MCP 里最容易被忽视、但影响最大的部分。模型能不能正确调用你的工具80% 取决于描述写得好不好。我见过太多人把 REST 的接口文档直接复制过来当描述结果模型根本不知道怎么用。REST 文档是写给人类看的里面有大量“参见 XX 章节”“需先调用 YY 接口”这种上下文依赖模型看不到这些上下文。好的工具描述应该包含三部分这个工具做什么一句话、什么时候该用触发场景、参数怎么填每个参数的业务含义不是类型。比如不要写“order_id: string”而要写“order_id: 订单编号格式为 ORD 开头的 16 位字符串可从 order_query 工具获取”。后者模型一看就知道该去哪里拿这个值。2.4 参数校验Pydantic 是你的第一道防线REST API 通常有自己的参数校验但 MCP 层必须再做一次原因有两个一是模型生成的参数不可信可能缺字段、类型错、超范围二是 MCP 层的校验失败可以返回结构化的错误信息给模型让模型自己纠正重试而不是直接抛 500。Pydantic 在这里几乎是标配。它能把参数定义、类型校验、默认值、描述一次性搞定而且 FastMCP 原生支持 Pydantic 模型作为工具参数。我后面会给出具体的模型定义方式包括条件必填、枚举约束、嵌套对象这些实际会用到的写法。3. 核心细节解析与实操要点3.1 环境准备与依赖选型先把依赖理清楚。核心是三个包fastmcpMCP 服务框架、pydantic参数模型、httpx异步 HTTP 客户端用来调你的 REST API。如果你用的是同步的 requests也可以但 MCP 服务本身是异步的混用同步客户端会阻塞事件循环所以强烈建议用 httpx 的异步模式。pip install fastmcp pydantic httpx版本上FastMCP 迭代很快建议锁一个近期稳定版本不要用 latest 裸奔。我当前用的是 fastmcp 2.x 系列pydantic 2.x。如果你还在 pydantic 1.x部分写法比如Field的某些参数会有差异建议先升级。注意FastMCP 和官方 MCP Python SDK 是两个东西。FastMCP 是更高层的封装写起来更简洁官方 SDK 更底层控制力更强。新手直接用 FastMCP遇到它不支持的场景再降级到官方 SDK。3.2 把 REST 接口映射成工具函数假设你有一个查询用户信息的 REST 接口GET /api/v1/users/{user_id}返回 JSON。封装成 MCP 工具的第一步是定义参数模型from pydantic import BaseModel, Field class GetUserInput(BaseModel): user_id: str Field( ..., description用户唯一标识格式为 U 开头的 12 位字符串例如 U123456789012 ) include_profile: bool Field( defaultFalse, description是否返回详细档案信息默认 false 只返回基础信息 )这里有几个细节值得说。Field(...)里的...表示必填这是 Pydantic 的写法。description一定要写清楚业务含义和格式这是给模型看的。include_profile这种可选参数给默认值模型不传也能正常工作。然后是工具函数本身from fastmcp import FastMCP import httpx mcp FastMCP(user-service) BASE_URL https://your-api.example.com mcp.tool() async def get_user(input: GetUserInput) - dict: 查询用户基础信息或详细档案。 当需要获取用户昵称、注册时间、账号状态时使用此工具。 如果需要用户的历史订单请改用 order_query 工具。 async with httpx.AsyncClient(timeout10.0) as client: resp await client.get( f{BASE_URL}/api/v1/users/{input.user_id}, params{include_profile: input.include_profile} ) resp.raise_for_status() return resp.json()注意 docstring 的写法。FastMCP 会把 docstring 作为工具描述传给模型所以这里不是写给人看的注释而是写给模型看的说明书。我特意加了一句“如果需要用户的历史订单请改用 order_query 工具”这是在帮模型做工具选择减少误调用。3.3 错误处理别让 REST 的错误码直接透传REST API 返回 404、403、500 的时候如果你直接把状态码和原始错误体抛给模型模型大概率不知道怎么处理。MCP 层的错误处理要做两件事把技术错误翻译成业务语义以及告诉模型下一步该怎么做。from fastmcp.exceptions import ToolError mcp.tool() async def get_user(input: GetUserInput) - dict: ... try: async with httpx.AsyncClient(timeout10.0) as client: resp await client.get(...) if resp.status_code 404: raise ToolError( f用户 {input.user_id} 不存在。 请确认 user_id 是否正确或先用 user_search 工具按昵称查找。 ) if resp.status_code 403: raise ToolError( 当前凭证无权访问该用户信息。 请检查是否使用了正确的 API Key或联系管理员开通权限。 ) resp.raise_for_status() return resp.json() except httpx.TimeoutException: raise ToolError(查询用户信息超时请稍后重试。如果持续超时可能是上游服务异常。)ToolError是 FastMCP 提供的异常类型抛出来后模型会收到结构化的错误信息并且可以基于错误信息决定是否重试或换工具。这比直接抛 HTTP 异常友好太多。实操心得错误信息里不要暴露内部实现细节比如数据库表名、内部服务地址。模型可能会把这些信息复述给用户造成信息泄露。错误信息要面向“业务操作”而不是“技术排查”。3.4 鉴权透传API Key 怎么安全地传给 REST 层你的 REST API 大概率需要鉴权。MCP 服务作为中间层鉴权信息怎么传是个关键问题。有三种常见做法第一种是服务端固定凭证MCP 服务启动时从环境变量读取 API Key所有请求都用这个 Key。适合内部服务、权限统一的场景。第二种是客户端透传MCP 客户端在调用工具时把用户的凭证传进来MCP 服务原样转发给 REST API。适合多租户、权限差异大的场景。第三种是令牌交换MCP 服务用自己的凭证去换取用户级令牌。适合有统一认证中心的场景。我自己的项目里内部工具用第一种对外服务用第二种。第二种的实现方式是在工具参数里加一个auth_token字段但这个字段不应该出现在工具描述里让模型去填——它应该由客户端在协议层注入。FastMCP 支持通过 context 获取请求元数据具体做法依赖你用的传输方式stdio 模式下通常从环境变量读HTTP 模式下从请求头读。from fastmcp import Context mcp.tool() async def get_user(input: GetUserInput, ctx: Context) - dict: ... api_key ctx.request_context.meta.get(api_key) if ctx.request_context else None if not api_key: raise ToolError(缺少 API Key无法调用用户服务。) headers {Authorization: fBearer {api_key}} # ... 后续请求带上 headers注意不要把 API Key 写进工具描述或参数默认值里那等于把密钥暴露给模型上下文。密钥只能通过协议层或环境变量传递。4. 完整实操流程与关键环节实现4.1 从零搭建一个可运行的 MCP 服务我把完整流程拆成六步每一步都有明确的产出物。第一步确定工具清单。列出你要暴露的 REST 接口然后按 2.1 节的聚合原则合并。产出物是一张表工具名、对应 REST 端点、参数、返回。第二步定义 Pydantic 模型。每个工具一个 Input 模型必要时定义 Output 模型。Output 模型不是必须的但定义了能让返回结构更稳定模型解析起来更准。第三步实现工具函数。每个函数做四件事校验参数Pydantic 自动做、构造 REST 请求、处理错误、裁剪返回。第四步配置传输层。stdio 模式直接mcp.run()HTTP 模式配置 host、port、路径。第五步本地验证。用 FastMCP 自带的测试客户端或 MCP Inspector 验证工具能被正确发现和调用。第六步接入真实客户端。把服务注册到你的 AI 客户端跑几个真实场景验证。4.2 参数映射的三种典型场景REST 参数和 MCP 参数不是一一对应的我遇到过的映射场景主要有三类。场景一路径参数 查询参数混合。REST 里GET /users/{id}?detailtrueMCP 里统一成一个 Input 模型函数内部拆开拼 URL。这个前面已经演示过。场景二POST body 嵌套结构。REST 的 body 可能是嵌套 JSONMCP 的 Input 模型也要用嵌套 Pydantic 模型对应class Address(BaseModel): province: str Field(..., description省份例如 广东省) city: str Field(..., description城市例如 深圳市) detail: str Field(..., description详细地址不超过 200 字) class CreateOrderInput(BaseModel): user_id: str Field(..., description下单用户 ID) items: list[str] Field(..., description商品 ID 列表至少一个) address: Address Field(..., description收货地址) remark: str Field(default, description订单备注可选)嵌套模型的好处是模型能理解结构层次不会把 address 拍平成一个字符串。场景三枚举值约束。REST 接口经常有状态字段取值有限。用 Pydantic 的Literal或Enum约束模型就不会传非法值from typing import Literal class UpdateOrderInput(BaseModel): order_id: str Field(..., description订单编号) action: Literal[cancel, confirm, modify_address] Field( ..., description操作类型cancel 取消订单confirm 确认收货modify_address 修改地址 )用Literal而不是str模型在生成参数时会受到约束非法值的概率大幅降低。4.3 返回结果裁剪别把整个 JSON 塞回去REST API 返回的 JSON 往往包含大量模型不需要的字段比如内部 ID、创建时间戳、审计信息。这些字段塞进模型上下文既浪费 token又可能干扰模型判断。我的做法是在 MCP 层做一次字段裁剪只保留业务相关的字段。比如用户接口返回 30 个字段MCP 层只返回 8 个RAW_FIELDS [user_id, nickname, status, register_time, profile] mcp.tool() async def get_user(input: GetUserInput) - dict: ... raw await _call_rest(...) return {k: raw.get(k) for k in RAW_FIELDS if k in raw}如果返回是列表还要考虑分页。REST 可能一次返回 100 条MCP 层应该默认只返回前 10 条并在描述里说明“如需更多请用 offset 参数”。这是防止上下文爆炸的关键。4.4 流式输出长任务怎么让模型边收边处理有些 REST 接口是流式的比如导出报表、生成内容。MCP 支持流式返回FastMCP 里可以用yield逐步返回内容。这个能力在“使用 mcp 工具流式输出内容到文件”这类场景里特别有用。mcp.tool() async def export_report(input: ExportInput): 导出报表流式返回内容块。 async with httpx.AsyncClient(timeout60.0) as client: async with client.stream(GET, f{BASE_URL}/reports/{input.report_id}) as resp: async for chunk in resp.aiter_text(): yield chunk客户端收到的是逐步到达的内容块可以边收边写文件或边展示。注意流式工具的返回类型和普通工具不同具体写法要参考你用的 FastMCP 版本不同版本 API 有差异。4.5 本地验证与调试写完服务别急着接客户端先用 MCP Inspector 或 FastMCP 的测试客户端跑一遍。我通常验证四件事工具列表能不能正确列出、每个工具的参数 schema 对不对、正常调用能不能返回、错误场景能不能返回可读的错误信息。# 快速验证脚本 import asyncio from fastmcp import Client async def main(): async with Client(user_service.py) as client: tools await client.list_tools() for t in tools: print(t.name, t.description[:50]) result await client.call_tool(get_user, {input: {user_id: U123456789012}}) print(result) asyncio.run(main())这个脚本能跑通基本就没大问题了。跑不通的话八成是参数模型定义和调用方式不匹配仔细看报错信息。5. 常见问题与排查技巧实录5.1 模型不调用我的工具怎么办这是最高频的问题。模型不调用工具通常有三个原因。第一是工具描述太模糊。如果描述写的是“获取用户信息”模型不知道什么时候该用。改成“当用户询问账号状态、昵称、注册时间时使用”触发场景明确了调用率会明显上升。第二是工具太多模型选择困难。前面说过工具数量控制在 10 个以内比较稳妥。超过的话考虑合并或分组。第三是参数描述缺失。模型不知道某个参数该填什么就会放弃调用。每个参数的 description 都要写清楚格式和来源。5.2 参数校验总是失败模型生成的参数不符合 Pydantic 模型常见原因和对策我整理成了一张表现象常见原因对策必填字段缺失描述里没强调必填在 description 里加“必填”字样类型错误字符串传成数字模型对类型理解偏差用更严格的类型或在描述里给示例枚举值非法没用 Literal 约束改用 Literal 或 Enum嵌套对象结构错嵌套模型描述不清给嵌套模型每个字段都写描述日期格式错没指定格式描述里写明“格式 YYYY-MM-DD”实操心得Pydantic 的校验错误信息默认比较技术化模型不一定看得懂。可以在工具函数里捕获ValidationError转成更口语化的提示再抛ToolError。5.3 调用超时或卡死MCP 服务调 REST API 超时排查顺序是先看 REST API 本身是否正常用 curl 直接测再看 MCP 服务的超时设置是否合理最后看是不是同步阻塞了事件循环。最常见的坑是用了同步的requests库。MCP 服务是异步的同步调用会阻塞整个事件循环导致其他请求全部卡住。一定要用httpx.AsyncClient或aiohttp。5.4 鉴权信息丢失HTTP 传输模式下鉴权信息通常放在请求头里。如果 MCP 服务读不到检查两点一是客户端有没有正确配置请求头二是 MCP 服务的传输层有没有把请求头透传到 context。stdio 模式下没有请求头概念鉴权信息只能从环境变量或启动参数读。5.5 返回内容太大导致上下文溢出这个问题的根源是没做返回裁剪。对策有三层第一层是字段裁剪只返回必要字段第二层是条数限制列表默认返回前 N 条第三层是分页提供 offset 和 limit 参数让模型自己控制。三层做完基本不会溢出。6. 工具选型与扩展思路6.1 FastMCP vs 官方 SDK vs 自研FastMCP 适合快速落地API 简洁Pydantic 集成好大部分场景够用。官方 SDK 适合需要精细控制协议细节的场景比如自定义传输、自定义能力协商。自研只建议在你有非常特殊的需求时考虑比如要嵌入到已有框架里否则维护成本太高。我的选择是新项目一律 FastMCP 起步遇到它解决不了的问题再降级到官方 SDK。这样前期开发效率最高后期也有退路。6.2 和现有 API 网关的关系MCP 服务不应该替代 API 网关而应该和网关配合。网关负责限流、鉴权、路由MCP 服务负责协议转换和工具描述。我通常把 MCP 服务部署在网关后面MCP 服务调网关网关再调后端服务。这样网关的策略对 MCP 调用同样生效不用重复实现。6.3 后续可以扩展的方向服务跑起来之后有几个方向可以继续做。一是加缓存对读多写少的接口在 MCP 层加一层缓存减少 REST 调用。二是加审计记录每次工具调用的参数和结果方便排查问题。三是加工具分组工具多了之后按业务域拆成多个 MCP 服务客户端按需加载。四是加健康检查MCP 服务启动时探测 REST API 是否可用不可用就快速失败而不是让模型等超时。我个人在实际操作中的体会是MCP 封装这件事技术难度不高难的是“站在模型的角度想问题”。你写的每一个描述、每一个参数、每一条错误信息都是模型理解你服务的唯一途径。把模型当成一个聪明但对你系统一无所知的新同事把该交代的都交代清楚封装出来的服务就好用。反过来如果只是把 REST 文档机械翻译一遍模型用起来就会磕磕绊绊最后你还是得手动兜底。