---
title: "Execute MCP tool"
method: POST
path: "/v1/mcp/tool/execute"
tags: ["MCP"]
---

# Execute MCP tool

`POST /v1/mcp/tool/execute`

Executes an MCP tool and returns the result.

## Query parameters

- `format` 'chat' | 'responses'

## Request body

- union — MCP tool execution request. The schema depends on the `format` query parameter: - `format=chat` or empty (default): Use `ChatAssistantMessageToolCall` schema - `format=responses`: Use `ResponsesToolMessage` schema
  - object — Chat format - uses ChatAssistantMessageToolCall schema
    - `index` integer
    - `type` string
    - `id` string
    - `function` object, required
      - `name` string
      - `arguments` string
  - object — Responses format - uses ResponsesToolMessage schema
    - `call_id` string — Common call ID for tool calls and outputs
    - `name` string, required — Tool function name (required for execution)
    - `arguments` string — Tool function arguments as JSON string
    - `output` object — Tool execution output
    - `action` object — Tool action configuration
    - `error` string — Error message if tool execution failed

## Response `200`

Tool executed successfully

- union — MCP tool execution response.
  - ChatMessage
    - `role` 'assistant' | 'user' | 'system' | 'tool' | 'developer', required
    - `name` string
    - `content` union — Message content - can be a string or array of content blocks
      - string
      - object[]
        - `type` 'text' | 'image_url' | 'input_audio' | 'file' | 'refusal', required
        - `text` string
        - `refusal` string
        - `image_url` object
          - `url` string, required
          - `detail` 'low' | 'high' | 'auto'
        - `input_audio` object
          - `data` string, required
          - `format` string
        - `file` object
          - `file_data` string
          - `file_id` string
          - `filename` string
          - `file_type` string
        - `cache_control` CacheControl — Cache control settings for content blocks
          - `type` 'ephemeral'
          - `ttl` string — Time to live (e.g., "1m", "1h")
    - `tool_call_id` string — For tool messages
    - `refusal` string
    - `audio` object
      - `id` string
      - `data` string
      - `expires_at` integer
      - `transcript` string
    - `reasoning` string
    - `reasoning_details` object[]
      - `id` string
      - `index` integer
      - `type` 'reasoning.summary' | 'reasoning.encrypted' | 'reasoning.text'
      - `summary` string
      - `text` string
      - `signature` string
      - `data` string
    - `annotations` object[]
      - `type` string
      - `url_citation` object
        - `start_index` integer
        - `end_index` integer
        - `title` string
        - `url` string
        - `sources` object
        - `type` string
    - `tool_calls` object[]
      - `index` integer
      - `type` string
      - `id` string
      - `function` object, required
        - `name` string
        - `arguments` string
  - object — Responses format response
    - `id` string
    - `type` 'message' | 'file_search_call' | 'computer_call' | 'computer_call_output' | 'web_search_call' | 'web_fetch_call' | 'function_call' | 'function_call_output' | 'code_interpreter_call' | 'local_shell_call' | 'local_shell_call_output' | 'mcp_call' | 'custom_tool_call' | 'custom_tool_call_output' | 'image_generation_call' | 'mcp_list_tools' | 'mcp_approval_request' | 'mcp_approval_responses' | 'reasoning' | 'item_reference' | 'refusal'
    - `status` 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed'
    - `role` 'assistant' | 'user' | 'system' | 'developer'
    - `content` union
      - string
      - object[]
        - `type` 'input_text' | 'input_image' | 'input_file' | 'input_audio' | 'output_text' | 'refusal' | 'reasoning_text', required
        - `file_id` string
        - `text` string
        - `signature` string
        - `image_url` string
        - `detail` string
        - `file_data` string
        - `file_url` string
        - `filename` string
        - `file_type` string
        - `input_audio` object
          - `format` 'mp3' | 'wav', required
          - `data` string, required
        - `annotations` object[]
          - `type` 'file_citation' | 'url_citation' | 'container_file_citation' | 'file_path'
          - `index` integer
          - `file_id` string
          - `text` string
          - `start_index` integer
          - `end_index` integer
          - `filename` string
          - `title` string
          - `url` string
          - `container_id` string
        - `logprobs` object[]
          - `bytes` integer[]
          - `logprob` number
          - `token` string
          - `top_logprobs` object[]
            - `bytes` integer[]
            - `logprob` number
            - `token` string
        - `refusal` string
        - `cache_control` CacheControl — Cache control settings for content blocks
          - `type` 'ephemeral'
          - `ttl` string — Time to live (e.g., "1m", "1h")
    - `call_id` string
    - `name` string
    - `arguments` string
    - `output` union — Tool call output. A plain string for function/custom/local-shell tool outputs, an array of content blocks for structured function tool outputs, or a computer-tool screenshot object for computer_call_output.
      - string
      - object[]
        - `type` 'input_text' | 'input_image' | 'input_file' | 'input_audio' | 'output_text' | 'refusal' | 'reasoning_text', required
        - `file_id` string
        - `text` string
        - `signature` string
        - `image_url` string
        - `detail` string
        - `file_data` string
        - `file_url` string
        - `filename` string
        - `file_type` string
        - `input_audio` object
          - `format` 'mp3' | 'wav', required
          - `data` string, required
        - `annotations` object[]
          - `type` 'file_citation' | 'url_citation' | 'container_file_citation' | 'file_path'
          - `index` integer
          - `file_id` string
          - `text` string
          - `start_index` integer
          - `end_index` integer
          - `filename` string
          - `title` string
          - `url` string
          - `container_id` string
        - `logprobs` object[]
          - `bytes` integer[]
          - `logprob` number
          - `token` string
          - `top_logprobs` object[]
            - `bytes` integer[]
            - `logprob` number
            - `token` string
        - `refusal` string
        - `cache_control` CacheControl — Cache control settings for content blocks
          - `type` 'ephemeral'
          - `ttl` string — Time to live (e.g., "1m", "1h")
      - object — Computer tool call output (computer_screenshot).
        - `type` 'computer_screenshot'
        - `file_id` string
        - `image_url` string
    - `action` object
    - `error` string
    - `queries` string[]
    - `results` object[]
    - `summary` object[]
      - `type` 'summary_text', required
      - `text` string, required
    - `encrypted_content` string

## Other responses

- `400` — Bad request
- `500` — Internal server error

---

[API](https://skmtc.net/getbifrost/apis/bifrost-api.md) · [All operations](https://skmtc.net/getbifrost/apis/bifrost-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getbifrost/bifrost-api/versions/f8cab88f64ea/schema)