探测 MCP 连接¶

探测 MCP 服务并返回可发现的工具。探测不会保存连接。

POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/connections/actions/probe-mcp

调用前准备¶

准备可访问目标工作区的个人访问令牌和目标工作区 ID。

请求体¶

输入示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/connections/actions/probe-mcp" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "endpoint_uri": "https://mcp.example.com",
    "transport": "http-streaming"
  }'

参数说明

字段	类型	是否必填	说明
`endpoint_uri`	string	否	要探测的 MCP 服务地址。未提供 connection_id 时必须提供。
`connection_id`	string	否	已保存的连接 ID。未提供 endpoint_uri 时必须提供。
`auth_type`	string	否	认证类型。
`api_key_header`	string	否	API Key 使用的请求头名称。
`credential`	object	否	探测时使用的凭据，可包含 bearer_token、api_key、basic_username、basic_password 或 custom_headers。
`transport`	string	否	MCP 传输方式：`sse` 或 `http-streaming`。省略时优先使用已有连接配置。没有已有配置时使用 `http-streaming`。

指定已保存的连接时，省略的传输方式和认证配置会继承该连接的配置。只有没有可继承配置时，才采用新连接的默认传输方式。

指定 connection_id 时，服务会读取对应 MCP 连接。省略地址或传输方式时沿用已存配置。没有显式提交凭据时，可沿用该连接的已存凭据。私有连接须属于当前调用者。使用已存凭据探测不同来源的地址时会被拒绝，需显式提供新凭据。

成功响应¶

响应示例

{
  "code": 0,
  "data": {
    "tool_count": 0,
    "tools": []
  }
}

字段说明

字段	类型	说明
`code`	integer	请求处理成功时为 `0`。
`data`	object	响应数据。
`data.tool_count`	integer	发现的工具数量。
`data.tools`	object（对象数组）	MCP 服务返回的工具。
`data.tools[].name`	string	名称。
`data.tools[].title`	string	展示标题。未设置时可省略。
`data.tools[].description`	string	说明。未设置时可省略。
`data.tools[].inputSchema`	object	上游工具的输入 JSON Schema。
`data.tools[].outputSchema`	object	上游工具的输出 JSON Schema。未设置时可省略。
`data.tools[].annotations`	object	扩展注解。未设置时可省略。
`data.tools[].icons`	object（对象数组）	上游工具图标信息。未设置时可省略。
`data.tools[]._meta`	object	上游工具扩展信息。未设置时可省略。
`data.protocol_version`	string	MCP 协议版本。未提供时不返回。未设置时可省略。

错误响应¶

响应示例

{
  "code": 2,
  "message": "invalid request body"
}

字段说明

字段	类型	说明
`code`	integer	错误代码。
`message`	string	面向调用者的错误信息。
`details.reason`	string	错误分类：INVALID_BODY、INVALID_ENDPOINT、HOST_NOT_ALLOWED、INVALID_TRANSPORT、AUTH_FAILED、TIMEOUT、INITIALIZE_FAILED、TLS_ERROR、PROTOCOL_ERROR、TOOLS_LIST_FAILED 或 UPSTREAM_ERROR。

最后更新于 2026 年 10 月 19 日