Call an MCP App tool for a visitor task

HTTP200/code0 still requires checking data.is_error. content and optional structured_content are tool results. Execute only app tools allowed by the task manifest; a visitor session is not arbitrary MCP connection credentials.

POST https://api.moi.matrixorigin.cn/v5/public/webapp/mcp-apps/call

Before you call this API

Set BASE_URL to the product API prefix https://api.moi.matrixorigin.cn/v5. For private deployments, use the corresponding product API URL.

Prepare links and visitor identity in the same environment. Do not supply a product PAT or Workspace request header.

Request

curl --request POST \
  "$BASE_URL/public/webapp/mcp-apps/call?webapp=$AGENT_ID&t=$WEBAPP_TOKEN&s=$WEBAPP_SESSION" \
  --header "Content-Type: application/json" \
  --data @- <<JSON
{"conversation_id": "${CONVERSATION_ID}", "task_id": "$TASK_ID", "tool_name": "example_tool", "arguments": {}}
JSON

Parameter

Location

Type

Required

Description

webapp

Queries

string

Yes

Agent ID corresponding to the link.

t

Queries

string

Yes

Current valid publication token. For short-code links, resolve first and use the short code as t.

s

Queries

string

Yes

Visitor session credentials under the same publication.

conversation_id

Body

string

Yes

This visitor’s conversation ID.

task_id

Body

string

Yes

Task ID within that conversation.

tool_id

Body

string

Condition

Tool identifier within the task; see shared objects for tool-name selection rules.

tool_name

Body

string

Condition

When present, binds by an app-visible tool name within the task.

arguments

Body

JSON

No

Tool arguments must still satisfy its schema; the example uses an object.

Successful response

{
  "code": 0,
  "data": {
    "content": [],
    "is_error": false
  }
}

Success returns HTTP 200 with numeric code=0. Read data’s Object descriptions with the example; the conversation-creation example shows a field excerpt only.

Error responses

Public errors and identity handling distinguishes unavailable links, disablement, invalid sessions, parameters, and system failures.

Last updated on