---
title: "Connecting to MCP Servers"
sidebarTitle: "Connecting to Servers"
description: "Connect Bifrost to external MCP servers via STDIO, HTTP, or SSE protocols."
icon: "plug"
---

## Overview

Bifrost can connect to any MCP-compatible server to discover and execute tools. Each connection is called an **MCP Client** in Bifrost terminology.

## Connection Types

Bifrost supports three connection protocols, each with different authentication options:

| Type | Description | Best For | Auth Support |
|------|-------------|----------|--------------|
| **STDIO** | Spawns a subprocess and communicates via stdin/stdout | Local tools, CLI utilities, scripts | None |
| **HTTP** | Sends requests to an HTTP endpoint | Remote APIs, microservices, cloud functions | Headers, OAuth 2.0, Per-User OAuth |
| **SSE** | Server-Sent Events for persistent connections | Real-time data, streaming tools | Headers, OAuth 2.0, Per-User OAuth |

### STDIO Connections

STDIO connections launch external processes and communicate via standard input/output. Best for local tools and scripts.

```json
{
  "name": "filesystem",
  "connection_type": "stdio",
  "stdio_config": {
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-filesystem"],
    "envs": ["HOME", "PATH"]
  },
  "tools_to_execute": ["*"]
}
```

**Use Cases:**
- Local filesystem operations
- Python/Node.js MCP servers
- CLI utilities and scripts
- Database tools with local credentials

<Warning>
**Docker Users:** When running Bifrost in Docker, STDIO connections may not work if the required commands (e.g., `npx`, `python`) are not installed in the container. For STDIO-based MCP servers, build a custom Docker image that includes the necessary dependencies, or use HTTP/SSE connections to externally hosted MCP servers.
</Warning>

### HTTP Connections

HTTP connections communicate with MCP servers via HTTP requests. Ideal for remote services and microservices.

HTTP connections support three authentication methods:
- **Header-based authentication**: Static headers (API keys, custom tokens)
- **OAuth 2.0**: Shared token managed by an admin, with automatic refresh
- **Per-User OAuth**: Each end-user authenticates with their own credentials

#### Header-Based Authentication

Use static headers for API keys and custom authentication tokens:

```json
{
  "name": "web-search",
  "connection_type": "http",
  "connection_string": "https://mcp-server.example.com/mcp",
  "auth_type": "headers",
  "headers": {
    "Authorization": "Bearer your-api-key",
    "X-Custom-Header": "value"
  },
  "tools_to_execute": ["*"]
}
```

**Use Cases:**
- Static API keys
- Bearer token authentication
- Custom header-based auth schemes

#### OAuth 2.0 Authentication

Use OAuth 2.0 for secure, user-based authentication with automatic token refresh:

```json
{
  "name": "web-search",
  "connection_type": "http",
  "connection_string": "https://mcp-server.example.com/mcp",
  "auth_type": "oauth",
  "oauth_config": {
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "authorize_url": "https://auth.example.com/authorize",
    "token_url": "https://auth.example.com/token",
    "scopes": ["read", "write"]
  },
  "tools_to_execute": ["*"]
}
```

**Features:**
- Automatic token refresh before expiration
- PKCE support for public clients
- Dynamic client registration (RFC 7591)
- OAuth discovery from server URLs

[→ Learn more about OAuth authentication →](./oauth)

**Use Cases:**
- Shared service integrations where all users access the same account
- Admin-managed third-party connections
- Compliance with OAuth 2.0 standards

#### Per-User OAuth

