指南：使用响应式API的MCP工具

构建代理应用程序通常需要连接到外部服务。传统上，这是通过函数调用完成的，每次操作都会使模型与您的后端、然后与外部服务进行一次往返，等待响应，最后将结果返回给模型。这个过程引入了多个网络跳数和显著的延迟，使其难以扩展和管理。

响应式API中托管的Model Context Protocol (MCP)工具使这变得更加容易。您无需手动将每个函数调用连接到特定服务，而是可以一次性配置您的模型以指向一个MCP服务器（或几个！）。该服务器充当一个集中的工具主机，公开“搜索产品目录”或“将商品添加到购物车”等标准命令。这允许更简单的编排和集中的工具管理。通过MCP，模型直接与MCP服务器交互，减少延迟并消除后端协调。

MCP工具简化了用例

MCP显著减少了构建与外部服务交互的产品的摩擦，使您能够无缝地将不同的服务连接在一起。以下是一些曾经涉及摩擦但现在由于模型可以直接与远程MCP服务器通信而变得更加简单的用例示例。

| 领域 | MCP工具解锁的用例 | 之前的摩擦 |

工具工作原理

总的来说，MCP工具的工作原理如下：

1. 声明服务器： 当您将MCP块添加到tools数组时，响应式API运行时首先检测服务器使用的传输协议，无论是较新的“流式HTTP”还是较旧的HTTP-over-SSE变体，并使用该协议进行通信。

2. 导入工具列表： 运行时调用服务器的tools/list，传递您提供的任何标头（API密钥、OAuth令牌等）。然后，它将结果写入模型上下文中的mcp_list_tools项。只要此项存在，就不会再次获取列表。您可以使用allowed_tools来限制模型可以看到的内容。

   OpenAI在每次请求后会丢弃标头值以及MCP server_url的模式、域和子域。授权密钥和服务器URL必须包含在每次API调用中。这些值不会出现在响应对象中。模式在可能的情况下使用“严格”模式，否则按原样加载。

3. 调用和批准工具： 一旦模型知道可用的操作，它就可以调用一个。每次调用都会产生一个mcp_tool_call项，默认情况下，流会暂停以等待您的明确批准，但一旦您信任服务器，就可以禁用此功能。

   批准后，运行时将执行调用，流回结果，然后模型决定是链接另一个工具还是返回最终答案。

使用MCP构建的最佳实践

MCP仍处于早期阶段，因此以下最佳实践可以在您构建时提高模型性能和行为。

过滤工具以避免载荷膨胀

远程服务器通常会公开许多工具，而不会考虑模型将如何解释和使用它们。默认情况下，这可能导致包含数十个端点，每个端点都附带详细的定义，如名称、描述和JSON模式，这些都会为模型的上下文增加数百个令牌并增加延迟。此外，许多服务器会返回整个数据对象，例如完整的Stripe发票记录，即使只有少数字段与模型的任务相关。为了优化生产中的性能，请使用响应式API中的allowed_tools参数来限制从服务器的mcp_list_tools中包含哪些工具。这可以减少令牌开销，提高响应时间，并缩小模型的决策范围。您可能还想完全排除某些工具，例如那些能够执行写操作的工具，或者那些具有财务或安全影响的工具。

curl https://api.openai.com/v1/responses -i \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "tools": [
        {
            "type": "mcp",
            "server_label": "gitmcp",
            "server_url": "https://gitmcp.io/openai/tiktoken",
            "allowed_tools": ["search_tiktoken_documentation", "fetch_tiktoken_documentation"],
            "require_approval": "never"
        }
    ],
    "input": "how does tiktoken work?"
}'

通过缓存减少延迟和令牌，并将推理模型保留用于高复杂度任务

模型首次连接到服务器时，将为每个添加的MCP服务器创建一个新的mcp_list_tools类型的项。只要此项存在于模型的上下文中，我们就不会再次调用服务器上的tools/list。这类似于用户对话级别的缓存。如果mcp_list_tools不存在，我们将再次从MCP服务器导入工具列表。在后续API请求中传递previous_response_id是确保mcp_list_tools项在后续回合中存在于模型上下文中的一种方法。或者，您也可以手动将项传递给新的响应。另一个会影响延迟和输出令牌数量的因素是您是否使用推理模型，因为推理模型将产生更多的输出令牌，以及推理令牌。以以下两个示例curl为例，它们比较了使用和不使用推理模型的令牌数量：

场景1：非推理模型

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "tools": [
      {
        "type": "mcp",
        "server_label": "gitmcp",
        "server_url": "https://gitmcp.io/openai/tiktoken",
        "require_approval": "never"
      }
    ],
    "input": "how does tiktoken work?"
  }'

  "usage": {
    "input_tokens": 280,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 665,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 945
  }

