Connecting to MCP Servers

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:

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

STDIO Connections

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

{
  "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

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.

HTTP Connections

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

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

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.

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

Use Cases:

Real-time market data
Live system monitoring
Event-driven workflows

Gateway Setup

Web UI
API
config.json

Adding an MCP Client

Navigate to MCP Clients in the sidebar - you’ll see a table of all registered servers

Click New MCP Server button to open the creation form
Fill in the connection details:

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

Click Create to connect

Viewing and Managing Connected Tools

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

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

Add STDIO Client

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

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

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

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

Response:

[
  {
    "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"
  }
]

Configure MCP clients in your config.json:

{
  "mcp": {
    "client_configs": [
      {
        "name": "filesystem",
        "connection_type": "stdio",
        "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",
        "tools_to_execute": ["search", "fetch_url"]
      },
      {
        "name": "database",
        "connection_type": "sse",
        "connection_string": "https://db-mcp.example.com/sse",
        "tools_to_execute": []
      }
    ]
  }
}

Use env.VARIABLE_NAME syntax to reference environment variables for sensitive values like URLs with API keys.

Go SDK Setup

Configure MCP in your Bifrost initialization:

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,
                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"),
                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:

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

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.

Example configuration:

{
    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):

{
  "name": "secure_api",
  "connection_type": "http",
  "connection_string": "env.SECURE_MCP_URL"
}

Go SDK:

{
    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

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

Gateway API
Go SDK

Reconnect a client:

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

Edit client configuration:

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:

curl -X DELETE http://localhost:8080/api/mcp/client/{id}

// 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"})

Health Monitoring

Bifrost automatically monitors MCP client health:

Periodic Pings: Every 10 seconds by default
Auto-Detection: Disconnections are detected automatically
State Updates: Client state changes are reflected in API responses

When a client disconnects:

State changes to disconnected
Tools from that client become unavailable
You can reconnect via API or UI

Naming Conventions

MCP client names have specific requirements:

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

Valid names: filesystem, web_search, myAPI, tool123 Invalid names: my-tools, web search, 123tools, datos-api

Quick Start

Providers & Guides

SDK Integrations

MCP Gateway

Custom plugins

Open Source Features

Enterprise Features

Connecting to MCP Servers

Overview

Connection Types

STDIO Connections

HTTP Connections

SSE Connections

Gateway Setup

Adding an MCP Client

Viewing and Managing Connected Tools

Add STDIO Client

Add HTTP Client

Add SSE Client

List All Clients

Go SDK Setup

Tools To Execute Semantics

Tools To Auto Execute (Agent Mode)

Environment Variables

Client State Management

Connection States

Managing Clients at Runtime

Health Monitoring

Naming Conventions

Next Steps

Tool Execution

Agent Mode

Quick Start

Providers & Guides

SDK Integrations

MCP Gateway

Custom plugins

Open Source Features

Enterprise Features

​Overview

​Connection Types

​STDIO Connections

​HTTP Connections

​SSE Connections

​Gateway Setup

​Adding an MCP Client

​Viewing and Managing Connected Tools

​Add STDIO Client

​Add HTTP Client

​Add SSE Client

​List All Clients

​Go SDK Setup

​Tools To Execute Semantics

​Tools To Auto Execute (Agent Mode)

​Environment Variables

​Client State Management

​Connection States

​Managing Clients at Runtime

​Health Monitoring

​Naming Conventions

​Next Steps

Tool Execution

Agent Mode

Overview

Connection Types

STDIO Connections

HTTP Connections

SSE Connections

Gateway Setup

Adding an MCP Client

Viewing and Managing Connected Tools

Add STDIO Client

Add HTTP Client

Add SSE Client

List All Clients

Go SDK Setup

Tools To Execute Semantics

Tools To Auto Execute (Agent Mode)

Environment Variables

Client State Management

Connection States

Managing Clients at Runtime

Health Monitoring

Naming Conventions

Next Steps