Use per-user OAuth when each end-user should access the upstream service under their own account (e.g., each user's personal Notion workspace or GitHub repos). Bifrost acts as an OAuth 2.1 Authorization Server — users authenticate through a consent flow and their tokens are stored per-identity.

Per-user OAuth is configured through the Web UI only (Bifrost runs a test OAuth flow and pre-fetches tools at setup time).

[→ Learn more about Per-User OAuth →](./per-user-oauth)

**Use Cases:**
- Multi-tenant apps where users access their own data
- Personal integrations (Notion, GitHub, Google Drive)
- Scenarios requiring per-user audit trails and token isolation

**Overall HTTP Use Cases:**
- Remote API integrations
- Cloud-hosted MCP services
- Microservice architectures
- Third-party tool providers

### SSE Connections

Server-Sent Events (SSE) connections provide real-time, persistent connections to MCP servers. Like HTTP connections, SSE supports header-based authentication, OAuth 2.0, and per-user OAuth.

#### Header-Based Authentication

```json
{
  "name": "live-data",
  "connection_type": "sse",
  "connection_string": "https://stream.example.com/mcp/sse",
  "auth_type": "headers",
  "headers": {
    "Authorization": "Bearer your-api-key"
  },
  "tools_to_execute": ["*"]
}
```

#### OAuth 2.0 Authentication

```json
{
  "name": "live-data",
  "connection_type": "sse",
  "connection_string": "https://stream.example.com/mcp/sse",
  "auth_type": "oauth",
  "oauth_config": {
    "client_id": "your-client-id",
    "authorize_url": "https://auth.example.com/authorize",
    "token_url": "https://auth.example.com/token",
    "scopes": ["stream:read"]
  },
  "tools_to_execute": ["*"]
}
```

**Use Cases:**
- Real-time market data
- Live system monitoring
- Event-driven workflows
- Shared streaming connections managed by an admin

#### Per-User OAuth

Same as HTTP — each user authenticates under their own account. Configured through the Web UI only.

[→ Learn more about Per-User OAuth →](./per-user-oauth)

[→ Learn more about OAuth authentication →](./oauth)

---

## Gateway Setup

<Tabs>
<Tab title="Web UI">

### Adding an MCP Client

1. Navigate to **MCP Gateway** in the sidebar - you'll see a table of all registered servers

<Frame>
  <img src="/media/ui-mcp-servers-table.png" alt="MCP Servers Table" />
</Frame>

2. Click **New MCP Server** button to open the creation form

3. Fill in the connection details:

<Frame>
  <img src="/media/ui-mcp-new-server.png" alt="Add MCP Client Form" />
</Frame>

**Fields:**
- **Name**: Unique identifier (no spaces or hyphens, ASCII only)
- **Connection Type**: STDIO, HTTP, or SSE
- **For STDIO**: Command, arguments, and environment variables
- **For HTTP/SSE**: Connection URL

4. Click **Create** to connect

### Viewing and Managing Connected Tools

Once connected, click on any client row to open the configuration sheet:

<Frame>
  <img src="/media/ui-mcp-tool-config.png" alt="MCP Client Configuration and Tools" />
</Frame>

Here you can:
- View all discovered tools with their descriptions and parameters
- Enable/disable individual tools via toggle switches
- Configure auto-execution for specific tools
- Edit custom headers for HTTP/SSE connections
- View the full connection configuration as JSON

</Tab>
<Tab title="API">

### Add STDIO Client

```bash
curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
    "name": "filesystem",
    "connection_type": "stdio",
    "stdio_config": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem"],
      "envs": ["HOME", "PATH"]
    },
    "tools_to_execute": ["*"]
  }'
```

### Add HTTP Client

```bash
curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web_search",
    "connection_type": "http",
    "connection_string": "http://localhost:3001/mcp",
    "tools_to_execute": ["*"]
  }'
```

### Add SSE Client

```bash
curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
    "name": "realtime_data",
    "connection_type": "sse",
    "connection_string": "https://api.example.com/mcp/sse",
    "tools_to_execute": ["*"]
  }'
```

### List All Clients

```bash
curl http://localhost:8080/api/mcp/clients
```

Response:
```json
[
  {
    "config": {
      "id": "abc123",
      "name": "filesystem",
      "connection_type": "stdio",
      "stdio_config": {
        "command": "npx",
        "args": ["-y", "@anthropic/mcp-filesystem"]
      }
    },
    "tools": [
      {"name": "read_file", "description": "Read contents of a file"},
      {"name": "write_file", "description": "Write contents to a file"},
      {"name": "list_directory", "description": "List directory contents"}
    ],
    "state": "connected"
  }
]
```

</Tab>
<Tab title="config.json">

Configure MCP clients in your `config.json`:

```json
{
  "mcp": {
    "client_configs": [
      {
        "name": "filesystem",
        "connection_type": "stdio",
        "is_ping_available": true,
        "stdio_config": {
          "command": "npx",
          "args": ["-y", "@anthropic/mcp-filesystem"],
          "envs": ["HOME", "PATH"]
        },
        "tools_to_execute": ["*"]
      },
      {
        "name": "web_search",
        "connection_type": "http",
        "connection_string": "env.WEB_SEARCH_MCP_URL",
        "is_ping_available": false,
        "tools_to_execute": ["search", "fetch_url"]
      },
      {
        "name": "database",
        "connection_type": "sse",
        "connection_string": "https://db-mcp.example.com/sse",
        "is_ping_available": true,
        "tools_to_execute": []
      }
    ]
  }
}
```

<Note>
Use `env.VARIABLE_NAME` syntax to reference environment variables for sensitive values like URLs with API keys.
</Note>

</Tab>
</Tabs>

---

## Go SDK Setup

Configure MCP in your Bifrost initialization:

```go
package main

import (
    "context"
    bifrost "github.com/maximhq/bifrost/core"
    "github.com/maximhq/bifrost/core/schemas"
)

func main() {
    mcpConfig := &schemas.MCPConfig{
        ClientConfigs: []schemas.MCPClientConfig{
            {
                Name:             "filesystem",
                ConnectionType:   schemas.MCPConnectionTypeSTDIO,
                IsPingAvailable:  true,  // Use lightweight ping for health checks
                StdioConfig: &schemas.MCPStdioConfig{
                    Command: "npx",
                    Args:    []string{"-y", "@anthropic/mcp-filesystem"},
                    Envs:    []string{"HOME", "PATH"},
                },
                ToolsToExecute: []string{"*"},
            },
            {
                Name:             "web_search",
                ConnectionType:   schemas.MCPConnectionTypeHTTP,
                ConnectionString: bifrost.Ptr("http://localhost:3001/mcp"),
                IsPingAvailable:  false,  // Use listTools for health checks
                ToolsToExecute:   []string{"search", "fetch_url"},
            },
        },
    }

    client, err := bifrost.Init(context.Background(), schemas.BifrostConfig{
        Account:   account,
        MCPConfig: mcpConfig,
        Logger:    bifrost.NewDefaultLogger(schemas.LogLevelInfo),
    })
    if err != nil {
        panic(err)
    }
}
```

### Tools To Execute Semantics

The `ToolsToExecute` field controls which tools from the client are available:

| Value | Behavior |
|-------|----------|
| `["*"]` | All tools from this client are included |
| `[]` or `nil` | No tools included (deny-by-default) |
| `["tool1", "tool2"]` | Only specified tools are included |

### Tools To Auto Execute (Agent Mode)

The `ToolsToAutoExecute` field controls which tools can be automatically executed in [Agent Mode](./agent-mode):

| Value | Behavior |
|-------|----------|
| `["*"]` | All tools are auto-executed |
| `[]` or `nil` | No tools are auto-executed (manual approval required) |
| `["tool1", "tool2"]` | Only specified tools are auto-executed |

<Note>
A tool must be in **both** `ToolsToExecute` and `ToolsToAutoExecute` to be auto-executed. If a tool is in `ToolsToAutoExecute` but not in `ToolsToExecute`, it will be skipped.
</Note>

**Example configuration:**

```go
{
    Name:           "filesystem",
    ConnectionType: schemas.MCPConnectionTypeSTDIO,
    StdioConfig: &schemas.MCPStdioConfig{
        Command: "npx",
        Args:    []string{"-y", "@anthropic/mcp-filesystem"},
    },
    ToolsToExecute:     []string{"*"},                              // All tools available
    ToolsToAutoExecute: []string{"read_file", "list_directory"},    // Only these auto-execute
}
```

---

## Environment Variables

Use environment variables for sensitive configuration values:

**Gateway (config.json):**
```json
{
  "name": "secure_api",
  "connection_type": "http",
  "connection_string": "env.SECURE_MCP_URL"
}
```

**Go SDK:**
```go
{
    Name:             "secure_api",
    ConnectionType:   schemas.MCPConnectionTypeHTTP,
    ConnectionString: bifrost.Ptr(os.Getenv("SECURE_MCP_URL")),
}
```

Environment variables are:
- Automatically resolved during client connection
- Redacted in API responses and UI for security
- Validated at startup to ensure all required variables are set

---

## Forwarding Request Headers to MCP Servers

<Info>
Header Forwarding is available in **v1.5.0-prerelease1 and above**.
</Info>

By default, Bifrost does not forward incoming request headers to MCP servers during tool execution. The `allowed_extra_headers` field lets you define a per-client allowlist of headers that callers may inject at request time and have forwarded to that MCP server when tools are executed.

This is separate from the static `headers` field used for authentication:

| Field | Purpose | When sent |
|-------|---------|-----------|
| `headers` | Static auth credentials (API keys, tokens) | Always, on every tool call |
| `allowed_extra_headers` | Dynamic per-request headers from callers | Only when the caller provides them, and only if they match the allowlist |

**Common use cases:**
- Forwarding a user's auth token to an MCP server that enforces per-user authorization
- Passing a tenant or org ID to a multi-tenant MCP server
- Propagating trace or correlation IDs for end-to-end observability

### How It Works

1. An incoming request carries one or more headers matching a client's `allowed_extra_headers` pattern
2. Bifrost captures those headers from the request (using the union of all clients' allowlists)
3. At tool execution time, each client **re-checks** the header against its own allowlist — so the same header can be forwarded to one MCP server but not another

<Note>
Headers are matched case-insensitively. The only wildcard supported is a standalone `"*"` (allow all headers) — partial patterns like `x-tenant-*` are not supported. If `"*"` is used, it must be the only entry in the list.
</Note>

<Tabs>
<Tab title="UI">

**Configure:** Navigate to **MCP Gateway**, open the configuration sheet for an HTTP or SSE client, and set the **Allowed Extra Headers** field:

<Frame>
  <img src="/media/ui-mcp-allowed-extra-headers.png" alt="Allowed Extra Headers configuration in the MCP client edit sheet" />
</Frame>

**Send headers:** Include the allowed headers in any inference request to the LLM gateway:

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-user-token: eyJhbGci..." \
  -H "x-tenant-id: acme-corp" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Look up my account details"}]
  }'
