# 从 MCP 客户端调用

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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

```text
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agents/{agent_id}/mcp/http
```

## 调用前准备

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


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

## 请求体

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 请求示例

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/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"
  }'
```

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `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 | 否 | 协议元数据。 |

:::
::::
:::::
::::::
:::::::

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 请求示例

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/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"
  }'
```

:::::
:::::{tab-item} 参数说明

::::{tab-set}
:::{tab-item} 路径参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `workspace_id` | string | 是 | RuntimeGrant 对应的工作区 ID。 |
| `agent_id` | string | 是 | 目标智能体 ID。 |

:::
::::
:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "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"
        }
      }
    ]
  }
}
```

:::::
:::::{tab-item} 字段说明

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




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



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

```json
{
  "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"
    }
  }
}
```



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

::::{tab-set}
:::{tab-item} 通用字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `jsonrpc` | string | 固定为 2.0。 |
| `id` | string 或 number 或 null | 与请求中的 JSON-RPC ID 对应。 |

:::
:::{tab-item} 响应数据

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `result.tools` | array of 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 协议元数据；仅在服务端提供时返回。 |
| `result.content` | array of 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 | 调用结果创建时间；存在时返回。 |

:::
::::
:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

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

::::{tab-set}
:::{tab-item} 常见 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。