从 MCP 客户端调用¶

通过指定智能体的 MCP HTTP 入口列出或调用当前任务允许使用的工具。此接口必须使用任务范围的 RuntimeGrant；个人访问令牌不能替代该凭据。

POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/agents/{agent_id}/mcp/http

调用前准备¶

准备与当前运行时任务匹配的 RuntimeGrant，以及路径中的工作区 ID 和智能体 ID。个人访问令牌不能替代 RuntimeGrant。

下方示例使用：

$RUNTIME_GRANT：任务范围的 RuntimeGrant，通过 Authorization: Bearer Header 传递。
$WORKSPACE_ID：RuntimeGrant 对应的工作区 ID，作为路径中的 workspace_id。
$AGENT_ID：目标智能体 ID。

请求头必须提供唯一的 Authorization: Bearer <RUNTIME_GRANT>。JSON-RPC 请求不接受未知顶层字段。

路径参数¶

参数	类型	是否必填	说明
`workspace_id`	string	是	RuntimeGrant 对应的工作区 ID。
`agent_id`	string	是	目标智能体 ID。

请求体¶

参数	类型	是否必填	说明
`jsonrpc`	string	是	固定为 `2.0`。
`id`	string 或 number	否	调用方生成的 JSON-RPC 请求 ID；响应会回显该值。
`method`	string	是	`tools/list` 或 `tools/call`。
`params`	object	否	方法参数。`tools/list` 仅接受省略、`null` 或空对象。
`params.name`	string	`tools/call` 时是	要调用的工具名称。必须使用 `tools/list` 返回的 `name`。
`params.arguments`	object	否	工具输入。
`params.call_id`	string	否	调用方关联本次工具调用的 ID。
`params._meta`	object	否	协议元数据。

请求示例¶

以下示例列出 RuntimeGrant 当前允许调用的工具：

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/mcp/http" \
  -H "Authorization: Bearer $RUNTIME_GRANT" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "<REQUEST_ID>",
    "method": "tools/list"
  }'

调用工具时，将 tools/list 返回的 result.tools[].name 原样传入：

{
  "jsonrpc": "2.0",
  "id": "<REQUEST_ID>",
  "method": "tools/call",
  "params": {
    "name": "<TOOL_NAME>",
    "call_id": "<CALL_ID>",
    "arguments": {
      "value": "<VALUE>"
    }
  }
}

成功响应¶

成功时返回 200 和 JSON-RPC 响应。tools/list 仅返回当前 RuntimeGrant 允许的工具；tools/call 的 structuredContent 是机器可读的调用结果。

{
  "jsonrpc": "2.0",
  "id": "req_01",
  "result": {
    "tools": [
      {
        "id": "tool_01",
        "name": "tool_01",
        "kind": "function",
        "description": "查询销售数据",
        "side_effect_class": "read",
        "input_schema": {
          "type": "object"
        }
      }
    ]
  }
}

响应字段如下。

本文中，字段路径中的 [] 表示数组中的每一项。例如，items[].name 表示 items 数组中每一项的 name 字段。

字段	类型	说明
`jsonrpc`	string	固定为 `2.0`。
`id`	string 或 number 或 null	与请求中的 JSON-RPC ID 对应。
`result.tools`	object（对象数组）	`tools/list` 返回的允许调用的工具。
`result.tools[].id`	string	工具 ID。
`result.tools[].name`	string	可调用的工具名称；调用时必须原样传入 `params.name`。
`result.tools[].kind`	string	工具类型；未设置时不返回。
`result.tools[].description`	string	工具说明；未设置时不返回。
`result.tools[].side_effect_class`	string	工具副作用分类。
`result.tools[].input_schema`	object	输入和输出 JSON Schema；未设置时不返回。
`result.tools[].output_schema`	object	输入和输出 JSON Schema；未设置时不返回。
`result.tools[]._meta`	object	MCP 协议元数据；仅在服务端提供时返回。

tools/call 的成功结果示例如下：

{
  "jsonrpc": "2.0",
  "id": "req_01",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"call_id\":\"call_01\",\"tool_id\":\"tool_01\",\"output\":{}}"
      }
    ],
    "structuredContent": {
      "call_id": "call_01",
      "tool_id": "tool_01",
      "output": {},
      "created_at": "2026-08-18T01:00:00Z"
    }
  }
}

字段	类型	说明
`result.content`	object（对象数组）	面向仅消费文本内容的客户端的结果。
`result.structuredContent`	object	`tools/call` 的机器可读结果。
`result.structuredContent.call_id`	string	工具调用 ID。
`result.structuredContent.tool_id`	string	实际调用的工具 ID。
`result.structuredContent.output`	object	工具输出。
`result.structuredContent.metadata`	object	调用元数据；存在时返回。
`result.structuredContent.artifacts`	array	调用生成的产物；存在时返回。
`result.structuredContent.created_at`	string	调用结果创建时间；存在时返回。

某些可由模型修正的工具错误仍返回 200，并在 result.isError 中标记为 true；请读取 result.content 后修正工具参数。

错误响应¶

MCP 网关错误使用 JSON-RPC error 对象。

{
  "jsonrpc": "2.0",
  "id": "req_01",
  "error": {
    "code": -32602,
    "message": "invalid params"
  }
}

常见 HTTP 错误¶

HTTP 状态码	错误代码	常见原因	建议操作
`400`	`-32700`、`-32600`、`-32601`、`-32602`	请求体无法解析、`jsonrpc` 不是 `2.0`、方法不受支持，或请求参数、工具名称、工具输入无效。	检查 JSON-RPC 请求；`tools/list` 不要传入非空参数。
`401`	`-32001`	RuntimeGrant 缺失、无效、已过期、被拒绝，或与路径中的工作区不匹配。	使用未过期且工作区匹配的 RuntimeGrant。
`401`	`-32003`	调用工具所需的凭据不可用。	检查运行时任务和工具所需的凭据配置。
`413`	`-32600`	请求体超过网关允许大小。	缩小请求体。
`422`	`-32002`	工具不受支持。	先调用 `tools/list`，仅调用返回的工具。
`500`	`-32000`	网关或工具执行出现未分类错误。	记录请求 ID 和错误信息后重试。
`503`	`-32002`	MCP 网关未配置。	稍后重试，或检查运行时部署。

后续操作¶

先调用 tools/list，再调用 tools/call。不要缓存其他 RuntimeGrant 的工具列表或跨任务复用 RuntimeGrant。

最后更新于 2026 年 8 月 22 日