GPT Image 2.5 is live — OpenAI's newest image model, targeted edits that leave the rest of the frame alone
全部教程与指南

· reAPI Team

MCP 工具调用:切换 API 后为何失效

追踪 MCP 工具调用经过发现、模型支持、执行和结果返回的全过程。在重试或提交付费任务前,诊断 API 迁移故障。

MCP 工具调用:切换 API 后为何失效

MCP 服务器显示“已连接”。助手仍然只用普通文本回答,或者声称检查了某项任务,却没有显示任何结果。如果这种情况是在更换模型 API 后开始的,请先检查新连接中实际传递了什么,再去修改提示词。

已连接的工具服务器与能够请求工具的模型,是应用中的两个不同部分。MCP 定义工具发现和调用。随后,宿主必须向模型提供相应工具,执行模型请求的任何获准调用,并将结果发回。[1][2] 第一步成功,并不能证明最后一步也成功。

在客户端收到的列表中查找工具

先检查一个工具。读取受影响客户端实际收到的 tools/list 结果;如适用,也要包括后续分页。保留它的名称、描述和输入架构。连接状态标记并不能说明这个特定工具是否已被发现。

如果工具缺失,请检查运行客户端的进程所选服务器、支持的传输方式和身份验证。当前 MCP 规范允许可用工具随提供的授权信息而变化。[1] 因此,能看到一个工具,并不能证明同一调用方能看到该服务器提供的所有工具。

对于 reAPI 连接,文档说明的服务器使用远程 Streamable HTTP,并要求自定义 Bearer 授权标头。只提供 OAuth 登录、但不支持自定义标头的客户端,无法通过这种配置连接。[3] 重复修改模型指令,无法补上客户端不具备的传输方式或凭据机制。

在排查时,要区分模型提供商凭据和工具服务器凭据。它们可能属于不同连接。更换模型 API 密钥无法修复 MCP 连接中缺失的凭据;更换 MCP 凭据也不会让工具自动出现在发往模型的请求中。记录安全的配置标识符,不要记录密钥。

比较发现的架构与模型实际看到的内容

以下面的虚构只读工具为例。它会按 ID 查询现有任务。这个片段仅用于说明发现结果,并非完整协议响应,也不是我们部署的工具:

{
  "name": "inspect_task_example",
  "description": "Look up the status of an existing task.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "task_id": { "type": "string" }
    },
    "required": ["task_id"]
  }
}

现在检查发送给模型的序列化请求。模型使用的工具格式可能不同于 MCP 的 inputSchema 格式,但名称、属性和必填字段的含义必须在转换后保留下来。如果宿主发送了工具名称,却没有 task_id 属性或必填字段列表,那么模型收到的契约就已经不同。

这就是适配器中一个明确的修复点。再写一段更长的提示词,让模型“正确使用工具”,并不能恢复缺失的架构。继续添加指令或再次更换提供商之前,先比较这两个对象。

在本例中,比较 task_id 的三个位置:发现结果中的属性、面向模型的属性,以及宿主随后分发的参数。三处都必须仍指向同一个必填字符串值。如果转换器在一处把它改名为 id,另一处却保留 task_id,就造成了不匹配。使用模型 API 支持的定义包装格式,同时保留该字段的名称、类型和必填状态。

还要检查过时的定义。服务器上的工具改名后,缓存的客户端列表可能仍显示旧名称。保存失败请求实际使用的定义,确保比较的是模型真正收到的内容,而不是另一份文档页面上最新的架构。

模型请求了工具,还是只描述了要使用工具?

读取模型响应的结构。普通文字说“我会检查这项任务”,并不是结构化工具调用。拒绝响应、普通答案、格式错误的调用和有效调用需要采取不同的下一步,即使它们都来自成功的 HTTP 响应。

如果请求包含正确的架构,但没有返回调用,请检查模型支持情况、工具选择设置和所用路由。自动工具选择可能返回普通答案;禁用工具的设置可能会阻止选择。不同模型对更严格的工具选择值的支持也各不相同。[2] 不要把每次未返回调用都当作参数格式错误。

当中间层选择提供商时,路由也很重要。OpenRouter 说明,require_parameters 可用于限制路由,使其只选支持所有请求参数的提供商。其默认参数偏好(包括对工具的偏好)并不等同于严格筛选。[4] 检查备用模型和实际处理请求的路由。不要把这个特定于提供商的选项复制到其他 API,并假设行为相同。

如果确实收到了结构化调用,请停止排查选择过程,转而跟进该调用。模型已经请求执行操作;应用仍需实际运行它。OpenRouter 的工具调用教程明确指出,执行责任在调用方,而不在模型。[2]

在执行和返回过程中跟踪同一个调用 ID

下面是虚构示例的下一部分,采用 Chat Completions 消息格式。ID 和结果都是编造的。这些是供检查的消息片段,并非发送请求的脚本:

[
  {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      {
        "id": "call_example_1",
        "type": "function",
        "function": {
          "name": "inspect_task_example",
          "arguments": "{\"task_id\":\"example_task_7\"}"
        }
      }
    ]
  },
  {
    "role": "tool",
    "tool_call_id": "call_example_1",
    "content": "{\"task_id\":\"example_task_7\",\"status\":\"processing\"}"
  }
]