场景2：没有previous_response_id的推理模型

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "o4-mini",
    "tools": [
      {
        "type": "mcp",
        "server_label": "gitmcp",
        "server_url": "https://gitmcp.io/openai/tiktoken",
        "require_approval": "never"
      }
    ],
    "input": "how does tiktoken work?",
    "reasoning": {
      "effort": "medium",
      "summary": "auto"
    }
  }'

  "usage": {
    "input_tokens": 36436,
    "input_tokens_details": {
      "cached_tokens": 22964
    },
    "output_tokens": 1586,
    "output_tokens_details": {
      "reasoning_tokens": 576
    },
    "total_tokens": 38022
    }

将MCP与其他工具结合使用

MCP工具只是工具数组中的另一个条目，因此模型可以将其与其他托管工具（如code_interpreter、web_search_preview或image_generation）以及您定义的任何自定义工具无缝结合使用。您还可以一起使用多个远程MCP服务器。

在此示例中，我们将创建一个代理，该代理是一家虚构瑜伽服装店的定价分析师：它首先从Alo Yoga MCP服务器提取当前竞争对手的女士短裤、瑜伽裤和背心价格，然后通过托管的网络搜索工具获取Uniqlo相同类别的价格。使用Code Interpreter，它分析上周的销售数据（来自通过Files端点预加载的CSV），以计算每件商品的收入和平均订单价值。然后，它测量每件商品的价格与新获取的Uniqlo和Alo Yoga基准之间的价格差距。任何定价高于或低于市场价15%或更多的产品都会被标记出来，代理会提供一份简明的文本报告，总结差异和关键收入统计数据。

system_prompt= """您是我服装公司的定价分析师。请使用MCP工具
从Alo Yoga MCP服务器获取女士
短裤、瑜伽裤和背心的价格。仅使用Alo yoga数据使用MCP服务器，不要搜索网络。

接下来，使用网络搜索工具查找Uniqlo女士短裤、瑜伽裤和背心的价格。

在每种情况下，对于Alo Yoga和Uniqlo，请提取
每个类别的最高结果的价格。还请提供完整的URL

使用上传的商店销售数据CSV文件，并使用
代码解释器工具计算每个
商品的收入，计算交易级别的平均订单价值，并计算CSV数据与Uniqlo/Alo Yoga价格之间的百分比价格差距。
标记定价高于或低于市场价15%或更多的产品。
创建并输出一份简明报告，包括调查结果。

# 步骤

1. **获取Alo Yoga价格：**
   - 使用Alo Yoga MCP服务器获取以下产品的价格：
高腰Airlift紧身裤
Sway Bra Tank
 5" Airlift Energy Short

- 确保找到每种产品的价格。
- 提取每个类别的最高结果的价格。
- 包括URL链接


2. **查询Uniqlo价格：**
   - 使用网络搜索工具查找以下Uniqlo产品的非促销价格：
女士AIRism柔软骑行短裤
女士AIRism柔软紧身裤
女士AIRism文胸无袖上衣

- 确保找到每种产品的非促销价格。
- 提取每个类别的最高结果的价格。
- 包括URL链接

3. **销售数据分析：**
   - 使用上传的CSV销售数据计算每个
商品的收入。

   - 确定交易级别的平均订单价值。
   - 对于每个SKU，计算CSV数据与Uniqlo/Alo Yoga价格之间的百分比价格差距。
   - 标记定价高于或低于市场价≥15%的产品。

4. **报告：**
   - 编译并输出一份报告，包括标记结果

# 输出格式

- 一份简明的文本报告，解释：
  - 任何定价高于或低于市场价≥15%的产品，
附带具体细节。 """

这是带有上述系统提示占位符的示例curl。

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "input": [
      {
        "role": "system",
        "content": [
          {
            "type": "input_text",
            "text": "ABOVE_SYSTEM_PROMPT"
          }
        ]
      }
    ],
    "tools": [
      {
        "type": "web_search_preview",
        "user_location": {
          "type": "approximate",
          "country": "US"
        },
        "search_context_size": "medium"
      },
      {
        "type": "code_interpreter",
        "container": {
          "type": "auto",
          "file_ids": [
            "file-WTiyGcZySaU6n218gj4XxR"
          ]
        }
      },
      {
        "type": "mcp",
        "server_url": "https://www.aloyoga.com/api/mcp",
        "server_label": "aloyoga",
        "allowed_tools": [
          "search_shop_catalog",
          "get_product_details"
        ],
        "require_approval": "never"
      }
    ],
    "temperature": 1,
    "max_output_tokens": 2048,
    "top_p": 1,
    "store": true
  }'

模型能够将其从MCP工具和网络搜索中的结果传递到代码解释器步骤，以生成格式清晰的报告，内容如下：

价格比较与收入分析报告

您的商店销售与价格分析

• 按产品划分的收入：
  • 短裤：$6,060
  • 背心：$6,150
  • 瑜伽裤：$12,210
• 平均订单价值： $872.14
• 您的商店各类别平均售价：
  • 短裤：$60.00
  • 背心：$75.00
  • 瑜伽裤：$110.00

与市场的价格差距

| 类别 | 店铺平均价 | 对比Alo Yoga价格差距 (%) | 标记 (≥15%) | 对比Uniqlo价格差距 (%) | 标记 (≥15%) |

建议与标记

标记产品（价格差距≥15%）：

