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 |
|---|---|---|---|---|
|
Queries |
string |
Yes |
Agent ID corresponding to the link. |
|
Queries |
string |
Yes |
Current valid publication token. For short-code links, resolve first and use the short code as t. |
|
Queries |
string |
Yes |
Visitor session credentials under the same publication. |
|
Body |
string |
Yes |
This visitor’s conversation ID. |
|
Body |
string |
Yes |
Task ID within that conversation. |
|
Body |
string |
Condition |
Tool identifier within the task; see shared objects for tool-name selection rules. |
|
Body |
string |
Condition |
When present, binds by an app-visible tool name within the task. |
|
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.