在这两条消息之间,宿主必须把获准的调用分发给工具并收到结果。模型响应中包含 call_example_1,并不能证明分发已经发生。查找对应的执行记录和服务器结果。

如果执行正在等待批准,请保留这一状态。如果用户拒绝了,结果就是该操作被拒绝;改用另一个工具或重试,并不代表获准绕过这个决定。如果用户已批准但始终没有分发,请调查宿主的执行逻辑。

还要将分发的工具名称和参数与请求的调用进行核对。在本例中,查询必须收到 example_task_7;如果宿主意外重复使用了前一个任务 ID,即便服务器返回有效结果,执行的也是另一项查询。保存模型调用 ID 与工具调用及返回内容之间的映射。这样,在模型把结果纳入肯定答复之前,就能看出任务是否错误。修正这个本地映射,不要更改源工具的架构,也不要扩大其访问权限。

对于流式调用,要等到参数完整。OpenRouter 建议按调用索引收集增量片段,并在参数字符串完整后再解析。[2] 如果早期片段在 task_id 中途就结束,那还不是有效 JSON。应将这种情况与完整但仍无效的参数字符串区分开。

上面的第二条消息携带与第一条相同的调用 ID。在文档描述的 Chat Completions 循环中,助手的工具调用轮次之后,每个请求调用都会跟随一条结果消息。[2] 如果返回了多个调用,要保留每个调用的身份及其结果。把同一条结果放到每个 ID 之下,可能让对话看似完整,却把错误数据附到了请求的操作上。

假设工具确实返回了 processing,但下一次模型请求省略了工具消息。执行成功了;模型却没有收到结果。或者,假设宿主在转换时把结果替换为空字符串。更换模型也无法补回对话中同样缺失的信息。

将实际服务器结果与发出的后续请求进行比较。保留相关内容和错误,而不只是客户端日志中的成功标记。应根据模型收到的结果来评估其最终措辞;它声称检查了任务,不能替代这条记录。

保留工具错误信息

MCP 将协议问题与工具执行失败区分开来。未知工具或格式错误的协议请求可能产生 JSON-RPC 错误。工具执行失败则可能以 isError: true 返回。[1] 将结果转换给模型时,要保留这种区别和相关消息。

对于示例查询,如果错误信息表明无法访问该任务,就不能把它变成空的成功状态。如果模型只收到空字符串,它就失去了说明失败或选择恰当下一步所需的信息。先检查转换过程,再判断最终答案是否有问题。

一个有用的本地检查方法,是将保存的或合成的消息送入适配器:一条普通结果、一条执行错误,以及两个 ID 不同的调用。确认内容、错误含义和身份都能保留下来。这只能测试适配器处理这些测试数据的方式;不能证明远程模型会正确选择工具。即使选择的工具是只读的,实时模型评估仍可能产生推理费用。

让两条合成结果明显不同,然后按与请求相反的顺序返回。宿主应按调用身份关联它们,而不是按到达顺序关联。测试结果完全相同,可能掩盖这个错误,因为交换结果后,下一次模型输入看起来并没有变化。

提交生成任务前完成连接检查

对于 reAPI,先使用与问题相关、不会提交任务的工具。MCP 参考文档列出的模型发现、架构检索、估价、任务状态和余额操作都不会扣除积分。submit_task 则不同:创建任务的调用会按该任务计费。[3]

文档中的服务器是无状态的,每个 HTTP 请求只接受一条 JSON-RPC 消息,不接受批量数组。媒体输入必须使用公开的 HTTP 或 HTTPS URL,不能使用 base64 或 data URI。[3] 执行步骤失败时,检查这些实际接口要求;不要反复提交生成任务来测试连接。

保留返回的任务 ID,并查询该现有任务。reAPI 文档说明任务提交不是幂等操作:重复创建请求可能会产生另一个计费任务。[3] 如果提交响应丢失,应进行接收状态检查,不要假设请求没有生效。

对于这个虚构查询,当你能指出消息从哪里开始出现差异时,迁移比较就完成了:工具发现、面向模型的定义、结构化调用、执行过程或返回结果。修复这一处具体差异,然后重复同一个无害检查。将服务器、模型、客户端版本和记录的调用放在一起,方便下一个人查看已验证的内容,而不必依赖“已连接”标记。

参考资料

  1. 模型上下文协议(Model Context Protocol),工具规范,2026-07-28 修订版。阅读日期:2026 年 11 月 16 日。协议版本和服务器实现可能有所不同。
  2. OpenRouter,《跨任意模型调用工具:循环只写一次,替换模型字符串》,官方教程,更新于 2026 年 9 月 24 日。阅读日期:2026 年 11 月 16 日。
  3. reAPI,MCP 服务器文档。审阅日期:2026 年 11 月 16 日。本指南未进行实时生成或客户端兼容性测试。
  4. OpenRouter,《提供商路由》,官方文档中的“要求提供商支持所有参数”和“默认参数偏好”章节。阅读日期:2026 年 11 月 16 日。
全部教程与指南