• 短裤： 价格比Alo Yoga低31.8%，但比Uniqlo高100.7%。
• 背心： 价格比Uniqlo高114.9%以上。
• 瑜伽裤： 价格比Uniqlo高267.9%。

短裤的价格明显低于高端竞争对手（Alo Yoga），但远高于经济型替代品（Uniqlo）。如果您想进入高端市场，可以考虑提高价格。如果您想瞄准经济型买家，降低价格是可以理解的。您的大多数背心和瑜伽裤定位相似——远低于Alo，但远高于Uniqlo。

改进MCP工具调用的提示指南

根据您的用例，您可能会发现模型会调用许多MCP调用，例如在使用目录搜索工具时。为了避免对大型产品库存进行无休止的迭代，最好指示模型将搜索限制为N个项目，并在用户明确要求更多信息时才提供继续的选项。这可以使响应保持专注和快速。

如果使用的MCP服务器包含详尽的mcp_list_tools，那么包含一些有针对性的少量示例来向模型展示如何选择正确的服务器并在获得所需信息后停止，而不是发出冗余调用，也是值得的。

最后，添加指导以提醒模型，如果用户查询中缺少关键信息（尺寸、颜色、产品线等），它应该先提出后续问题，而不是进行广泛搜索。这种小小的提示可以减少不必要的工具调用并提高答案质量。以下是一个示例提示，展示了这些指南如何结合在一起：

system_prompt= """您是一位可以调用以下MCP服务器的AI助手：

1. allbirds_store
2. gitmcp

步骤

1. 使用上述MCP服务器回答用户查询，并非所有MCP服务器都与给定查询相关，因此您可以选择要调用的服务器。
2. 如果用户请求缺少关键详细信息（尺寸、颜色等），请先提出后续问题，而不是猜测并过早使用MCP服务器工具。
3. 如果搜索目录中的产品，每次最多返回4个结果，然后询问用户是否想查看更多。

### 少量示例

# EX1 — 直接产品搜索，然后获取变体详细信息
user: Allbirds Tree Runner男款尺码10有货吗？
assistant: {"name":"allbirds_store.search_shop_catalog",
            "arguments":{"query":"Tree Runner",
                         "context":"Men’s size 10 shoes"}}
# （假设搜索返回 product_id "gid://shopify/Product/987"）
assistant: {"name":"allbirds_store.get_product_details",
            "arguments":{"product_id":"gid://shopify/Product/987",
                         "options":{"Size":"10"}}}

# EX2 — 澄清缺失的尺码，然后进行两步颜色变体查找
user: 我想要蓝色的Tree Runner。
assistant: 好的——您需要什么尺码？
user: 尺码10。
assistant: {"name":"allbirds_store.search_shop_catalog",
            "arguments":{"query":"Tree Runner",
                         "context":"Blue variant, size 10"}}
# （假设搜索返回 product_id "gid://shopify/Product/987"）
assistant: {"name":"allbirds_store.get_product_details",
            "arguments":{"product_id":"gid://shopify/Product/987",
                         "options":{"Size":"10","Color":"Blue"}}}

# EX3 — Git文档：搜索然后获取特定文件
user: 你能告诉我tiktoken如何进行字节对编码吗？
assistant: {"name":"gitmcp.search_website_documentation",
            "arguments":{"query":"tiktoken byte-pair encoding"}}
# （假设搜索返回 document_id "docs/ENCODING.md"）
assistant: {"name":"gitmcp.fetch_website_documentation",
            "arguments":{"document_id":"docs/ENCODING.md"}} """

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4.1",
    "input": [
      {
        "role": "system",
        "content": [
          {
            "type": "input_text",
            "text": "ABOVE_SYSTEM_PROMPT"
          }
        ]
      },
      {
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "find me womens tree loungers in size 8"
          }
        ]
      }
    ],
    "tools": [
      {
        "type": "mcp",
        "server_url": "https://www.allbirds.com/api/mcp",
        "server_label": "allbirds",
        "allowed_tools": [
          "search_shop_catalog",
          "get_cart",
          "update_cart",
          "search_shop_policies_and_faqs",
          "get_product_details"
        ],
        "require_approval": "never"
      },
      {
        "type": "mcp",
        "server_label": "gitmcp",
        "server_url": "https://gitmcp.io/openai/tiktoken",
        "allowed_tools": [
          "fetch_tiktoken_documentation",
          "search_tiktoken_documentation",
          "search_tiktoken_code",
          "fetch_generic_url_content"
        ],
        "require_approval": "never"
      }
    ],
    "temperature": 1,
    "max_output_tokens": 2048
  }'

结论

响应式API中的托管MCP工具将外部服务访问从定制的管道任务转变为API的一等能力。通过连接到远程服务器、让运行时缓存其工具列表，并使用allowed_tools修剪该列表，您可以消除额外的网络跳数，减少令牌开销，并为模型提供一个简洁、可发现的操作集。当与code_interpreter、web_search_preview或image_gen等内置工具结合使用时，MCP可以实现丰富的多服务工作流，无论您是在分析销售数据、分类生产错误还是自动化结账流程。