```

</Tab>
<Tab title="Management API">

**Configure:** Include `allowed_extra_headers` when creating or updating a client:

```bash
curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_api",
    "connection_type": "http",
    "connection_string": "https://mcp.example.com/mcp",
    "auth_type": "headers",
    "headers": {
      "Authorization": "Bearer service-token"
    },
    "allowed_extra_headers": ["x-user-token", "x-tenant-id", "x-request-id"],
    "tools_to_execute": ["*"]
  }'
```

**Send headers:** Include the allowed headers in any inference request:

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-user-token: eyJhbGci..." \
  -H "x-tenant-id: acme-corp" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Look up my account details"}]
  }'
```

</Tab>
<Tab title="Config File">

**Configure:**

```json
{
  "mcp": {
    "client_configs": [
      {
        "name": "my_api",
        "connection_type": "http",
        "connection_string": "https://mcp.example.com/mcp",
        "auth_type": "headers",
        "headers": {
          "Authorization": "Bearer service-token"
        },
        "allowed_extra_headers": ["x-user-token", "x-tenant-id", "x-request-id"],
        "tools_to_execute": ["*"]
      }
    ]
  }
}
```

**Send headers:** Include the allowed headers in any inference request:

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-user-token: eyJhbGci..." \
  -H "x-tenant-id: acme-corp" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Look up my account details"}]
  }'
