Call a task MCP App tool

Call a tool the application is allowed to access in the original task. This may cause business side effects. Also check is_error in the result.

POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agent-runtime-tasks/{task_id}/mcp-apps/call

Before you call this API

Prepare a personal access token, workspace ID, and runtime task that returned an application descriptor in the current environment. Use original-task tool IDs, application resource URIs, or tool names. Current identity still needs agent-use and corresponding connection/service privileges. See Task scope and results.

Request parameters

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agent-runtime-tasks/$TASK_ID/mcp-apps/call" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  --data '{"tool_name":"weather","arguments":{"city":"杭州"}}'

Parameter

Type

Required

Description

workspace_id

string

Yes

Workspace ID in the current environment, matching X-Workspace-ID.

task_id

string

Yes

Agent runtime task ID owning the application.

X-Workspace-ID

string

Yes

Request workspace.

X-API-Key

string

Yes

Personal access token in the current environment.

tool_id

string

At least one of tool_id/tool_name

Original task tool ID; used when tool_name is absent.

tool_name

string

At least one of tool_name/tool_id

Application tool name. Name matching takes precedence when both are provided.

arguments

JSON value

Per tool schema

Call arguments; object in the example. Omitted/null does not satisfy tool input requirements automatically.

Successful response

{
  "code": 0,
  "data": {
    "content": [
      {
        "type": "text",
        "text": "示例结果"
      }
    ],
    "structured_content": {
      "city": "杭州"
    },
    "is_error": false
  }
}

Field

Type

Description

code

integer

0 on success.

data.content

JSON value (array) or null

Tool-returned content blocks; read according to content type.

data.structured_content

JSON value

Optional structured result; snake_case, distinct from upstream structuredContent.

data.is_error

boolean

Whether the tool reports execution failure. Check even for HTTP 200.

Error response

HTTP / code

Conditions and recovery

400 / 2

Invalid JSON, fields, URI, or selector.

403 / 5

Current agent-use or corresponding privileges denied.

404 / 3

Task outside current scope or tool/URI unbound.

409 / 2

Task failed, canceled, or rejected; application operations cannot continue.

503 / 15

Runtime/provider unavailable.

500 / 1

Unclassified internal/persistence failure with localized general message.

Errors use localized message; authentication may return string code/msg. See In-Task Knowledge Retrieval for recovery/environment states.

Last updated on