Overview

​

What is MCP?

• MCP Client: Connect to any MCP-compatible server (filesystem tools, web search, databases, etc.)
• MCP Server: Expose your connected tools to external MCP clients (like Claude Desktop)
• Agent Mode: Autonomous tool execution with configurable auto-approval
• Code Mode: Let AI write and execute Python to orchestrate multiple tools

​

Security-First Design

​

Key Capabilities

​

How MCP Works in Bifrost

​

Basic Tool Calling Flow

1. POST /v1/chat/completions
   → LLM returns tool call suggestions (NOT executed)

2. Your app reviews the tool calls
   → Apply security rules, get user approval if needed

3. POST /v1/mcp/tool/execute
   → Execute approved tool calls explicitly

4. POST /v1/chat/completions
   → Continue conversation with tool results

• No unintended API calls to external services
• No accidental data modification or deletion
• Full audit trail of all tool operations
• Human oversight for sensitive operations

​

Why Code Mode Matters

​

Bifrost as an MCP Gateway

• Connect Bifrost to multiple MCP servers (filesystem, web search, databases, etc.)
• Expose all those tools through a single MCP endpoint
• External clients connect to Bifrost and get access to all aggregated tools

​

Server Instructions

<mcp_server name="github">
Always call get_me first to understand current user permissions.
</mcp_server>

<mcp_server name="deepwiki">
DeepWiki MCP provides AI-powered documentation…
</mcp_server>

curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0.0.1"}}}' \
  | jq -r '.result.instructions // "«none»"'

​

Endpoints

​

POST /mcp (JSON-RPC)

# List available tools
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Call a tool
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "filesystem_read_file",
      "arguments": {
        "path": "/tmp/test.txt"
      }
    }
  }'

​

GET /mcp (SSE)

curl -N http://localhost:8080/mcp \
  -H "Accept: text/event-stream"

• connection/opened message on connect
• Keeps connection alive until client disconnects

​

External MCP Client Integration

• Claude Desktop - macOS and Windows desktop application
• Cursor - IDE with MCP support
• Custom Applications - Any app implementing the MCP protocol
• Browser Extensions - Tools with MCP client capability

http://your-bifrost-gateway/mcp

​

Virtual Key Authentication

​

Anonymous Access (No Credentials)

​

Scoped by Virtual Key

# Via x-bf-vk header
curl -X POST http://localhost:8080/mcp \
  -H "x-bf-vk: vk_your_virtual_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

# Via Authorization header
curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer vk_your_virtual_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

# Via X-Api-Key header
curl -X POST http://localhost:8080/mcp \
  -H "X-Api-Key: vk_your_virtual_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

# Via x-goog-api-key header
curl -X POST http://localhost:8080/mcp \
  -H "x-goog-api-key: vk_your_virtual_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

{
  "mcpServers": {
    "bifrost-production": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer vk_your_production_key"
      }
    },
    "bifrost-development": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer vk_your_development_key"
      }
    }
  }
}

​

Tool Filtering for MCP Clients

​

Per-Virtual Key Tool Access

{
  "governance": {
    "virtual_keys": [
      {
        "name": "production-key",
        "mcp_configs": [
          {
            "mcp_client_name": "filesystem",
            "tools_to_execute": ["read_file", "list_directory"]
          },
          {
            "mcp_client_name": "web_search",
            "tools_to_execute": ["*"]
          }
        ]
      },
      {
        "name": "admin-key",
        "mcp_configs": [
          {
            "mcp_client_name": "filesystem",
            "tools_to_execute": ["*"]
          },
          {
            "mcp_client_name": "database",
            "tools_to_execute": ["*"]
          }
        ]
      }
    ]
  }
}

​

Tool Auto-Execution Is Client-Side in Gateway Mode

• Claude Desktop: tool-approval is per-tool in the host’s settings.
• Cursor / Cline / Continue: each has its own “auto-approve” or “trust” lists in the MCP integration config.
• Custom MCP hosts: the SDK you’re using (mark3labs/mcp-go, @modelcontextprotocol/sdk-typescript, etc.) typically exposes a callback for tool-call confirmation that you wire up yourself.

​

Advanced Gateway Features

​

Health Monitoring

