mcp

Execute Mcp Tool

Changed on

Execute one caller-authorized tool call against a stored MCP server.

The calling application owns any user approval, argument editing, cancellation and action history; Otari executes exactly the tool name and arguments it is given, once, and returns the remote server's native result. A result with isError: true is a definitive outcome and comes back as an HTTP 200.

This request must never be retried automatically. client_execution_id is correlation, not idempotency: once the call has been dispatched Otari cannot know whether the tool ran, and an outcome_unknown response means exactly that. Proxies, service meshes and SDKs on this path have to disable retries for it, including on connection resets and 5xx responses.

post/api/v1/mcp/execute

Request

  • The document declares no server URL.
  • Auth: one of:
    • API key in header Otari-Key
    • API key in header x-api-key

Request body

argumentsobject

The exact caller-authorized JSON-object arguments.

client_execution_idstring uuid required

A caller-generated UUID, for correlation only. It is not proof of approval and not an idempotency key: repeating a request with the same value may execute the tool again, so this request must never be retried automatically.

mcp_server_idstring uuid required

The stored MCP server to execute against.

server_revisionstring required

The stored-server revision returned by tool discovery. Required, and compared against the current one so a configuration change since the caller authorized this call is refused rather than executed. Not an approval credential.

tool_namestring required

The remote MCP tool name the caller authorized for this one execution.

Response

Successful Response

_metaobject nullable
isErrorboolean
structuredContentobject nullable

Changes