2026 MCP 工具 Schema 转换指南：Claude、OpenAI 与 Gemini Function Calling 如何互转

约 5 分钟阅读MCPAI AgentFunction CallingJSON Schema工具调用

作者：PocketKit 编辑团队

对比 MCP inputSchema、Claude input_schema、OpenAI tools[].function.parameters 与 Gemini functionDeclarations，通过完整示例解决 strict、required、additionalProperties 和类型大小写等迁移问题。

AI Agent 真正开始干活时，需要的不只是一段提示词，还要知道可以调用哪些工具、每个参数是什么类型、哪些字段必填。MCP（Model Context Protocol）让工具更容易被发现和复用，但它并没有让 Claude、OpenAI 和 Gemini 的 API 请求格式自动变成一样。

一个在 Claude 中正常的 input_schema，复制到 OpenAI 后可能缺少 function 包装；OpenAI 的 Strict Mode 工具改成 Gemini 时，additionalProperties 又可能需要删除。这篇文章不讨论抽象的“Agent 未来”，只解决一个具体问题：如何把同一个工具定义稳定地迁移到 MCP、Claude、OpenAI 和 Gemini。

TL;DR：MCP、Claude、OpenAI 和 Gemini 都使用 JSON Schema 描述工具参数，但外层包装、字段名和支持的 Schema 子集不完全相同。MCP 常用 inputSchema，Claude 使用 input_schema，OpenAI 使用 tools[].function.parameters，Gemini 放在 functionDeclarations[].parameters。先规范化为标准 JSON Schema，再生成各家包装，是最稳定的迁移方法。

四种工具定义有什么不同？

目标 参数 Schema 位置 常见注意点
MCP tools/list 结果中的 inputSchema 工具还包含 name 和 description
Claude tools[].input_schema 字段名是 snake_case
OpenAI tools[].function.parameters Strict Mode 对 required 和 additionalProperties 更严格
Gemini functionDeclarations[].parameters 支持 JSON Schema/OpenAPI 的特定子集，需按当前 SDK 文档复核

最容易犯的错误，是只改了 input_schema 或 parameters 的字段名，却没有改外层结构。模型看到的参数规则可能一样，API 看到的请求对象却完全不同。

用一个天气工具看懂格式映射

先把参数收敛为一份中立 JSON Schema：

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "City name, for example Shanghai"
    },
    "unit": {
      "type": "string",
      "enum": ["celsius", "fahrenheit"]
    }
  },
  "required": ["city"]
}

MCP 工具

{
  "name": "get_weather",
  "description": "Get the current weather for a city",
  "inputSchema": {
    "type": "object",
    "properties": {
      "city": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["city"]
  }
}

Claude Tool Use

{
  "name": "get_weather",
  "description": "Get the current weather for a city",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["city"]
  }
}

OpenAI Function Calling

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get the current weather for a city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" },
        "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
      },
      "required": ["city"]
    }
  }
}

Gemini Function Calling

{
  "name": "get_weather",
  "description": "Get the current weather for a city",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "city": { "type": "STRING" },
      "unit": { "type": "STRING", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["city"]
  }
}

不同 Gemini SDK 版本可能接受枚举值或小写 JSON Schema 类型。不要凭记忆硬改，应以项目当前使用的 SDK 和官方文档为准。

最常见的 6 类 Schema 报错

1. 只复制参数体，丢了平台外层包装

OpenAI 需要 type: "function" 和 function 对象，Claude 工具则直接使用 name、description 和 input_schema。请不要把整个 Claude 工具对象直接塞进 OpenAI 的 parameters。

2. Strict Mode 下遗漏 additionalProperties: false

Strict 工具的目的是让模型输出严格匹配 Schema。对象层级通常需要禁止未声明的字段，而且嵌套对象也要递归检查。

3. required 与 properties 不一致

required 中的名称必须在 properties 里存在。启用严格结构输出时，某些 API 还会要求所有字段出现在 required 中，可选性通过允许 null 表达。

4. Gemini 不接受某些 JSON Schema 关键字

$schema、$id 或复杂的 additionalProperties 并不一定属于目标 API 支持的子集。迁移时应删除无关元数据，但不要误删 enum、required 和嵌套参数。

