连接 MCP 服务并导入工具¶
MCP 连接保存远程服务地址、传输方式和凭据引用；探测接口读取该服务公布的工具；批量导入接口把选中的远程工具注册为工作区工具。智能体运行时使用的是导入后的工具，不是直接“运行连接”。
开始之前¶
请准备：
Product API Base URL、个人访问令牌和工作区 ID；
可从当前环境访问的 MCP 服务地址；
MCP 服务使用的传输方式和认证方式；
允许列出工具和执行目标工具的最小必要凭据。
只连接受信任的 MCP 服务。探测前确认服务地址使用受支持的安全协议，且不会通过重定向把凭据发送到其他主机。
1. 创建连接¶
下面创建一个使用 HTTP Streaming、无需认证的 MCP 连接。需要认证时，把认证方式和凭据放入对应字段，不要把密钥拼到 URL 中。
curl -X POST \
"$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/connections" \
-H "X-API-Key: $PRODUCT_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"name": "support-mcp",
"description": "Tools provided by the support service.",
"status": "active",
"kind": "mcp_server",
"endpoint_uri": "<MCP_HTTPS_ENDPOINT>",
"auth_type": "none",
"visibility": "workspace",
"config": {
"transport": "http-streaming"
}
}'
保存响应中的 data.id。凭据由服务端保存为引用；后续读取连接时不应期待返回明文凭据。
2. 探测 MCP 服务¶
使用连接 ID 探测服务：
curl -X POST \
"$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/connections/actions/probe-mcp" \
-H "X-API-Key: $PRODUCT_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"connection_id": "<CONNECTION_ID>"
}'
成功响应中的 tool_count 和 tools 反映本次探测发现的能力。检查每个工具的远程名称、描述、inputSchema 和 outputSchema。探测成功不会自动导入工具，也不能证明每个工具调用都一定成功。
3. 选择并导入工具¶
只导入业务确实需要的工具。下面把探测到的 get_ticket 注册为工作区工具：
curl -X POST \
"$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/connections/actions/batch-create-mcp-tools" \
-H "X-API-Key: $PRODUCT_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"connection_id": "<CONNECTION_ID>",
"visibility": "workspace",
"items": [
{
"tool_name": "get_ticket",
"name": "get-ticket",
"description": "Read one support ticket by ID.",
"input_schema": {
"type": "object",
"properties": {
"ticket_id": {"type": "string"}
},
"required": ["ticket_id"]
},
"category": "support",
"tags": ["ticket", "read"]
}
]
}'
逐项检查响应中的 status：
created：已创建工作区工具，保存返回的工具 ID；existing：已存在对应工具，使用返回的工具资源继续检查；failed：本项导入失败，读取该项的错误，不要假定其他项也失败。
4. 验证导入结果¶
读取导入后的工具详情，确认来源指向正确连接，Schema 与探测结果一致，并检查 bindable、凭据和运行时支持。随后把工具绑定到技能或智能体，使用只读或低风险输入进行验证。
远程 MCP 服务的工具定义发生变化时，重新探测并对比 Schema，再决定是否更新工作区工具。不要在未评估兼容性时覆盖正在使用的输入输出契约。
常见问题¶
现象 |
先检查 |
下一步 |
|---|---|---|
无法建立连接 |
服务地址、网络、TLS、传输方式 |
从当前运行环境确认地址可达，再检查服务日志。 |
探测返回认证错误 |
|
更新连接凭据后重新探测。 |
探测成功但没有工具 |
远程服务是否公布工具、当前身份权限 |
使用同一身份在 MCP 服务端检查工具列表。 |
导入后不可绑定 |
工具详情中的可绑定原因和运行时 |
补齐配置，或换用受支持的工具和运行时。 |