1. 从一次工具调用失败说起MCP到底在解决什么问题我第一次认真研究MCP不是因为读到了什么架构文档而是因为一个很具体的报错llm request failed: provider rejected the request schema or tool payload。当时我正把一个内部工具通过MCP协议暴露给大模型本地测试一切正常换到另一个客户端就挂了。排查了半天才发现问题出在入参约束的schema定义上——我用了某个客户端不支持的JSON Schema关键字导致工具描述在传输过程中被拒绝。这个经历让我意识到MCP看起来只是让模型调用工具这么简单一件事但真正吃透它需要理解三个层面的东西工具是怎么被暴露出去的、入参是怎么被约束的、LLM在底层到底是怎么发起调用的。这三件事环环相扣任何一环理解不到位都会在实际集成中踩坑。MCP全称Model Context Protocol是一个开放协议用来标准化大语言模型与外部工具、数据源之间的交互方式。你可以把它理解成AI世界的USB接口——以前每个模型厂商、每个客户端都有自己的工具调用格式你为A平台写的工具换到B平台就得重写一遍。MCP做的事情就是定义一套统一的描述语言和通信规范让工具提供方和工具消费方解耦。这篇文章适合几类人看正在做AI Agent工具集成的工程师、想把内部系统接入大模型的开发者、以及那些被codex无法找到mcp、codex接入figma mcp怎么授权这类问题卡住的人。我不会只讲概念而是会把工具暴露的完整链路、入参约束的设计细节、LLM调用的底层逻辑拆开来讲配上我实际踩过的坑和可复现的操作步骤。读完你应该能自己判断为什么你的工具模型看不见为什么参数总是传错以及怎么设计一套稳定的工具描述。2. 工具暴露的完整链路从list_tools到模型可见2.1 list_tools不是列个清单那么简单很多人以为工具暴露就是服务端提供一个list_tools接口返回一个工具数组客户端拿到之后转给模型就完事了。实际链路要复杂得多中间至少经过四次转换。第一次转换发生在MCP Server内部。你注册的工具通常是一个函数带有函数名、参数、返回值类型。Server需要把这些信息序列化成MCP协议规定的工具描述格式核心字段包括name、description、inputSchema。这里的inputSchema是一个JSON Schema对象描述了这个工具接受什么参数。第二次转换发生在MCP Client。Client通过list_tools拿到工具列表后不能直接丢给模型因为不同模型厂商对工具描述的格式要求不一样。OpenAI有一套function calling格式Anthropic有自己的一套国内模型又各有差异。Client需要把MCP的标准格式转换成目标模型能理解的格式。第三次转换是模型侧的理解。模型拿到工具描述后会把它编码进上下文在生成回复时判断是否需要调用工具、调用哪个工具、传什么参数。这一步是黑盒但你可以通过工具描述的质量来影响模型的判断准确率。第四次转换是调用回传。模型输出一个工具调用请求Client解析后转成MCP格式发给ServerServer执行完把结果返回再一路转回模型。我见过太多人卡在第二次转换上。比如codex无法找到mcp这个问题十有八九不是工具没注册成功而是Client在转换工具描述时因为某个字段格式不兼容把整个工具列表丢弃了。排查方法很简单在Client侧打印转换前后的工具描述对比看哪个字段丢了或者格式变了。2.2 工具描述里的description为什么比你想的重要description字段看起来只是给人看的说明文字但对模型来说这是它判断什么时候该用这个工具的唯一依据。我做过一个对比测试同一个工具description写查询用户信息和写根据用户ID查询用户的姓名、邮箱、注册时间、会员等级当用户询问账户相关问题时使用模型调用准确率差了将近40%。写description有几个实操原则。第一要写清楚什么时候用而不只是这个工具做什么。模型需要的是触发条件不是功能说明书。第二把关键参数的含义也写进去因为模型在决定传参时也会参考description。第三避免歧义如果你的系统里有多个相似工具description必须能明确区分它们。还有一个容易被忽略的点description的长度。太短模型理解不了太长会占用上下文且可能被截断。我的经验是控制在100到300个字符之间把最关键的触发条件和功能边界说清楚就够了。2.3 工具命名里的隐藏陷阱工具名不是随便起的。模型在生成工具调用时需要精确匹配工具名任何字符差异都会导致调用失败。我踩过的坑包括用了中文名导致某些客户端编码出错、用了带空格的名字被截断、用了和内置工具重名的名字导致冲突。命名规范我总结了几条全小写字母加下划线、动词开头、避免缩写、长度控制在3到5个单词。比如get_user_profile就比getUserProfile和gup都好前者是因为跨平台兼容性后者是因为可读性。另外要注意命名空间的问题。如果你有多个MCP Server工具名可能会冲突。有些Client支持给工具加前缀来区分来源有些不支持。在设计阶段就要考虑好别等到集成时才发现两个Server都有search工具。3. 入参约束JSON Schema写不好模型就传不对参3.1 inputSchema的每个字段都在影响模型行为inputSchema是一个标准的JSON Schema但MCP场景下它的作用不只是校验更重要的是引导模型正确传参。模型会读取这个schema来理解每个参数的类型、含义和约束然后生成符合要求的参数值。一个典型的inputSchema长这样{ type: object, properties: { user_id: { type: string, description: 用户的唯一标识通常是UUID格式 }, include_orders: { type: boolean, description: 是否包含订单信息默认为false, default: false } }, required: [user_id] }这里每个字段都有讲究。type决定了模型生成参数时的格式如果写string但模型传了个数字某些Client会直接拒绝。description是给模型看的参数说明写清楚格式要求能大幅降低传参错误率。required标记必填参数模型会优先保证这些参数被填充。default给可选参数提供默认值减少模型需要决策的字段数量。3.2 那些让Client拒绝请求的schema写法回到开头那个provider rejected the request schema or tool payload报错。我后来定位到问题出在我用了oneOf关键字。MCP协议本身支持完整的JSON Schema但很多Client在转换时只实现了子集遇到不支持的关键字就直接拒绝整个请求。我整理了一份高风险schema关键字清单这些在实际集成中容易出问题关键字风险等级常见问题替代方案oneOf高多数Client不支持拆成多个工具或用enumanyOf高同上同上allOf中部分Client解析异常直接展开字段$ref高跨文件引用基本不支持内联展开patternProperties中支持度参差不齐用additionalPropertiesif/then/else高几乎都不支持在description里说明我的建议是除非你确定目标Client支持否则只用最基础的type、properties、required、enum、default、description这几个关键字。复杂约束通过description文字说明让模型自己遵守而不是靠schema强制。3.3 参数类型设计的实战经验类型设计有几个反直觉的点。第一能用string就别用number。模型生成数字时容易出各种问题比如精度丢失、格式错误。如果参数本质是ID或者编码用string更稳。第二布尔值要谨慎。模型对布尔值的理解有时会偏差把false当成字符串传。如果布尔参数很关键考虑用enum的yes/no代替。第三数组参数要明确元素类型和数量限制否则模型可能传一个空数组或者超长数组。还有一个技巧把复杂对象拆成扁平参数。比如你要传一个地址不要设计成{address: {city: ..., street: ...}}而是拆成city和street两个顶层参数。扁平结构模型理解起来更准出错率更低。3.4 参数校验失败时的错误信息设计当模型传的参数不符合schema时Server会返回错误。这个错误信息会回传给模型模型有机会根据错误重新生成参数。所以错误信息的设计直接影响重试成功率。差的错误信息Invalid parameters。模型看到这个完全不知道哪里错了只能瞎猜。好的错误信息参数user_id格式错误期望UUID格式如550e8400-e29b-41d4-a716-446655440000实际收到12345。模型看到这个能明确知道要改成什么格式。我在Server侧做了一个错误信息模板把字段名、期望格式、实际值、示例都带上。实测下来模型一次重试成功率从不到30%提升到了70%以上。4. LLM调用工具的底层逻辑模型到底在做什么4.1 工具调用不是模型执行而是模型生成这是最容易被误解的一点。模型本身不执行任何工具它只是生成一段结构化的文本表达我要调用某个工具参数是这些。真正执行工具的是Client或Server。理解这一点很重要因为它决定了你能做什么优化。模型生成工具调用请求的过程本质上是一个文本生成任务。它根据上下文里的工具描述、用户输入、历史对话生成一个符合格式的调用请求。所以所有影响文本生成的因素——上下文长度、描述质量、格式清晰度——都会影响工具调用的准确性。这也解释了为什么有时候模型会幻觉出一个不存在的工具。因为它在做文本生成如果工具描述不够清晰它可能生成一个看起来合理但实际不存在的工具名。4.2 模型如何决定调不调和调哪个模型的决策过程可以粗略分成两步。第一步是意图判断当前用户输入是否需要工具介入。这一步模型主要看工具description里的触发条件描述。第二步是工具选择如果需要选哪个工具。这一步模型会比较各个工具的描述和当前需求的匹配度。影响这两步的关键因素有几个。工具数量是第一位的我实测发现工具超过20个之后模型选择准确率开始明显下降。这时候需要做工具分组或者动态加载只把当前场景相关的工具暴露给模型。工具描述的区分度是第二位的。如果两个工具描述很像模型很容易选错。解决办法是在description里明确写出什么时候用A什么时候用B。历史对话的干扰是第三位的。如果之前的对话里调用过某个工具模型有惯性继续调用它。这在多轮对话里要特别注意必要时在系统提示里明确当前场景。4.3 流式输出与工具调用的配合现在很多场景要求流式输出比如使用mcp工具流式输出内容到文件。流式输出和工具调用配合时有个坑模型可能在流式生成过程中突然插入工具调用请求这时候已经输出的内容怎么处理标准做法是工具调用请求作为一个特殊的事件插入流中Client收到后暂停内容展示执行工具拿到结果后把结果注入上下文继续生成。但不同Client对这个流程的实现不一样有些会丢弃工具调用前的内容有些会保留。我的建议是如果你的工具调用结果会影响后续内容生成那在工具调用前的内容应该被视为草稿等工具结果回来后再统一输出。如果工具调用是独立的那可以正常流式输出。4.4 多轮工具调用的上下文管理复杂任务往往需要多次工具调用。比如先查用户ID再根据ID查订单再根据订单查物流。每一轮工具调用的结果都要注入上下文供下一轮决策使用。这里的问题是上下文会快速膨胀。每次工具调用的请求和结果都占用token几轮下来可能就超限了。我的做法是对工具结果做摘要只保留关键信息注入上下文完整结果存在外部需要时再取。另外已经完成的工具调用链可以压缩成一句话总结比如已查询用户123的订单共3笔而不是保留完整的请求和响应。5. 从零搭建一个MCP工具的实操记录5.1 环境准备与最小可运行示例我用Python搭一个最小示例展示完整的工具暴露流程。需要安装MCP的Python SDKpip install mcp然后写一个最简单的Serverfrom mcp.server import Server from mcp.types import Tool, TextContent app Server(demo-server) app.list_tools() async def list_tools(): return [ Tool( nameget_weather, description查询指定城市的当前天气。当用户询问天气相关问题时使用。, inputSchema{ type: object, properties: { city: { type: string, description: 城市名称如北京、上海 } }, required: [city] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name get_weather: city arguments[city] return [TextContent(typetext, textf{city}今天晴25度)]这个示例虽然简单但包含了工具暴露的核心要素工具名、描述、入参schema、调用处理。你可以先跑通这个再逐步加复杂度。5.2 工具注册时最容易忽略的三个细节第一个细节是异步。MCP的工具处理函数必须是异步的如果你用了同步的数据库查询或者HTTP请求要包一层异步。我见过有人直接在里面调同步的requests结果整个Server阻塞。第二个细节是错误处理。工具执行失败时不要直接抛异常而是返回一个包含错误信息的TextContent。这样模型能看到错误并决定是否重试。直接抛异常会导致整个调用链断掉。第三个细节是返回值格式。MCP支持多种内容类型最常用的是TextContent。如果你的工具返回结构化数据可以序列化成JSON字符串放在TextContent里并在description里说明返回格式方便模型解析。5.3 用真实Client验证工具可见性Server写好后别急着接大模型先用MCP Inspector或者简单的Client脚本验证工具能不能被正确列出。这一步能排除掉大部分schema问题。验证清单list_tools返回的工具数量对不对、每个工具的name和description是否完整、inputSchema是否是合法JSON、必填字段是否标记正确。我习惯把返回的schema打印出来肉眼过一遍确认没有多余或缺失的字段。确认无误后再接入真实Client。接入后第一件事是看Client侧的工具列表确认工具被正确转换。如果Client侧看不到工具回到上一步检查转换日志。5.4 接入LLM后的联调技巧接入LLM后联调的核心是看模型生成的工具调用请求是否符合预期。我通常会在Client侧加日志记录每次模型输出的工具调用请求包括工具名和参数。如果模型不调用工具先检查description是否说清了触发条件。如果调用了但参数不对检查inputSchema的description是否足够明确。如果调用了不存在的工具检查工具名是否有歧义。联调时建议从简单场景开始一次只测一个工具确认没问题再加下一个。一次性暴露所有工具出问题时很难定位是哪个工具的描述有问题。6. 那些年我踩过的MCP集成坑6.1 授权与鉴权codex接入figma mcp的授权问题codex接入figma mcp怎么授权这类问题很典型。MCP协议本身不规定鉴权方式各家实现不一样。有的用API Key有的用OAuth有的用环境变量。我的经验是先看Server文档要求的鉴权方式然后在Client侧找到对应的配置入口。如果Client不支持某种鉴权方式可能需要写一个中间层做转换。授权失败时先确认凭证是否过期再确认Client是否把凭证正确传递给了Server。6.2 工具找不到从codex无法找到mcp说起codex无法找到mcp这个问题我遇到过三次原因各不相同。第一次是Server没启动Client连不上。第二次是工具描述里有Client不支持的schema关键字整个列表被丢弃。第三次是工具名冲突Client去重时把工具过滤掉了。排查顺序先确认Server在运行且端口可达再检查Client日志里有没有schema解析错误最后检查工具名是否有重复或冲突。6.3 请求被拒provider rejected the request schema这个报错我在开头提过根因是schema不兼容。解决办法是简化schema只用最基础的关键字。如果必须用复杂约束在description里用文字说明让模型遵守而不是靠schema强制。还有一个隐藏原因是payload过大。如果工具描述太长或者参数太多某些provider会拒绝。这时候需要精简描述或者把大工具拆成多个小工具。6.4 流式输出中断工具调用与流式的冲突流式输出时插入工具调用有些Client处理不好会导致输出中断。我的解决办法是在工具调用前加一个明确的标记Client收到标记后暂停流式等工具结果回来再继续。另外工具调用的结果要尽快返回避免长时间挂起导致连接超时。7. 设计一套稳定工具集的几条原则7.1 工具粒度粗一点还是细一点工具粒度是个权衡。粒度太细工具数量爆炸模型选择困难。粒度太粗一个工具承担太多职责参数复杂模型传参容易出错。我的经验是一个工具只做一件事但这件事的边界要清晰。比如查询用户和查询订单是两个工具但查询用户的基本信息和查询用户的会员信息可以合并成一个查询用户信息通过参数控制返回哪些字段。判断标准是如果两个工具的参数高度重叠且经常被一起调用考虑合并。如果两个工具的参数完全不同且调用场景独立保持分开。7.2 参数设计让模型少做决策每多一个参数模型就多一次决策出错概率就增加。所以参数设计的原则是能不给模型决策的就不给。具体做法能设默认值的设默认值能通过上下文推断的不要作为参数能用枚举的不要用自由文本。比如查询时间范围不要设计成两个日期参数让模型填而是设计成time_range枚举值为today、last_week、last_month模型选一个就行。7.3 错误恢复让模型能自己纠正工具执行失败时返回的错误信息要能让模型理解并纠正。我前面提过错误信息模板这里再强调一点错误信息里要包含怎么改的提示而不只是哪里错了。比如参数格式错误错误信息里带上正确格式的示例。参数值超出范围错误信息里带上有效范围。这样模型能直接根据错误信息重新生成参数不需要额外推理。7.4 版本管理工具变更时怎么不破坏现有集成工具一旦暴露给模型就相当于有了外部依赖。你改工具名、改参数、改描述都可能影响现有集成。所以工具变更要像API变更一样谨慎。我的做法是工具名一旦确定不改参数只增不减description可以优化但不能改变语义。如果必须做破坏性变更新增一个工具旧工具标记为deprecated但保留一段时间给使用方迁移的时间。8. 关于MCP工具设计我个人的几条经验工具描述是给模型看的不是给人看的。写description的时候想象你在跟一个很聪明但完全不了解你系统的助手说话你需要把触发条件、功能边界、参数含义都说清楚它才能正确使用。schema能简单就简单。我见过太多人把JSON Schema写得极其复杂结果各种Client不兼容。基础关键字够用了复杂约束用文字说明。测试要从Client侧看结果。Server侧测试通过不代表Client侧没问题中间有转换环节。每次改完工具都要在真实Client里验证一遍。工具数量要控制。超过20个工具模型选择准确率会下降。如果业务需要很多工具考虑按场景分组动态加载。错误信息要设计。这是最容易被忽略但影响很大的一环。好的错误信息能让模型自己纠正差的错误信息只能靠人工介入。最后说一个我最近在想的点MCP工具的设计本质上是在设计模型和系统之间的接口。这个接口的质量直接决定了AI Agent能不能稳定工作。花时间打磨工具描述和参数设计比花时间调模型参数更有效。