```

</Tab>
<Tab title="MCP Gateway (/mcp)">

**Configure** the client as above (Web UI, Management API, or config.json).

**Send headers:** When an external MCP client (e.g., Claude Desktop, Cursor) connects to Bifrost's `/mcp` endpoint, include the allowed headers in that HTTP request. Bifrost forwards them during any tool call made within that session:

```json
{
  "mcpServers": {
    "bifrost": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "x-user-token": "eyJhbGci...",
        "x-tenant-id": "acme-corp"
      }
    }
  }
}
```

<Note>
Header support in MCP client config varies by client. The above JSON format applies to clients that support custom headers (e.g., Claude Desktop, Cursor). Check your MCP client's documentation for the exact configuration syntax.
</Note>

</Tab>
<Tab title="Go SDK">

**Configure:**

```go
schemas.MCPClientConfig{
    Name:             "my_api",
    ConnectionType:   schemas.MCPConnectionTypeHTTP,
    ConnectionString: bifrost.Ptr("https://mcp.example.com/mcp"),
    AuthType:         schemas.MCPAuthTypeHeaders,
    Headers: map[string]schemas.EnvVar{
        "Authorization": {Value: "Bearer service-token"},
    },
    AllowedExtraHeaders: schemas.WhiteList{"x-user-token", "x-tenant-id", "x-request-id"},
    ToolsToExecute: []string{"*"},
}
```

**Send headers:** Set `BifrostContextKeyMCPExtraHeaders` on the context before calling `ChatCompletionRequest` or `ExecuteChatMCPTool`:

```go
bifrostCtx := schemas.NewBifrostContext(context.Background(), schemas.NoDeadline)
bifrostCtx.SetValue(schemas.BifrostContextKeyMCPExtraHeaders, map[string][]string{
    "x-user-token": {"eyJhbGci..."},
    "x-tenant-id":  {"acme-corp"},
})