• What a check does: a ping (when the server supports one) plus a tools/list over the same connection, so one pass covers both liveness and tool-list refresh
• Adaptive cadence: once a client is healthy, checks run on its tool sync interval (10 minutes by default). While a client is unstable they run every 10 seconds, so recovery is detected quickly
• Check timeout: each ping or tools/list attempt is bounded at 5 seconds and retried with backoff inside the check
• Failure threshold: a single failed check marks the client unstable. There is no consecutive-failure counter across checks; the retries inside each check are what absorb an ordinary blip
• Automatic recovery: a failed check reconnects the client in the background, so a session the server expired, a dropped SSE stream, or a stdio server whose process exited is replaced without anyone intervening. For http and sse the replacement is dialled before the old connection is dropped, so calls keep flowing throughout. stdio and in-process clients close first instead, because two subprocesses would double resource use and clash over anything held exclusively, such as a port bind or a lockfile
• Tool calls repair too: a call that fails because the credential was rejected or the session is gone triggers the same reconnect immediately, and usually retries the caller’s own request on the healed connection (see Auth failure recovery)
• unstable does not hide tools: it reflects Bifrost’s own checks, never the outcome of real tool calls, and tool calls keep being attempted normally throughout
• needs_reauth is sticky: clients whose OAuth credential permanently died are parked in needs_reauth, health checks won’t flip them back, and Reconnect is disabled for them; an admin must reauthorize instead

{
  "mcp": {
    "tool_sync_interval": "10m"
  }
}

POST /api/mcp/client/{id}/reconnect

// Reconnect a disconnected MCP client
err := client.ReconnectMCPClient(context.Background(), clientID)
if err != nil {
    // Handle reconnection error
    log.Printf("Failed to reconnect client: %v", err)
}

​

Reconnection behavior

• HTTP and SSE clients reconnect make-before-break. Bifrost dials the new connection first; the existing connection keeps serving tool calls for the whole dial. Once the new connection is ready, the swap is atomic, and only then is the old connection closed. In practice this means credential rotation, reauthorization, and the automatic-refresh recycle described in Automatic refresh don’t cause downtime for these clients.
• STDIO and in-process clients reconnect close-first. The existing connection (and, for STDIO, its subprocess) is closed before the new one is dialed, so there’s a brief window where the client has no connection. This is deliberate: a STDIO reconnect spawns a new subprocess, and many STDIO servers hold exclusive resources (lockfiles, bound ports, singleton sockets) that a second instance can’t acquire while the first is still running. STDIO reconnects are also almost always crash recovery, where the existing connection is already dead and there’s nothing to keep serving.

​

Request ID Tracking

mcpConfig := &schemas.MCPConfig{
    FetchNewRequestIDFunc: func(ctx context.Context) string {
        // Generate unique ID per agent iteration
        return fmt.Sprintf("agent-%s-%d", ctx.Value("original-id"), time.Now().UnixMilli())
    },
}

​

Dynamic Tool Discovery

1. Client Connection - Initial ListTools request
2. Runtime Updates - When server tool list changes
3. Configuration Changes - When tools_to_execute is updated

​

Per-User Auth on the Gateway

• x-bf-vk: <vk> (or Authorization: Bearer <vk> / x-api-key: <vk> / x-goog-api-key: <vk>) — VK-mode identity
• x-bf-mcp-session-id: <opaque-string> — session-mode identity (client-asserted, must be re-sent on every call)
• Enterprise SSO — user-mode identity, attached automatically by the auth middleware

• kind: "oauth" → authorize_url points at the upstream provider’s consent page (via a Bifrost intermediate)
• kind: "headers" → submit_url points at a Bifrost form where the user enters their header values

• User-mode flows require the bound SSO user — anyone else opening the URL gets a 403. User-owned VKs auto-promote to user-mode.
• VK-mode and session-mode flows are openable by anyone holding the URL. By default they still require a Bifrost dashboard session in the browser; turn on mcp_enable_temp_token_auth to let anonymous browsers complete them via a short-lived #t=<temp-token> URL fragment.

​

Public URL configuration when behind a proxy

• mcp_external_client_url — what Bifrost registers as the redirect_uri with upstream OAuth providers

​

Recommended: disable auto tool injection

• Web UI
• API
• config.json

1. Navigate to Settings → MCP in the sidebar
2. Toggle Disable Auto Tool Injection on
3. Click Save

curl -X PUT http://localhost:8080/api/config \
  -H "Content-Type: application/json" \
  -d '{
    "client_config": {
      "mcp_disable_auto_tool_inject": true
    }
  }'

PUT /api/config merges the supplied client_config into the existing one — other fields are unchanged.

{
  "client": {
    "mcp_disable_auto_tool_inject": true
  }
}

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-bf-mcp-include-tools: filesystem-*,github-create_issue" \
  -d '{ "model": "openai/gpt-4o", "messages": [...] }'

​

Security Considerations

​

1. Enable Virtual Key Enforcement

{
  "client": {
    "enforce_auth_on_inference": true
  }
}

​

2. Use HTTPS

MCP Client → HTTPS → Reverse Proxy → HTTP → Bifrost Gateway

​

3. Limit Tool Access

​

4. Network Restrictions

​

Troubleshooting

​

Next Steps