# 云部署 MCP / Remote MCP > 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。 ## 核心功能 * 兼容丰富的 MCP 生态：已对接 [智能体工具商店](https://www.volcengine.com/mcp-marketplace)，支持调用市场内各类垂直领域 MCP 工具（如巨量千川、知识库），无需自行开发工具逻辑。 * 多轮工具调用：复杂任务（例如多步数据查询+分析）支持多轮 MCP 调用，上一轮工具输出结果自动作为下一轮模型输入（例：MCP 数据查询→模型分析→二次补充查询）。 * 灵活混合调用：可与用户自定义函数、Web Search 工具混合使用（如联合巨量千川 MCP 与 Web Search 实现“数据+热点”交叉分析），暂不限制工具组合数量。 ## 准备工作：获取 MCP URL > **说明** > > 方舟平台的新用户？获取 API Key 及 开通模型等准备工作，请参见 [快速入门](/docs/quick-start)。 1. 您可以访问 [智能体工具商店](https://www.volcengine.com/mcp-marketplace)，选择想要使用的云部署 MCP 或 Remote MCP。 ![](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/4b1779c885354816878ca958a3268e1e~tplv-goo7wpa0wc-image.image) 2. 在 MCP 详情页，点击生成获取带授权信息的个人 MCP 服务端 URL。 > 部分 MCP 通过`Authorization`字段来配置授权，详情请参考[2. 配置鉴权信息](/docs/mcp-remote-mcp#8cf42728)。 ![](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/c85a81f998b24194a89d343a84576c0a~tplv-goo7wpa0wc-image.image) ## 快速入门 > **说明** > > * 以下常用调用场景示例代码中，需先将 `` 替换为实际密钥，并将 `server_label`/`server_url` 替换为实际 MCP Server 信息。 > * 测试期间调用此工具需要增加 header '`ark-beta-mcp: true`'。 **选项：cURL** ```Bash curl --location 'https://ark.cn-beijing.volces.com/api/v3/responses' \ --header "Authorization: Bearer " \ --header 'Content-Type: application/json' \ --header 'ark-beta-mcp: true' \ --data '{ "model": "doubao-seed-2-1-pro-260915", "stream": true, "tools": [ { "type": "mcp", "server_label": "deepwiki", "server_url": "https://mcp.deepwiki.com/mcp", "require_approval": "never" } ], "input": [ { "role": "user", "content": [ { "type": "input_text", "text": "看一下volcengine/ai-app-lab这个repo的文档" } ] } ] }' ``` **选项：Python SDK** ```Python from arkruntime import Ark import os # 从环境变量获取API密钥（配置方法：https://ark.volcengine.com/region:cn-beijing/docs/quick-start） api_key = os.getenv('ARK_API_KEY') # 初始化客户端，启用MCP功能 client = Ark( base_url='https://ark.cn-beijing.volces.com/api/v3', api_key=api_key ) # 发起基础MCP调用请求 response = client.responses.create( model="doubao-seed-2-1-pro-260915", tools=[ { "type": "mcp", "server_label": "deepwiki", "server_url": "https://mcp.deepwiki.com/mcp", "require_approval": "never" } ], input=[ { "role": "user", "content": [ { "type": "input_text", "text": "看一下volcengine/ai-app-lab这个repo的文档" } ] } ], extra_headers={"ark-beta-mcp": "true"}, stream=True # 流式获取结果 ) # 打印响应结果 for chunk in response: if hasattr(chunk, 'delta'): print(chunk.delta, end="", flush=True) ``` **选项：Java SDK** ```Java package com.example.arkdemo; import com.volcengine.ark.runtime.model.responses.constant.ResponsesConstants; import com.volcengine.ark.runtime.model.responses.event.StreamEvent; import com.volcengine.ark.runtime.model.responses.request.ResponsesInput; import com.volcengine.ark.runtime.model.responses.request.CreateResponsesRequest; import com.volcengine.ark.runtime.model.responses.tool.ToolMCP; import com.volcengine.ark.runtime.model.responses.tool.mcp.MCPRequireApproval; import com.volcengine.ark.runtime.model.responses.event.reasoningsummary.ReasoningSummaryTextDeltaEvent; import com.volcengine.ark.runtime.model.responses.event.outputitem.OutputItemDoneEvent; import com.volcengine.ark.runtime.model.responses.event.outputtext.OutputTextDeltaEvent; import com.volcengine.ark.runtime.service.ArkService; import okhttp3.ConnectionPool; import okhttp3.Dispatcher; import com.volcengine.ark.runtime.model.responses.common.ResponsesThinking; import com.volcengine.ark.runtime.model.responses.event.response.ResponseCompletedEvent; import java.time.Duration; import java.util.Collections; import java.util.HashMap; import java.util.Map; import java.util.concurrent.TimeUnit; public class mcpjava { // 固定使用的模型 private static final String model = "doubao-seed-2-1-pro-260915"; public static void main(String[] args) { // 1. 校验鉴权凭证（必须配置 ARK_API_KEY 环境变量） String apiKey = System.getenv("ARK_API_KEY"); if (apiKey == null) { System.out.println("ARK_API_KEY environment variable not set"); return; } // 2. 初始化 ArkService（配置连接池、并发、超时等） ConnectionPool connectionPool = new ConnectionPool(5, 1, TimeUnit.SECONDS); Dispatcher dispatcher = new Dispatcher(); dispatcher.setMaxRequests(5000); dispatcher.setMaxRequestsPerHost(5000); ArkService service = ArkService.builder() .dispatcher(dispatcher) .timeout(Duration.ofHours(1)) .connectionPool(connectionPool) .apiKey(apiKey) .build(); // 3. 构造 MCP 工具调用请求 CreateResponsesRequest mcpRequest = CreateResponsesRequest.builder() .model(model) .stream(true) // 流式响应，实时获取结果 // 配置 MCP 工具：指定服务标签、服务地址、审批模式 .tools(Collections.singletonList( ToolMCP.builder() .serverLabel("deepwiki-test") // MCP 服务标签 .serverUrl("https://mcp.deepwiki.com/mcp") // MCP 服务接口地址 // 审批模式：NEVER（无需审批）、ALWAYS（必须审批）、AUTO（自动审批） .requireApproval(MCPRequireApproval.builder() .mode(ResponsesConstants.MCP_APPROVAL_MODE_NEVER) .build()) .build() )) // 输入查询指令：让 MCP 工具查询指定仓库结构 .input(ResponsesInput.builder() .stringValue("查看这个 repo的structure expressjs/express") .build()) // 启用模型思考过程（可在流式输出中查看） .thinking(ResponsesThinking.builder() .type(ResponsesConstants.THINKING_TYPE_ENABLED) .build()) .build(); // 4. 构造自定义 Header（设置 ark-beta-mcp:true） Map customHeaders = new HashMap<>(); customHeaders.put("ark-beta-mcp", "true"); // 5. 执行 MCP 工具调用并处理流式响应（传入自定义 Header） try { System.out.println("----- [MCP Tool Call] 开始调用 -----"); // 流式调用时传入 headers 参数 service.streamResponse(mcpRequest, customHeaders) .doOnError(Throwable::printStackTrace) // 异常处理 .blockingForEach(mcpjava::printStreamEvent); // 监听流式事件 } catch (Exception e) { System.err.println("MCP Tool Call Error: " + e.getMessage()); e.printStackTrace(); } // 6. 关闭服务 executor，释放资源 service.shutdownExecutor(); } // 跟踪是否已输出思考过程前缀 private static boolean isReasoningPrefixPrinted = false; // 跟踪是否已输出工具返回前缀 private static boolean isToolPrefixPrinted = false; // 流式事件处理：打印思考过程、响应内容、工具调用状态 private static void printStreamEvent(StreamEvent event) { // 打印思考过程增量（如模型分析如何调用 MCP 工具） if (event instanceof ReasoningSummaryTextDeltaEvent) { ReasoningSummaryTextDeltaEvent reasoningEvent = (ReasoningSummaryTextDeltaEvent) event; String delta = reasoningEvent.getDelta(); // 只在思考过程开始时添加前缀 if (!isReasoningPrefixPrinted && delta.trim().length() > 0) { System.out.print("[思考过程] " + delta); isReasoningPrefixPrinted = true; } else { System.out.print(delta); } // 如果遇到换行符，重置前缀标记 if (delta.contains("\n")) { isReasoningPrefixPrinted = false; } } // 打印文本响应增量（MCP 工具返回结果的实时输出） else if (event instanceof OutputTextDeltaEvent) { OutputTextDeltaEvent textEvent = (OutputTextDeltaEvent) event; String delta = textEvent.getDelta(); // 只在工具返回开始时添加前缀 if (!isToolPrefixPrinted && delta.trim().length() > 0) { System.out.print("[工具返回] " + delta); isToolPrefixPrinted = true; } else { System.out.print(delta); } // 如果遇到换行符，重置前缀标记 if (delta.contains("\n")) { isToolPrefixPrinted = false; } } // 打印输出项完成事件 else if (event instanceof OutputItemDoneEvent) { OutputItemDoneEvent itemEvent = (OutputItemDoneEvent) event; System.out.println("\n[输出完成] " + itemEvent.getItem().getType()); // 重置所有前缀标记 isReasoningPrefixPrinted = false; isToolPrefixPrinted = false; } // 整体响应完成，打印调用用量 else if (event instanceof ResponseCompletedEvent) { ResponseCompletedEvent completedEvent = (ResponseCompletedEvent) event; System.out.println("\n[响应完成] 调用用量：" + completedEvent.getResponse().getUsage()); // 重置所有前缀标记 isReasoningPrefixPrinted = false; isToolPrefixPrinted = false; } // 打印所有其他未处理的事件类型（用于调试） else { System.out.println("\n[未处理事件] 类型：" + event.getClass().getName()); // 重置所有前缀标记 isReasoningPrefixPrinted = false; isToolPrefixPrinted = false; } } } ``` **选项：Go SDK** ```Go package main import ( "context" "fmt" "io" "os" "github.com/volcengine/ark-runtime-go/arkruntime" "github.com/volcengine/ark-runtime-go/arkruntime/model/responses" ) const ( mcpServerURL = "https://mcp.deepwiki.com/mcp" mcpLabel = "deepwiki" mcpBetaHeader = "ark-beta-mcp" userPrompt = "查一下 mark3labs/mcp-go 这个仓库的结构" ) func main() { nonStream() fmt.Println() stream() } func newClient() *arkruntime.Client { return arkruntime.NewClientWithApiKey( os.Getenv("ARK_API_KEY"), arkruntime.WithBaseUrl("https://ark.cn-beijing.volces.com/api/v3"), ) } func nonStream() { fmt.Println("===== non-streaming =====") client := newClient() ctx := context.Background() // Round 1: ask the model to call the MCP tool. req1 := &responses.ResponsesRequest{ Model: "doubao-seed-2-1-pro-260915", Input: responses.NewInputItemArrayResponsesInput([]responses.InputItem{ {OneOf: responses.NewItemEasyMessageInputItemSum(buildUserMessage())}, }), Tools: []responses.Tool{mcpTool(false)}, } resp1, err := client.CreateResponses( ctx, req1, arkruntime.WithCustomHeader(mcpBetaHeader, "true"), ) if err != nil { fmt.Printf("round 1 error: %v\n", err) return } fmt.Printf("response: %+v\n", resp1) approvalRequestID := findApprovalRequestID(resp1.Output) if approvalRequestID == "" { fmt.Println("no approval request emitted; nothing to approve") return } // Round 2: approve the requested MCP call. req2 := &responses.ResponsesRequest{ Model: "doubao-seed-2-1-pro-260915", Input: responses.NewInputItemArrayResponsesInput([]responses.InputItem{ {OneOf: responses.NewItemFunctionMcpApprovalResponseInputItemSum( responses.ItemFunctionMcpApprovalResponse{ Type: responses.ItemFunctionMcpApprovalResponseTypeMcpApprovalResponse, ApprovalRequestID: approvalRequestID, Approve: true, }, )}, }), Tools: []responses.Tool{mcpTool(false)}, PreviousResponseID: responses.NewOptString(resp1.ID), } resp2, err := client.CreateResponses( ctx, req2, arkruntime.WithCustomHeader(mcpBetaHeader, "true"), ) if err != nil { fmt.Printf("round 2 error: %v\n", err) return } fmt.Printf("response: %+v\n", resp2) // Round 3: let the model call the MCP tool without approval. req3 := &responses.ResponsesRequest{ Model: "doubao-seed-2-1-pro-260915", Input: responses.NewInputItemArrayResponsesInput([]responses.InputItem{ {OneOf: responses.NewItemEasyMessageInputItemSum(buildUserMessage())}, }), Tools: []responses.Tool{mcpTool(true)}, } resp3, err := client.CreateResponses( ctx, req3, arkruntime.WithCustomHeader(mcpBetaHeader, "true"), ) if err != nil { fmt.Printf("round 3 error: %v\n", err) return } fmt.Printf("response: %+v\n", resp3) } func stream() { fmt.Println("===== streaming =====") client := newClient() ctx := context.Background() req1 := &responses.ResponsesRequest{ Model: "doubao-seed-2-1-pro-260915", Input: responses.NewInputItemArrayResponsesInput([]responses.InputItem{ {OneOf: responses.NewItemEasyMessageInputItemSum(buildUserMessage())}, }), Tools: []responses.Tool{mcpTool(false)}, } responseID, approvalRequestID, err := streamAndCapture(ctx, client, req1) if err != nil { fmt.Printf("round 1 stream error: %v\n", err) return } if approvalRequestID == "" { fmt.Println("no approval request emitted; nothing to approve") return } req2 := &responses.ResponsesRequest{ Model: "doubao-seed-2-1-pro-260915", Input: responses.NewInputItemArrayResponsesInput([]responses.InputItem{ {OneOf: responses.NewItemFunctionMcpApprovalResponseInputItemSum( responses.ItemFunctionMcpApprovalResponse{ Type: responses.ItemFunctionMcpApprovalResponseTypeMcpApprovalResponse, ApprovalRequestID: approvalRequestID, Approve: true, }, )}, }), Tools: []responses.Tool{mcpTool(false)}, PreviousResponseID: responses.NewOptString(responseID), } if _, _, err := streamAndCapture(ctx, client, req2); err != nil { fmt.Printf("round 2 stream error: %v\n", err) return } req3 := &responses.ResponsesRequest{ Model: "doubao-seed-2-1-pro-260915", Input: responses.NewInputItemArrayResponsesInput([]responses.InputItem{ {OneOf: responses.NewItemEasyMessageInputItemSum(buildUserMessage())}, }), Tools: []responses.Tool{mcpTool(true)}, } if _, _, err := streamAndCapture(ctx, client, req3); err != nil { fmt.Printf("round 3 stream error: %v\n", err) } } func buildUserMessage() responses.ItemEasyMessage { return responses.ItemEasyMessage{ Role: responses.NewOptMessageRole(responses.MessageRoleUser), Content: responses.NewContentItemArrayMessageContent([]responses.ContentItem{ { OneOf: responses.NewContentItemTextContentItemSum(responses.ContentItemText{ Type: responses.ContentItemTextTypeInputText, Text: userPrompt, }), }, }), } } func mcpTool(skipApproval bool) responses.Tool { mcp := responses.McpTool{ Type: responses.McpToolTypeMcp, ServerLabel: mcpLabel, ServerURL: mcpServerURL, ServerDescription: responses.NewOptString("Query a GitHub repository's documentation"), } if skipApproval { mcp.RequireApproval = responses.NewOptMcpRequireApproval( responses.NewMcpApprovalModeMcpRequireApproval(responses.McpApprovalModeNever), ) } return responses.Tool{OneOf: responses.NewMcpToolToolSum(mcp)} } func findApprovalRequestID(output []responses.OutputItem) string { for i := len(output) - 1; i >= 0; i-- { if request, ok := output[i].OneOf.GetItemFunctionMcpApprovalRequest(); ok { return request.ID.Or("") } } return "" } func streamAndCapture( ctx context.Context, client *arkruntime.Client, req *responses.ResponsesRequest, ) (string, string, error) { stream, err := client.CreateResponsesStream( ctx, req, arkruntime.WithCustomHeader(mcpBetaHeader, "true"), ) if err != nil { return "", "", err } var responseID string var approvalRequestID string for { event, err := stream.Recv() if err == io.EOF { return responseID, approvalRequestID, nil } if err != nil { return responseID, approvalRequestID, err } switch event.OneOf.Type { case responses.ResponseCreatedEventResponseStreamEventSum: responseID = event.OneOf.ResponseCreatedEvent.Response.ID case responses.ResponseReasoningSummaryTextDeltaEventResponseStreamEventSum: fmt.Print(event.OneOf.ResponseReasoningSummaryTextDeltaEvent.Delta.Or("")) case responses.ResponseTextDeltaEventResponseStreamEventSum: fmt.Print(event.OneOf.ResponseTextDeltaEvent.Delta.Or("")) case responses.ResponseTextDoneEventResponseStreamEventSum: fmt.Printf("\n[text done] %s\n", event.OneOf.ResponseTextDoneEvent.Text.Or("")) case responses.ResponseOutputItemDoneEventResponseStreamEventSum: item := event.OneOf.ResponseOutputItemDoneEvent.Item if request, ok := item.OneOf.GetItemFunctionMcpApprovalRequest(); ok { approvalRequestID = request.ID.Or("") fmt.Printf( "\n[mcp approval request] name=%s arguments=%s\n", request.Name, request.Arguments, ) } case responses.ResponseMcpCallArgumentsDeltaEventResponseStreamEventSum: fmt.Print(event.OneOf.ResponseMcpCallArgumentsDeltaEvent.Delta) case responses.ResponseMcpCallCompletedEventResponseStreamEventSum: fmt.Println("\n[mcp call completed]") case responses.ResponseMcpListToolsInProgressEventResponseStreamEventSum: fmt.Println("\n[listing mcp tools]") case responses.ResponseMcpListToolsCompletedEventResponseStreamEventSum: fmt.Println("\n[mcp tools listed]") } } } ``` ## 参数说明 详情请参见[创建 Response](/docs/create-model-responses-api)。 ## 支持的模型列表 参见[工具调用能力](/docs/model-list#f44ceef7)。 > 模型调用需确保已完成 MCP 服务开通及对应模型权限申请，未开通用户无法触发 MCP 工具功能。 ## 工作原理 您可以通过 `Responses` API 调用 MCP 工具（包括云部署 MCP 和 Remote MCP）。此功能与函数调用的主要区别在于，MCP 工具完全在云端执行：大模型会连接至远程服务器来完成调用，因此不支持本地 MCP 运行调用。 ## 使用指南 本节介绍了常见的使用场景及其字段设置方法，以帮助您更高效地运用 MCP 工具。 ### 1. 过滤 MCP 工具 一个 MCP 服务器可能提供多种工具。您可以在该服务的详情页查看完整的工具列表。在 API 调用时，您可以使用 `allowed_tools` 参数来指定要使用的工具，从而节省时间并获得更符合预期的结果。 > **说明** > > `allowed_tools.tool_names` 数组用于列举需要模型调用的 MCP 工具名。 ```Python "tools": [ { "type": "mcp", "server_label": "mcp_tools", "server_url": "https://mcpserver/mcp", "allowed_tools": { "tool_names": [ "tool1", "tool2" ] } } ] ``` ### 2. 配置鉴权信息 目前部分 MCP 工具需要在 header 中配置身份验证。一般通过 `Authorization` 字段来配置，示例参考如下： > **说明** > > `headers.Authorization` 请替换为 MCP 工具提供方要求的认证信息（如 `Bearer `）。 ```JSON ... "tools": [ { "type": "mcp", "server_label": "info-quest-mcp", "server_url": "https://mcp.infoquest.bytepluses.com/mcp", "require_approval": "never", "headers": { "Authorization": "******" } } ] ... ``` ## 场景示例：多轮调用 **场景**：调用巨量千川 MCP 分析直播数据，需用户确认后执行，支持多轮补充查询。 ```Python from arkruntime import Ark import os api_key = os.getenv('ARK_API_KEY') client = Ark( base_url='https://ark.cn-beijing.volces.com/api/v3', api_key=api_key ) # 1. 首轮请求：发起MCP调用审批 first_response = client.responses.create( model="doubao-seed-2-1-pro-260915", tools=[ { "type": "mcp", "server_label": "qianchuan-mcp", "server_url": "https://mcp.qianchuan.com/mcp", "require_approval": "always" } ], input=[ { "role": "user", "content": [{"type": "input_text", "text": "分析今日直播间竞价推广数据"}] } ], extra_headers={"ark-beta-mcp": "true"}, stream=True ) # 提取审批ID与上一轮响应ID last_chunk = None for chunk in first_response: last_chunk = chunk previous_response_id = last_chunk.response.id approval_id = last_chunk.response.output[-1].id print(f"上一轮响应ID：{previous_response_id}，审批ID：{approval_id}") # 2. 二轮请求：同意审批并继续执行 second_response = client.responses.create( model="doubao-seed-2-1-pro-260915", tools=[ { "type": "mcp", "server_label": "qianchuan-mcp", "server_url": "https://mcp.qianchuan.com/mcp", "require_approval": "always" } ], input=[ { "type": "mcp_approval_response", "approve": True, # 同意审批 "approval_request_id": approval_id } ], extra_headers={"ark-beta-mcp": "true"}, previous_response_id=previous_response_id, # 关联上一轮请求 stream=True ) # 打印二轮响应结果 for chunk in second_response: if hasattr(chunk, 'delta'): print(chunk.delta, end="", flush=True) ``` ## 注意事项 1. 目前云部署 MCP / Remote MCP 仅支持通过 Responses API 调用，同时**只支持通过 Streamable HTTP 链接的 MCP**。 2. **函数命名冲突**：若用户自定义函数与 MCP 内置工具（如 `mcp_call`）重名，由模型自动判断调用优先级，无需额外配置。 3. **默认限流规则**：账号维度默认限流为 `1000 RPM`（每分钟请求数），超出限流将导致请求失败，需调整可提交工单。 4. **错误信息**：暂不支持 `caching` 参数，使用该参数会返回 400 错误信息。 ## 计费说明 消耗模型基础 Tokens，不收取 MCP 工具调用附加费。 ## 相关参考 * [创建 Response](/docs/create-model-responses-api) * [联网搜索工具](/docs/web-search) * [智能体工具商店](https://www.volcengine.com/mcp-marketplace)