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.

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:

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:

{
  "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.

{
  "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:

{
  "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.

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

Common HTTP errors

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.

Last updated on Sep 3, 2026