---
title: "Execute Mcp Tool"
method: POST
path: "/v1/mcp/execute"
tags: ["mcp"]
---

# Execute Mcp Tool

`POST /v1/mcp/execute`

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.

## Request body

- McpExecuteRequest — One stored server, and the exact call the application authorized. No inline server fields (R-REQ-4): a caller registers a remote MCP server through the control plane once and refers to it by id afterwards, which keeps URLs, credentials, revocation and allowlist policy on Otari's side of the boundary instead of in every request. Extras are forbidden rather than ignored, so a caller still sending the old inline ``server`` block is told its configuration was not used instead of watching Otari quietly execute against a different server than the one it named.
  - `arguments` object — The exact caller-authorized JSON-object arguments.
  - `client_execution_id` string, 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_id` string, uuid, required — The stored MCP server to execute against.
  - `server_revision` string, 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_name` string, required — The remote MCP tool name the caller authorized for this one execution.

## Response `200`

Successful Response

- CallToolResult — The server's response to a tool call.
  - `_meta` object, nullable
  - `content` union[], required
    - union
      - TextContent — Text content for a message.
        - `_meta` object, nullable
        - `annotations` Annotations
          - `audience` string[], nullable
          - `priority` number, nullable
        - `text` string, required
        - `type` 'text', required
      - ImageContent — Image content for a message.
        - `_meta` object, nullable
        - `annotations` Annotations
          - `audience` string[], nullable
          - `priority` number, nullable
        - `data` string, required
        - `mimeType` string, required
        - `type` 'image', required
      - AudioContent — Audio content for a message.
        - `_meta` object, nullable
        - `annotations` Annotations
          - `audience` string[], nullable
          - `priority` number, nullable
        - `data` string, required
        - `mimeType` string, required
        - `type` 'audio', required
      - ResourceLink — A resource that the server is capable of reading, included in a prompt or tool call result. Note: resource links returned by tools are not guaranteed to appear in the results of `resources/list` requests.
        - `_meta` object, nullable
        - `annotations` Annotations
          - `audience` string[], nullable
          - `priority` number, nullable
        - `description` string, nullable
        - `icons` Icon[], nullable
          - `mimeType` string, nullable
          - `sizes` string[], nullable
          - `src` string, required
        - `mimeType` string, nullable
        - `name` string, required
        - `size` integer, nullable
        - `title` string, nullable
        - `type` 'resource_link', required
        - `uri` string, uri, required
      - EmbeddedResource — The contents of a resource, embedded into a prompt or tool call result. It is up to the client how best to render embedded resources for the benefit of the LLM and/or the user.
        - `_meta` object, nullable
        - `annotations` Annotations
          - `audience` string[], nullable
          - `priority` number, nullable
        - `resource` union, required
          - TextResourceContents — Text contents of a resource.
            - `_meta` object, nullable
            - `mimeType` string, nullable
            - `text` string, required
            - `uri` string, uri, required
          - BlobResourceContents — Binary contents of a resource.
            - `_meta` object, nullable
            - `blob` string, required
            - `mimeType` string, nullable
            - `uri` string, uri, required
        - `type` 'resource', required
  - `isError` boolean
  - `structuredContent` object, nullable

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Payment Required
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `422` — Unprocessable Content
- `429` — Too Many Requests
- `500` — Internal Server Error
- `502` — Bad Gateway
- `503` — Service Unavailable
- `504` — Gateway Timeout

## Changes

- **2026-09-10** `80c117c36f36` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/mozilla-ai/apis/otari/changes/v1/mcp/execute/post.md)

---

[API](https://skmtc.dev/mozilla-ai/apis/otari.md) · [All operations](https://skmtc.dev/mozilla-ai/apis/otari/llms.txt) · [OpenAPI document](https://skmtc.dev/mozilla-ai/apis/otari/revisions/80c117c36f36?raw)