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
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
- Gateway
- Go SDK
Step 1: Send Chat Request
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:Step 3: Continue the Conversation
Assemble the full conversation history and continue:Response Formats
Bifrost supports two API formats for tool execution:Chat Format (Default)
Use?format=chat or omit the parameter:
Responses Format
Use?format=responses for the Responses API format:
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:
[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:- Sequential
- Parallel
Error Handling
Tool execution can fail for various reasons: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 a2026-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.
- 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.
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:- Correct
rolefield ("tool") - Matching
tool_call_idfor correlation - Properly formatted
content
Next Steps
Agent Mode
Enable autonomous tool execution with auto-approval
Tool Filtering
Control which tools are available per request