5. 工具名称不稳定

get-weather、get_weather 和 GetWeather 对业务人员来说可能是同一件事，但对 Agent 调度器来说是三个不同的标识符。确定命名规则后，不要在不同平台中随意改名。

6. Schema 合法，但工具描述太模糊

Schema 验证通过不等于模型会正确选择工具。description 应说清使用时机、输入边界和不该调用的场景，不要只写“查询数据”。

如何在浏览器里完成格式转换

打开 Tool Schema 转换器，粘贴 Claude Tool、OpenAI Function、Gemini Function Declaration 或原始 JSON Schema。工具会识别输入并同时生成三种平台格式。

开启 Strict Mode 时，转换器会为对象节点补充 additionalProperties: false，并根据属性列表整理 required。转换后建议再用 JSON 格式化与校验 检查语法，并用 Token 计数器 评估大量工具定义带来的上下文成本。

格式转换只能处理结构差异，不能证明业务语义正确。生成结果必须在目标 SDK 中做一次真实调用测试。

MCP 和多模型迁移检查清单

  1. 工具 name 在所有平台保持一致。
  2. description 明确说明调用时机和禁用场景。
  3. 所有 required 字段都存在于 properties。
  4. 嵌套对象和数组的 items 也被完整转换。
  5. Strict Mode 所需的对象限制已递归处理。
  6. 不支持的 $schema、$id 等元数据已移除。
  7. 参数类型和大小写符合当前 SDK 要求。
  8. 已测试正常输入、缺少必填字段和多余字段三种情况。
  9. 服务端仍会验证参数，而不是信任模型输出。
  10. 工具失败时返回可操作的错误，避免 Agent 无限重试。

官方规范与参考

常见问题

MCP 的 inputSchema 能直接给 Claude 使用吗？

参数 Schema 通常可以复用，但 Claude API 的工具定义字段是 input_schema，仍需转换外层字段并验证使用的 JSON Schema 特性是否受支持。

Claude input_schema 和 OpenAI parameters 有什么区别？

两者内部都以 JSON Schema 描述参数，但所在的 API 外层对象不同。OpenAI 还支持在 Function 对象中配置 Strict Mode，因此不应只做字段名替换。

为什么开启 strict: true 后 Schema 报错？

常见原因是对象节点未禁止额外字段、required 未覆盖所需属性，或使用了目标 API 不支持的 JSON Schema 关键字。

Gemini 的 type 为什么有时是大写？

不同 Gemini SDK 和示例可能使用枚举常量或 JSON 字符串。转换器会生成常见的大写类型形式，但最终仍应以项目使用的 SDK 版本为准。

Tool Schema 转换会上传我的接口定义吗？

PocketKit 的 Tool Schema 转换器 在浏览器中处理粘贴的 JSON，转换本身不需要把 Schema 发送到服务器。但在粘贴前仍应删除密钥、内部 URL 和其他敏感值。

转换后是否还需要测试？

需要。Schema 转换器能处理结构差异，但无法验证工具服务的权限、超时、业务参数和错误恢复逻辑。至少要测试一次正常调用和两次失败调用。

如果你正在搭建多模型 Agent，可以从 AI 应用开发工具包 继续完成 Schema 转换、Token 预算、提示词整理和安全测试。

FAQ

本文常见问题

MCP 的 inputSchema 能直接给 Claude 使用吗？

参数 Schema 通常可复用，但 Claude API 使用 input_schema 字段，仍需转换外层包装并确认所用 JSON Schema 特性受支持。

Claude input_schema 和 OpenAI parameters 有什么区别？

两者都用 JSON Schema 描述参数，但处于不同的 API 包装中；OpenAI 还可在 Function 对象上启用 strict 模式。

为什么开启 strict true 后 Schema 报错？

常见原因是对象未禁止额外属性、required 列表不完整，或使用了目标 API 不支持的 JSON Schema 关键字。

Tool Schema 转换后还需要测试吗？

需要。格式转换只能处理结构差异，不能验证服务权限、超时、业务参数和错误恢复逻辑。

← 返回博客