<span id="调用任务mcp-app工具"></span>

# Call a task MCP App tool

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

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.

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

<span id="调用前准备"></span>

## 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](scope-and-results.md).

<span id="请求参数"></span>

## Request parameters

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

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

:::::
:::::{tab-item} Parameters

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

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

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} Fields

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

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

<span id="错误响应"></span>

## 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](../../../../developer/cli/tasks/runtime-knowledge.md) for recovery/environment states.
