跳转到主要内容
工具调用

连接 MCP 服务器

在对话中使用外部工具

千问云通过 Responses API 支持 Model Context Protocol (MCP)。在 tools 参数中传入一个或多个 MCP 服务器配置,模型会连接这些服务器,发现可用工具,并根据需要调用它们来完成请求。

快速开始

以下示例接入网页解析(WebParser)MCP 服务,展示如何通过 Responses API 调用 MCP 工具。需要先在百炼控制台开通网页解析(WebParser)MCP 服务。 查找与开通更多 MCP 服务,请参见MCP 服务
请将示例代码中 MCP 工具配置的 server_urlheaders 替换为您实际使用的 MCP 服务信息。
  • Python
  • Node.js
  • curl
import os
from openai import OpenAI

client = OpenAI(
  # 若没有配置环境变量,请用千问云 API Key 将下行替换为:api_key="sk-xxx"(不建议),
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)

# MCP 工具配置
mcp_tool = {
  "type": "mcp",
  "server_protocol": "sse",
  "server_label": "WebParser",
  "server_description": "网页解析(WebParser)MCP 服务,一个专用于网页内容解析的工具包。",
  "server_url": "https://dashscope.aliyuncs.com/api/v1/mcps/WebParser/sse",
  "headers": {
    "Authorization": "Bearer " + os.getenv("DASHSCOPE_API_KEY")
  }
}

response = client.responses.create(
  model="qwen3.6-plus",
  input="https://help.aliyun.com/zh/model-studio/mcp 里支持哪些模型?",
  tools=[mcp_tool]
)

print("[模型回复]")
print(response.output_text)
print(f"\n[Token 用量] 输入: {response.usage.input_tokens}, 输出: {response.usage.output_tokens}, 合计: {response.usage.total_tokens}")

工作原理

1

定义 MCP 工具配置

定义 MCP 工具配置,包括服务器的 SSE 端点和可选的认证头信息。
2

传入配置

在 Responses API 调用的 tools 参数中传入该配置。
3

模型连接并发现工具

模型连接 MCP 服务器,发现可用工具,并调用它们来处理输入。
4

接收响应

响应包含模型的最终输出,其中包括 MCP 工具调用的结果。
MCP 服务器是第三方服务。请仅连接您信任的服务器。恶意 MCP 服务器可能返回有害内容、通过工具描述窃取数据,或产生意外费用。添加服务器前,请务必验证其来源。
仅支持使用 SSE 协议的 MCP 服务器,每次请求最多可配置 10 个。

响应结构

典型的响应包含两个阶段:工具列举(模型发现可用工具)和最终输出(模型使用工具并返回结果)。 工具列举输出 响应的 output 数组首先包含一个 mcp_list_tools 项,展示模型在 MCP 服务器上发现的工具:
{
  "type": "mcp_list_tools",
  "server_label": "WebParser",
  "tools": [
    {
      "name": "web_parse",
      "description": "解析指定 URL 的网页内容并返回文本。",
      "input_schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": ["url"] }
    }
  ]
}
工具调用与最终输出 发现工具后,模型调用工具并生成最终的文本响应。output 数组包含每次工具调用对应的 mcp_call 项,以及一个包含综合回答的 message 项:
[模型回复]
根据千问云的官方文档,MCP(Model Context Protocol)目前支持的模型如下:

*   千问Plus系列:Qwen3.6-Plus系列、Qwen3.5-Plus系列
*   千问Flash系列:Qwen3.6-Flash系列、Qwen3.5-Flash系列
*   千问开源系列:Qwen3.6开源系列(注:qwen3.6-27b 除外)、Qwen3.5开源系列

特别注意:
MCP 功能仅支持通过 Responses API 调用。

[Token 用量] 输入: 20698, 输出: 711, 合计: 21409
实际响应取决于 MCP 服务器抓取到的实时内容。Token 用量因请求而异。
错误处理 如果模型无法连接 MCP 服务器,响应的 status"failed",顶层的 error 对象包含具体信息。output 数组为空。
{
  "error": {
    "code": "server_error",
    "message": "<400> InternalError.Algo.InvalidParameter: Agent invalid parameter. The error message is [Mcp Server config is invalid.]"
  },
  "status": "failed",
  "output": []
}
常见原因包括 server_url 无效和服务器超时。请检查 error.codeerror.message 字段进行排查。
如果 MCP 服务器可达但认证失败,模型可能会静默跳过 MCP 工具,不使用它们直接响应。此时不会返回错误信息。

启用流式输出

MCP 工具调用可能涉及与外部服务器的多次往返通信。启用流式输出可实时接收工具调用进度和模型响应。在请求中添加 stream=True(Python)、stream: true(Node.js / curl)即可。 流式输出的实现细节、事件类型和代码示例,请参阅流式输出

MCP 专属流式事件

除标准流式事件外,MCP 响应还会产生以下事件类型:
事件类型说明
response.mcp_list_tools.doneMCP 服务器的工具发现已完成。
response.mcp_call.doneMCP 工具调用已完成并返回结果。

MCP 工具参数

参数必填说明
type固定值 "mcp"
server_protocol通信协议,仅支持 "sse"
server_labelMCP 服务器的简短标识。
server_description服务器功能的自然语言描述。清晰的描述有助于模型判断何时调用该服务器的工具,提高工具选择的准确性。建议为所有 MCP 服务器提供此参数。
server_urlMCP 服务器的 SSE 端点 URL。
headers连接 MCP 服务器时附带的 HTTP 头,例如用于认证的 Authorization
带认证的配置示例
{
  "type": "mcp",
  "server_protocol": "sse",
  "server_label": "WebParser",
  "server_description": "网页解析(WebParser)MCP 服务,一个专用于网页内容解析的工具包。",
  "server_url": "https://dashscope.aliyuncs.com/api/v1/mcps/WebParser/sse",
  "headers": {
    "Authorization": "Bearer $DASHSCOPE_API_KEY"
  }
}

支持的模型

MCP 仅通过 Responses API 提供。以下模型支持 MCP 工具调用:
模型系列模型 ID
Qwen-Plusqwen3.6-plus 系列, qwen3.5-plus 系列
Qwen-Flashqwen3.6-flash 系列, qwen3.5-flash 系列
Qwen3.6 开源Qwen3.6 开源系列(qwen3.6-27b 除外)
Qwen3.5 开源Qwen3.5 开源系列

计费

使用 MCP 时涉及两类费用:
  • 模型推理费用:根据模型的 Token 用量计费。
  • MCP 服务器费用:按各 MCP 服务器提供商的计费规则收取。