Skip to main content

Overview

When an LLM returns tool calls in its response, Bifrost does not automatically execute them. Instead, your application explicitly calls the tool execution API, giving you full control over:
  • Which tool calls to execute
  • User approval workflows
  • Security validation
  • Audit logging
The basic flow is: Chat Request → Review Tool Calls → Execute Tools → Continue Conversation. For detailed architecture diagrams, see the MCP Architecture documentation.

Authentication

The /v1/mcp/tool/execute endpoint uses the same authentication as other inference endpoints like /v1/chat/completions: Virtual keys and authentication are independent layers that work together. For details on how to use virtual keys with authentication, see Authentication and Virtual Keys.

End-to-End Example

Step 1: Send Chat Request

Response with tool calls:
Tool names are prefixed with the MCP client name (e.g., filesystem_list_directory). This ensures uniqueness across multiple MCP clients.

Step 2: Execute the Tool

The request body matches the tool call object from the response:
Tool result response:

Step 3: Continue the Conversation

Assemble the full conversation history and continue:
Final response:

Response Formats

Bifrost supports two API formats for tool execution:

Chat Format (Default)

Use ?format=chat or omit the parameter:
Request:
Response:

Responses Format

Use ?format=responses for the Responses API format:
Request:
Response:

Images, audio and files

A tool that returns only text comes back as a single string, as shown above. When it also returns images, audio or files, content is a list of blocks instead:
A tool that returns only structured data comes back as that data, as JSON text. When the result is sent on to a model, Anthropic, Bedrock and Responses API models receive the images themselves (Responses API models receive files too). Models from other providers cannot take media in a tool result, so they receive a short note naming what the tool returned, such as [image/png, 34 KB returned by the tool, not shown]. Clients of Bifrost’s MCP server receive each tool’s result as the upstream server returned it, images, structured data and errors included, unless a plugin such as guardrails changed it.

Multiple Tool Calls

LLMs often request multiple tools in a single response. Execute them in sequence or parallel:

Error Handling

Tool execution can fail for various reasons:
Gateway error responses:

Tools that ask for input

Some MCP servers stop mid-call to ask for something: a question for the user (elicitation), a model completion (sampling), or the client’s filesystem roots. Bifrost does not support these requests. It does not declare them to servers, and it cannot pass them to the MCP client or model that made the call. A tool that needs one fails. On a 2026-07-28 connection, the error names the server and what it asked for, and Bifrost does not retry the call. This applies to every path, including MCP clients connected through Bifrost’s gateway, even if the client could answer the request itself. If the server needs a step completed in the browser, such as connecting an account, the error includes the step and its URL. Complete it and call the tool again. To use such a tool, connect the MCP client directly to the server.

Auth failure recovery

Inline auth-failure retry is available in Bifrost v2.0.0 and above.
When a tool call reaches the upstream MCP server but comes back with a clean auth rejection (401/403), Bifrost reacts on the spot instead of waiting for the health monitor:
  • Per-user clients (per_user_oauth, per_user_headers, token_exchange): Bifrost force-refreshes the caller’s credential (refreshes the per-user OAuth token, or discards the exchanged token and exchanges again), re-acquires a connection, and retries the same call inline, exactly once. If the retry succeeds, the caller just sees a normal success. Per-user header values have nothing to refresh; a rejected value needs a new submission.
  • Shared clients (oauth, headers): Bifrost immediately force-refreshes the credential and starts reconnecting in the background. The failing call waits briefly for that reconnect (capped by its own deadline) and retries once on the healed connection; the caller usually sees a normal success. If the reconnect doesn’t finish in time, the original error surfaces and later calls succeed once the background reconnect completes.
  • Safety opt-out: a tool that is not read-only and is destructive and not idempotent is never retried. A tool with no annotations counts as destructive and not idempotent, matching the MCP spec defaults. The original error always surfaces so a side effect cannot run twice. Bifrost still refreshes a per-user client’s credential, or reconnects a shared client, in the background, so later calls use a fresh credential once that succeeds.
This applies to POST /v1/mcp/tool/execute, Agent Mode tool calls, and tool calls over the MCP Gateway alike.

Copy-Pastable Responses

Tool execution responses are designed to be directly appended to your conversation history:
The response includes:
  • Correct role field ("tool")
  • Matching tool_call_id for correlation
  • Properly formatted content

Next Steps

Agent Mode

Enable autonomous tool execution with auto-approval

Tool Filtering

Control which tools are available per request