# Called from MCP client

List or call the tools allowed for the current task through the MCP HTTP entry of the specified agent. This interface must use a task-scoped RuntimeGrant; a personal access token cannot replace this credential.

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

## Preparation before calling

Prepare a RuntimeGrant that matches the current runtime task, along with the workspace ID and agent ID in the path. Personal access tokens are not a replacement for RuntimeGrant.

The example below uses:

- `$RUNTIME_GRANT`: Task-scoped RuntimeGrant, passed through the `Authorization: Bearer` Header.
- `$WORKSPACE_ID`: The workspace ID corresponding to the RuntimeGrant, as `workspace_id` in the path.
- `$AGENT_ID`: target agent ID.

The request header must provide the unique `Authorization: Bearer <RUNTIME_GRANT>`. JSON-RPC requests do not accept unknown top-level fields.

## Request example

The following example lists the tools currently allowed to be called by a RuntimeGrant:

```bash
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"
  }'
```

When calling the tool, pass in the `result.tools[].name` returned by `tools/list` as it is:

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

## Path parameters

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `workspace_id` | string | Yes | The workspace ID corresponding to the RuntimeGrant. |
| `agent_id` | string | Yes | Target agent ID. |

## Request body

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `jsonrpc` | string | Yes | Fixed to `2.0`. |
| `id` | string or number | No | The JSON-RPC request ID generated by the caller; the response echoes this value. |
| `method` | string | Yes | `tools/list` or `tools/call`. |
| `params` | object | No | Method parameters. `tools/list` only accepts omission, `null`, or an empty object. |
| `params.name` | string | Required for `tools/call` | Name of the tool to call. Use the `name` returned by `tools/list`. |
| `params.arguments` | object | No | Tool input. |
| `params.call_id` | string | No | The ID associated with this tool call by the caller. |
| `params._meta` | object | No | Protocol metadata. |

## Successful response

Returns `200` and a JSON-RPC response on success. `tools/list` returns only tools allowed by the current RuntimeGrant; `structuredContent` for `tools/call` is the machine-readable result of the call.

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

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `jsonrpc` | string | Fixed to `2.0`. |
| `id` | string or number or null | Corresponds to the JSON-RPC ID in the request. |
| `result.tools` | object[] | `tools/list` Returns the tool that is allowed to be called. |
| `result.tools[].id` | string | Tool ID. |
| `result.tools[].name` | string | The name of the callable tool; `params.name` must be passed in as it is when calling. |
| `result.tools[].kind` | string | Tool type; does not return if not set. |
| `result.tools[].description` | string | Tool description; does not return if not set. |
| `result.tools[].side_effect_class` | string | Tool side effect classification. |
| `result.tools[].input_schema` | object | Input and output JSON Schema; does not return if not set. |
| `result.tools[].output_schema` | object | Input and output JSON Schema; does not return if not set. |
| `result.tools[]._meta` | object | MCP protocol metadata; only returned when provided by the server. |

`[]` after a type denotes an array. `[]` in a field path denotes each item in an array.

Examples of successful results for `tools/call` are as follows:

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

| Field | Type | Description |
| --- | --- | --- |
| `result.content` | object[] | Results for clients that only consume text content. |
| `result.structuredContent` | object | Machine-readable result of `tools/call`. |
| `result.structuredContent.call_id` | string | Tool call ID. |
| `result.structuredContent.tool_id` | string | The tool ID actually called. |
| `result.structuredContent.output` | object | Tool output. |
| `result.structuredContent.metadata` | object | Call metadata; returned if exists. |
| `result.structuredContent.artifacts` | array | The product generated by the call; returned if exists. |
| `result.structuredContent.created_at` | string | The creation time of the call result; returned if it exists. |

Some tool errors that can be corrected by the model still return `200` and are marked as `true` in `result.isError`; please read `result.content` and correct the tool parameters.

## Error response

MCP gateway error using JSON-RPC `error` object.

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

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `-32700`、`-32600`、`-32601`、`-32602`
  - The request body cannot be parsed, `jsonrpc` is not `2.0`, the method is not supported, or the request parameters, tool name, or tool input are invalid.
  - Check JSON-RPC requests; `tools/list` do not pass in non-null parameters.
* - `401`
  - `-32001`
  - The RuntimeGrant is missing, invalid, expired, rejected, or does not match the workspace in the path.
  - Use an unexpired RuntimeGrant with a matching workspace.
* - `401`
  - `-32003`
  - The credentials required to call the tool are not available.
  - Check the configuration of credentials required by runtime tasks and tools.
* - `413`
  - `-32600`
  - The request body exceeds the gateway allowed size.
  - Reduce the request body.
* - `422`
  - `-32002`
  - Tool is not supported.
  - Call `tools/list` first, calling only the returned tool.
* - `500`
  - `-32000`
  - An unclassified error occurred in gateway or tool execution.
  - Record the request ID and error message and try again.
* - `503`
  - `-32002`
  - MCP gateway not configured.
  - Try again later, or check for runtime deployment.
```

## Follow-up operations

Call `tools/list` first, then `tools/call`. Do not cache tool lists for other RuntimeGrants or reuse RuntimeGrants across tasks.