response, err := client.ChatCompletionRequest(bifrostCtx, request)
```

</Tab>
</Tabs>

---

## Client State Management

### Connection States

| State | Description |
|-------|-------------|
| `connected` | Client is active and tools are available |
| `connecting` | Client is establishing connection |
| `disconnected` | Client lost connection but can be reconnected |
| `error` | Client configuration or connection failed |

### Managing Clients at Runtime

<Tabs>
<Tab title="Gateway API">

**Reconnect a client:**
```bash
curl -X POST http://localhost:8080/api/mcp/client/{id}/reconnect
```

**Edit client configuration:**
```bash
curl -X PUT http://localhost:8080/api/mcp/client/{id} \
  -H "Content-Type: application/json" \
  -d '{
    "name": "filesystem",
    "connection_type": "stdio",
    "stdio_config": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem"]
    },
    "tools_to_execute": ["read_file", "list_directory"]
  }'
```

**Remove a client:**
```bash
curl -X DELETE http://localhost:8080/api/mcp/client/{id}
```

</Tab>
<Tab title="Go SDK">

```go
// Get all connected clients
clients, err := client.GetMCPClients()
for _, mcpClient := range clients {
    fmt.Printf("Client: %s, State: %s, Tools: %d\n",
        mcpClient.Config.Name,
        mcpClient.State,
        len(mcpClient.Tools))
}

// Reconnect a disconnected client
err = client.ReconnectMCPClient("filesystem")

// Add new client at runtime
err = client.AddMCPClient(schemas.MCPClientConfig{
    Name:           "new_client",
    ConnectionType: schemas.MCPConnectionTypeHTTP,
    ConnectionString: bifrost.Ptr("http://localhost:3002/mcp"),
    ToolsToExecute: []string{"*"},
})

// Remove a client
err = client.RemoveMCPClient("old_client")

// Edit client tools
err = client.EditMCPClientTools("filesystem", []string{"read_file", "list_directory"})
```

</Tab>
</Tabs>

---

## Health Monitoring

Bifrost automatically monitors MCP client health with periodic checks every 10 seconds by default.

### Health Check Methods

By default, Bifrost uses the lightweight **ping method** for health checks. However, you can configure the health check method based on your MCP server's capabilities:

| Method | When to Use | Overhead | Fallback |
|--------|------------|----------|----------|
| **Ping** (default) | Server supports MCP ping protocol | Minimal | Best for most servers |
| **ListTools** | Server doesn't support ping, or you need heavier checks | Higher | More resource-intensive |

### Configuring Health Check Method

You can toggle the `is_ping_available` setting for each client:

#### Via Web UI

1. Navigate to **MCP Gateway** and select a server
2. In the configuration panel, toggle **"Ping Available for Health Check"**
3. Enable: Uses lightweight ping for health checks
4. Disable: Uses listTools method for health checks instead

<Frame>
  <img src="/media/ui-mcp-ping-available.png" alt="Ping Available Toggle" />
</Frame>

#### Via API

```bash
curl -X PUT http://localhost:8080/api/mcp/client/{id} \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_server",
    "is_ping_available": false
  }'
