Execute an MCP tool

POST 
/api/v1/llm/mcp-call-tool

Invokes an MCP tool directly, outside a conversation flow. Use it to test a tool without starting a generation run.

The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.

Use this in a guide: Check a chat integration before customers use it · Build an assistant that researches the web

Request

Responses

200

Tool executed

Call a tool discovered through mcpListTools; replace the server, tool name and arguments with that tool’s schema.

Section ID: DOC-MA-conversations-api-mcpCallTool#example-conversations-mcpCallTool-request

Request example

{
  "toolCall": {
    "id": "tool_call_123",
    "serverId": "custom:product-tools",
    "name": "lookup_booking",
    "argumentsJson": {
      "booking_id": "BK-123"
    }
  }
}

Illustrative response shape; omitted default fields and actual outcomes depend on the operation.

Section ID: DOC-MA-conversations-api-mcpCallTool#example-conversations-mcpCallTool-response

Response example

{
  "requestId": "example_123",
  "toolCall": {
    "id": "example_123",
    "name": "example",
    "argumentsJson": {
      "example": "value"
    },
    "status": "TOOL_EXECUTION_STATUS_PENDING",
    "resultJson": {
      "example": "value"
    },
    "executedAt": "2026-09-16T12:00:00Z",
    "serverId": "example_123",
    "isClientTool": true,
    "description": "example",
    "parametersJsonSchema": {
      "example": "value"
    },
    "requiresApprovalAt": "2026-09-16T12:00:00Z",
    "approvedAt": "2026-09-16T12:00:00Z",
    "approvedBy": "example",
    "executionDuration": "1s",
    "endReason": "example",
    "clientToolDeadlineAt": "2026-09-16T12:00:00Z"
  },
  "executionTimeMs": 1
}

Document ID: DOC-MA-conversations-api-mcpCallTool. Section identities and revisions.

Section	Stable reference
Execute an MCP tool	DOC-MA-conversations-api-mcpCallTool#overview
Request	DOC-MA-conversations-api-mcpCallTool#request
Responses	DOC-MA-conversations-api-mcpCallTool#responses