Skip to main content

Response API MCP 集成

Model Context Protocol (MCP) 是一个开源标准,用于连接AI应用程序与外部系统。通过MCP,AI模型可以访问文件系统、数据库、API服务等外部工具,大大扩展AI应用的能力。

快速开始

只需要替换 <API-KEY> 为你的实际API密钥即可运行。
curl -X POST "https://model-api.skyengine.com.cn/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API-KEY>" \
  -d '{
    "model": "gpt-5-2025-08-07",
    "tools": [
      {
        "type": "mcp",
        "server_label": "howtocook-mcp",
        "server_description": "查询菜谱的工具",
        "server_url": "https://mcp.api-inference.modelscope.net/5742da85755f4e/sse",
        "require_approval": "never"
      }
    ],
    "input": "帮我查询一个菜谱"
  }'

MCP工作原理

  1. 配置MCP工具: 在 tools 数组中定义MCP工具配置
  2. 服务器连接: API自动连接到指定的MCP服务器
  3. 工具导入: 自动从MCP服务器获取可用工具列表
  4. 工具调用: AI模型根据需要调用相应的MCP工具
  5. 结果返回: 工具执行结果整合到AI响应中

MCP工具配置

每个MCP工具在 tools 数组中定义:

配置格式

{
  "tools": [
    {
      "type": "mcp",
      "server_label": "服务器标识符",
      "server_description": "服务器描述",
      "server_url": "服务器URL",
      "require_approval": "审批要求"
    }
  ]
}

必需字段

  • type: 工具类型,必须为 "mcp"
  • server_label: 自定义的服务器标识符
  • server_description: 服务器功能描述
  • server_url: MCP服务器的端点URL
  • require_approval: 审批要求(“never”, “always”, “once”)

参数说明

必需参数

  • model - 要使用的模型ID
  • tools - MCP工具配置数组
  • input - 输入内容(文本或消息列表)

可选参数

  • max_output_tokens - 最大输出token数量
  • temperature - 控制输出随机性
  • tool_choice - 工具选择策略(“auto”, “required”, “none”)

响应格式

MCP工具列表响应

当API成功连接到MCP服务器并导入工具时,会返回以下格式:
{
    "id": "mcpl_68a6102a4968819c8177b05584dd627b0679e572a900e618",
    "type": "mcp_list_tools", 
    "server_label": "howtocook-mcp",
    "tools": [
        {
            "annotations": null,
            "description": "搜索菜谱和烹饪方法",
            "input_schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string"
                    }
                },
                "required": ["query"],
                "additionalProperties": false
            },
            "name": "search_recipe"
        }
    ]
}

完整响应格式

包含AI生成内容的完整响应:
{
    "id": "resp_0d6e102b1212ec030068fe0c5b00d48196aba4c7306f06178e",
    "object": "response",
    "created_at": 1761479771,
    "status": "completed",
    "background": false,
    "content_filters": null,
    "error": null,
    "incomplete_details": null,
    "instructions": null,
    "max_output_tokens": 13107,
    "max_tool_calls": null,
    "model": "gpt-5-2025-08-07",
    "output": [
        {
            "id": "rs_0d6e102b1212ec030068fe0c5b8cd8819681b4c8c2c91f2472",
            "type": "reasoning",
            "summary": []
        },
        {
            "id": "msg_0d6e102b1212ec030068fe0c5fc3188196a1677c52f2be231d",
            "type": "message",
            "status": "completed",
            "content": [
                {
                    "type": "output_text",
                    "annotations": [],
                    "logprobs": [],
                    "text": "当然可以!请告诉我下面的信息,我就给你一份详细菜谱:\n\n- 想做的菜名,或你手头有的3-5种食材\n- 口味偏好(清淡/家常/重辣/酸甜等)\n- 是否有饮食限制(素食、少油少盐、无麸质等)\n- 可用厨具(炒锅/烤箱/空气炸锅/电饭煲等)\n- 预计时间与份量(几人吃)\n\n如果还没想好菜名,我也可以给你推荐,比如:\n- 快手家常:番茄炒蛋、蒜蓉西兰花、醋溜土豆丝\n- 下饭硬菜:宫保鸡丁、红烧肉、麻婆豆腐\n- 清淡健康:清蒸鲈鱼、口蘑青菜、滑蛋虾仁\n- 西式简餐:蒜香黄油虾、培根奶油意面、烤蔬菜鸡胸\n\n也可以拍一张你冰箱或食材的照片,我来根据食材给你定制菜谱。"
                }
            ],
            "role": "assistant"
        }
    ],
    "parallel_tool_calls": true,
    "previous_response_id": null,
    "prompt_cache_key": null,
    "reasoning": {
        "effort": "medium",
        "summary": null
    },
    "safety_identifier": null,
    "service_tier": "default",
    "store": true,
    "temperature": 1.0,
    "text": {
        "format": {
            "type": "text"
        },
        "verbosity": "medium"
    },
    "tool_choice": "auto",
    "tools": [],
    "top_logprobs": 0,
    "top_p": 1.0,
    "truncation": "disabled",
    "usage": {
        "input_tokens": 12,
        "input_tokens_details": {
            "cached_tokens": 0
        },
        "output_tokens": 646,
        "output_tokens_details": {
            "reasoning_tokens": 384
        },
        "total_tokens": 658
    },
    "user": null,
    "metadata": {}
}

计费说明

MCP工具使用采用按需计费:
  • 工具导入: 仅在首次导入工具定义时计费
  • 工具调用: 每次实际调用MCP工具时计费
  • 无额外费用: 除标准token使用外无其他费用

注意事项

  1. 服务器可用性: 确保MCP服务器正常运行和可访问
  2. HTTP端点: MCP服务器必须提供HTTP端点
  3. 网络连接: 远程MCP服务器需要稳定的网络连接
  4. 服务器类型: 确保使用正确的服务器类型(如 streamable_http
  5. 数据安全: 注意MCP工具访问的数据安全性

常见错误

  • MCP server not found: 检查服务器URL和可用性
  • Tool import failed: 验证MCP服务器配置和HTTP端点
  • Connection timeout: 检查网络连接和服务器响应时间
  • Invalid server configuration: 确保所有必需字段都已正确配置
  • Server type mismatch: 检查服务器类型是否正确设置