```

#### Via config.json

```json
{
  "mcp": {
    "client_configs": [
      {
        "name": "filesystem",
        "connection_type": "stdio",
        "is_ping_available": true,
        "stdio_config": {
          "command": "npx",
          "args": ["-y", "@anthropic/mcp-filesystem"]
        }
      }
    ]
  }
}
```

#### Via Go SDK

```go
err := client.EditMCPClient(context.Background(), schemas.MCPClientConfig{
    ID:               "filesystem",
    Name:             "filesystem",
    IsPingAvailable:  false,  // Use listTools instead of ping
    ToolsToExecute:   []string{"*"},
})
```

### Health Check Behavior

When a client disconnects:
1. State changes to `disconnected`
2. Tools from that client become unavailable
3. You can reconnect via API or UI

**Note:** Changing `is_ping_available` takes effect immediately without requiring a client reconnection.

---

## Connection Resilience and Retry Logic

Bifrost automatically implements **exponential backoff retry logic** to handle transient network failures and temporary service unavailability. This ensures that brief connection issues don't immediately cause tool unavailability.

<Warning>
**Important:** Bifrost only retries on transient errors (network failures, timeouts, temporary service unavailability). Permanent errors like authentication failures, configuration errors, and missing commands fail immediately without retry.
</Warning>

### Automatic Retry Strategy

Bifrost retries failed operations using the following strategy, as implemented by `ExecuteWithRetry` and `DefaultRetryConfig` in the MCP layer:

| Parameter | Value | Description |
|-----------|-------|-------------|
| **Max Retries** (`DefaultRetryConfig.MaxRetries`) | 5 | Retries after the initial attempt (6 attempts total) |
| **Initial Backoff** (`DefaultRetryConfig.InitialBackoff`) | 1 second | Starting backoff duration before doubling |
| **Max Backoff** (`DefaultRetryConfig.MaxBackoff`) | 30 seconds | Maximum wait time between retries |
| **Backoff Multiplier** | 2x | Exponential growth between attempts |

**Backoff Progression** (matches `ExecuteWithRetry` with `DefaultRetryConfig`):
- Attempt 1: Initial attempt (no wait)
- Attempt 2: Wait 1s, then retry (and double backoff to 2s)
- Attempt 3: Wait 2s, then retry (and double backoff to 4s)
- Attempt 4: Wait 4s, then retry (and double backoff to 8s)
- Attempt 5: Wait 8s, then retry (and double backoff to 16s)
- Attempt 6: Wait 16s, then retry (backoff capped at 30s max)

### Error Classification

Bifrost intelligently classifies errors as either **transient** (retryable) or **permanent** (fail immediately):

**Transient Errors (Retried):**
- Connection timeouts or refused connections
- Network unreachable errors
- DNS resolution failures
- HTTP 5xx errors (500, 502, 503, 504)
- HTTP 429 (Too Many Requests)
- I/O errors and broken pipes
- Temporary service unavailability

**Permanent Errors (Fail Immediately - No Retry):**
- **Context deadline exceeded or cancelled** - Retrying won't help if time limit is reached
- Authentication failures (401, 403)
- Authorization denied
- Configuration errors (invalid auth, invalid config)
- File or command not found (e.g., "command not found: npx")
- Bad request errors (400, 405, 422)
- Command execution permission denied
- Invalid credentials

### What Operations Are Retried

Bifrost applies retry logic to these critical operations:

1. **Connection Creation** - Establishing initial connection to the MCP server (with error classification)
2. **Transport Start** - Starting the transport layer (STDIO, HTTP, SSE)
3. **Client Initialization** - Initializing the MCP client protocol
4. **Tool Discovery** - Retrieving available tools from the server
5. **Automatic Reconnection** - When health checks detect disconnection

### Reconnection on Health Check Failure

When a client reaches 5 consecutive health check failures:

1. Client state changes to `disconnected`
2. Bifrost automatically attempts reconnection **in the background**
3. Reconnection uses the same exponential backoff retry logic
4. Once reconnected, health checks resume normal operation
5. Tools become available again without manual intervention

This automatic reconnection happens asynchronously and doesn't block other operations.

### Manual Reconnection

You can also trigger manual reconnection at any time:

<Tabs>
<Tab title="Gateway API">

```bash
curl -X POST http://localhost:8080/api/mcp/client/{id}/reconnect
```

Manual reconnection also uses the retry logic for robustness.

</Tab>
<Tab title="Go SDK">

```go
// Reconnect with automatic retry logic
err := client.ReconnectMCPClient("filesystem")
if err != nil {
    log.Printf("Reconnection failed after retries: %v", err)
}
```

</Tab>
</Tabs>

### Benefits

- **Handles transient failures**: Brief network hiccups won't cause tool unavailability
- **Prevents server overload**: Exponential backoff prevents hammering servers
- **Automatic recovery**: Disconnected clients reconnect automatically
- **Production-ready**: No manual intervention needed for temporary issues
- **Transparent logging**: Detailed retry attempts logged for debugging

---

## Naming Conventions

MCP client names have specific requirements:

<Warning>
- Must contain only ASCII characters
- Cannot contain hyphens (`-`) or spaces
- Cannot start with a number
- Must be unique across all clients
</Warning>

**Valid names:** `filesystem`, `web_search`, `myAPI`, `tool123`

**Invalid names:** `my-tools`, `web search`, `123tools`, `datos-api`

---

## Next Steps

<CardGroup cols={2}>
  <Card title="Tool Execution" icon="play" href="./tool-execution">
    Learn how to execute tools from connected MCP servers
  </Card>
  <Card title="Agent Mode" icon="robot" href="./agent-mode">
    Enable autonomous tool execution with auto-approval
  </Card>
</CardGroup>
