MCP Configuration - Maxim Docs

MCP Overview (File Based)

You can directly use the UI (http://localhost:{port}/mcp-clients) to configure the MCP clients.

MCP (Model Context Protocol) configuration enables:

External tool integration (filesystem, web scraping, databases)
STDIO, HTTP, and SSE connections to MCP servers
Tool filtering and access control
HTTP endpoint for manual tool execution (/v1/mcp/tool/execute)

{
  "mcp": {
    "client_configs": [
      {
        "name": "filesystem",
        "connection_type": "stdio",
        "stdio_config": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem"]
        }
      }
    ]
  }
}

Connection Types

STDIO Connection

Most common for local MCP servers:

{
  "mcp": {
    "client_configs": [
      {
        "name": "filesystem-tools",
        "connection_type": "stdio",
        "stdio_config": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem"],
          "envs": ["HOME", "USER"]
        },
        "tools_to_execute": ["read_file", "list_directory"],
        "tools_to_skip": ["delete_file"]
      }
    ]
  }
}

HTTP Connection

For remote MCP servers:

{
  "mcp": {
    "client_configs": [
      {
        "name": "remote-api",
        "connection_type": "http",
        "connection_string": "env.MCP_CONNECTION_STRING"
      }
    ]
  }
}

🔒 Security: Use env.PREFIX for secure connection strings: "connection_string": "env.MCP_CONNECTION_STRING"

SSE Connection

For server-sent events:

{
  "mcp": {
    "client_configs": [
      {
        "name": "realtime-data",
        "connection_type": "sse",
        "connection_string": "env.MCP_SSE_CONNECTION_STRING"
      }
    ]
  }
}

Popular MCP Servers

Filesystem Tools

{
  "name": "filesystem",
  "connection_type": "stdio",
  "stdio_config": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem"],
    "envs": ["HOME"]
  },
  "tools_to_execute": ["read_file", "list_directory", "write_file"]
}

Web Search

{
  "name": "web-search",
  "connection_type": "stdio",
  "stdio_config": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-web-search"],
    "envs": ["SEARCH_API_KEY"]
  }
}

Database Access

{
  "name": "database",
  "connection_type": "stdio",
  "stdio_config": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "envs": ["DATABASE_URL"]
  },
  "tools_to_execute": ["query", "schema"]
}

Git Integration

{
  "name": "git-tools",
  "connection_type": "stdio",
  "stdio_config": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-git"],
    "envs": ["GIT_AUTHOR_NAME", "GIT_AUTHOR_EMAIL"]
  }
}

Tool Filtering

Whitelist Approach

Only allow specific tools:

{
  "name": "safe-filesystem",
  "connection_type": "stdio",
  "stdio_config": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem"]
  },
  "tools_to_execute": ["read_file", "list_directory"]
}

Blacklist Approach

Allow all tools except dangerous ones:

{
  "name": "web-tools",
  "connection_type": "stdio",
  "stdio_config": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-web"]
  },
  "tools_to_skip": ["delete_page", "modify_content", "admin_access"]
}

Using MCP Tools via HTTP

Automatic Tool Integration

Tools are automatically available in chat completions:

# Make a request - MCP tools are automatically added
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "List the files in the current directory"}
    ]
  }'

# Response includes tool calls
# {
#   "choices": [{
#     "message": {
#       "tool_calls": [{
#         "id": "call_123",
#         "type": "function",
#         "function": {
#           "name": "list_directory",
#           "arguments": "{\"path\": \".\"}"
#         }
#       }]
#     }
#   }]
# }

Manual Tool Execution

Execute tools directly via HTTP endpoint:

curl -X POST http://localhost:8080/v1/mcp/tool/execute \
  -H "Content-Type: application/json" \
  -d '{
    "id": "call_123",
    "type": "function",
    "function": {
      "name": "read_file",
      "arguments": "{\"path\": \"config.json\"}"
    }
  }'

# Response
# {
#   "role": "tool",
#   "content": {
#     "content_str": "{\n  \"providers\": {\n    ...\n  }\n}"
#   },
#   "tool_call_id": "call_123"
# }

Multi-Turn Conversations with MCP Tools

When MCP is configured, Bifrost automatically adds available tools to requests. Here’s an example of a multi-turn conversation where the AI uses tools: Initial Request (AI decides to use a tool):

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Can you list the files in the /tmp directory?"}
    ]
  }'

Response includes tool calls:

{
  "data": {
    "choices": [
      {
        "message": {
          "role": "assistant",
          "content": null,
          "tool_calls": [
            {
              "id": "call_abc123",
              "type": "function",
              "function": {
                "name": "list_directory",
                "arguments": "{\"path\": \"/tmp\"}"
              }
            }
          ]
        }
      }
    ]
  }
}

Execute Tool (Use Bifrost’s MCP tool execution endpoint): 💡 Note: The request body of this endpoint is a tool call block you received from /v1/chat/completions route - you can directly copy and paste the tool call block as the request body.

curl -X POST http://localhost:8080/v1/mcp/tool/execute \
  -H "Content-Type: application/json" \
  -d '{
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "list_directory",
        "arguments": "{\"path\": \"/tmp\"}"
      }
  }'

Response with tool result:

{
  "role": "tool",
  "content": "config.json\nreadme.txt\ndata.csv",
  "tool_call_id": "call_abc123"
}

Continue Conversation (Add tool result and get final response):

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Can you list the files in the /tmp directory?"},
      {
        "role": "assistant",
        "content": null,
        "tool_calls": [{
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "list_directory",
            "arguments": "{\"path\": \"/tmp\"}"
          }
        }]
      },
      {
        "role": "tool",
        "content": "config.json\nreadme.txt\ndata.csv",
        "tool_call_id": "call_abc123"
      }
    ]
  }'

Final response:

{
  "data": {
    "choices": [
      {
        "message": {
          "role": "assistant",
          "content": "I found 3 files in the /tmp directory:\n1. config.json\n2. readme.txt\n3. data.csv\n\nWould you like me to read the contents of any of these files?"
        }
      }
    ]
  }
}

Tool Execution Flow Summary:

Send chat completion request → AI responds with tool_calls
Send tool_calls to /v1/mcp/tool/execute → Get tool_result message
Append tool_result to conversation → Send back for final response

Request-Level Tool Filtering

Control which MCP tools are available per request using context:

# Include only specific MCP clients
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "List files and search web"}
    ],
    "mcp-include-clients": ["filesystem"],
    "mcp-exclude-clients": ["web-search", "database"]
  }'

# Include specific tools only
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Help me with file operations"}
    ],
    "mcp-include-tools": ["read_file", "list_directory"],
    "mcp-exclude-tools": ["delete_file", "write_file"]
  }'

MCP Management API Endpoints

Bifrost HTTP transport provides REST API endpoints for dynamic MCP client management.

GET /api/mcp/clients - List All MCP Clients

Get information about all configured MCP clients:

curl -X GET http://localhost:8080/api/mcp/clients

# Response
[
  {
    "name": "filesystem",
    "config": {
      "name": "filesystem",
      "connection_type": "stdio",
      "stdio_config": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem"]
      },
      "tools_to_execute": ["read_file", "list_directory"]
    },
    "tools": ["read_file", "list_directory", "write_file"],
    "state": "connected"
  },
  {
    "name": "web-search",
    "config": {
      "name": "web-search", 
      "connection_type": "stdio",
      "stdio_config": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-web-search"]
      }
    },
    "tools": [],
    "state": "error"
  }
]

POST /api/mcp/client - Add New MCP Client

Add a new MCP client at runtime:

# Add STDIO client
curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
    "name": "git-tools",
    "connection_type": "stdio",
    "stdio_config": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"],
      "envs": ["GIT_AUTHOR_NAME", "GIT_AUTHOR_EMAIL"]
    },
    "tools_to_execute": ["git_log", "git_status"]
  }'

# Add HTTP client
curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
    "name": "remote-api",
    "connection_type": "http",
    "connection_string": "https://api.example.com/mcp"
  }'

# 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"
  }'

# Success Response
{
  "status": "success",
  "message": "MCP client added successfully"
}

PUT /api/mcp/client/ - Edit Client Tools

Modify which tools are available from a client:

# Allow only specific tools (whitelist)
curl -X PUT http://localhost:8080/api/mcp/client/filesystem \
  -H "Content-Type: application/json" \
  -d '{
    "tools_to_execute": ["read_file", "list_directory"]
  }'

# Block specific tools (blacklist)
curl -X PUT http://localhost:8080/api/mcp/client/filesystem \
  -H "Content-Type: application/json" \
  -d '{
    "tools_to_skip": ["delete_file", "write_file"]
  }'

# Clear all restrictions (allow all tools)
curl -X PUT http://localhost:8080/api/mcp/client/filesystem \
  -H "Content-Type: application/json" \
  -d '{
    "tools_to_execute": [],
    "tools_to_skip": []
  }'

# Success Response
{
  "status": "success", 
  "message": "MCP client tools edited successfully"
}

DELETE /api/mcp/client/ - Remove MCP Client

Remove an MCP client and disconnect it:

curl -X DELETE http://localhost:8080/api/mcp/client/filesystem

# Success Response
{
  "status": "success",
  "message": "MCP client removed successfully"
}

POST /api/mcp/client//reconnect - Reconnect Client

Reconnect a disconnected or errored MCP client:

curl -X POST http://localhost:8080/api/mcp/client/filesystem/reconnect

# Success Response
{
  "status": "success",
  "message": "MCP client reconnected successfully"
}

POST /v1/mcp/tool/execute - Execute MCP Tool

Execute an MCP tool directly (see detailed examples above):

curl -X POST http://localhost:8080/v1/mcp/tool/execute \
  -H "Content-Type: application/json" \
  -d '{
    "id": "call_123",
    "type": "function", 
    "function": {
      "name": "read_file",
      "arguments": "{\"path\": \"config.json\"}"
    }
  }'

# Response - Tool execution result
{
  "role": "tool",
  "content": "{\n  \"providers\": {\n    ...\n  }\n}",
  "tool_call_id": "call_123"
}

Error Responses

All endpoints return consistent error responses:

// 400 Bad Request
{
  "error": {
    "message": "Invalid request format: missing required field 'name'",
    "type": "invalid_request"
  }
}

// 500 Internal Server Error  
{
  "error": {
    "message": "Failed to connect to MCP client: connection timeout",
    "type": "internal_error"
  }
}

Management Workflow Example

Complete client lifecycle management via API:

# 1. Add a new client
curl -X POST http://localhost:8080/api/mcp/client \
  -H "Content-Type: application/json" \
  -d '{
    "name": "temp-filesystem",
    "connection_type": "stdio",
    "stdio_config": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  }'

# 2. Check client status
curl -X GET http://localhost:8080/api/mcp/clients | jq '.[] | select(.name=="temp-filesystem")'

# 3. Restrict to safe tools only
curl -X PUT http://localhost:8080/api/mcp/client/temp-filesystem \
  -H "Content-Type: application/json" \
  -d '{
    "tools_to_execute": ["read_file", "list_directory"]
  }'

# 4. Test tool execution
curl -X POST http://localhost:8080/v1/mcp/tool/execute \
  -H "Content-Type: application/json" \
  -d '{
    "id": "test_call",
    "type": "function",
    "function": {
      "name": "list_directory", 
      "arguments": "{\"path\": \".\"}"
    }
  }'

# 5. Remove when done
curl -X DELETE http://localhost:8080/api/mcp/client/temp-filesystem

Environment Variables

Required Variables for MCP Servers

# Filesystem tools
export HOME="/home/user"

# Web search
export SEARCH_API_KEY="your-search-api-key"

# Database
export DATABASE_URL="postgresql://user:pass@localhost/db"

# Git tools
export GIT_AUTHOR_NAME="Your Name"
export GIT_AUTHOR_EMAIL="you@example.com"

# Custom MCP servers
export YOUR_MCP_SERVER_API_KEY="your-key"

Docker with MCP

⚠️ Important: Docker currently does NOT support STDIO connection for MCP. Use Go binary if STDIO connection is required.

# For HTTP/SSE MCP connections only
docker run -p 8080:8080 \
  -v $(pwd)/config.json:/app/config/config.json \
  -e OPENAI_API_KEY \
  -e SEARCH_API_KEY \
  -e MCP_CONNECTION_STRING \
  -e MCP_SSE_CONNECTION_STRING \
  -e APP_PLUGINS=maxim \
  maximhq/bifrost

Go Binary with MCP (Supports all connection types)

# All environment variables are picked up automatically
export OPENAI_API_KEY="your-openai-key"
export SEARCH_API_KEY="your-search-key"

go install github.com/maximhq/bifrost/transports/bifrost-http@latest
bifrost-http -config config.json -port 8080 -plugins maxim

Testing MCP Integration

Verify MCP Tools Are Available

# Make a request that should use tools
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "What files are in this directory?"}
    ]
  }'

Test Manual Tool Execution

# Test filesystem tool
curl -X POST http://localhost:8080/v1/mcp/tool/execute \
  -H "Content-Type: application/json" \
  -d '{
    "id": "test_call",
    "type": "function",
    "function": {
      "name": "list_directory",
      "arguments": "{\"path\": \".\"}"
    }
  }'

Check Server Logs

# Look for MCP connection logs
docker logs bifrost-container | grep MCP

# Expected output:
# [Bifrost MCP] MCP Manager initialized
# [Bifrost MCP] Connected to MCP client: filesystem

Multi-Tool Workflow Example

Complete Configuration

{
  "providers": {
    "openai": {
      "keys": [
        {
          "value": "env.OPENAI_API_KEY",
          "models": ["gpt-4o-mini"],
          "weight": 1.0
        }
      ]
    }
  },
  "mcp": {
    "client_configs": [
      {
        "name": "filesystem",
        "connection_type": "stdio",
        "stdio_config": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem"]
        }
      },
      {
        "name": "web-search",
        "connection_type": "stdio",
        "stdio_config": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-web-search"],
          "envs": ["SEARCH_API_KEY"]
        }
      }
    ]
  }
}

Complex Request

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Search the web for the latest Node.js version, then create a package.json file with that version"
      }
    ]
  }'

Architecture: For MCP system design and performance details, see Architecture Documentation.

​MCP Overview (File Based)

​Connection Types

​STDIO Connection

​HTTP Connection

​SSE Connection

​Popular MCP Servers

​Filesystem Tools

​Web Search

​Database Access

​Git Integration

​Tool Filtering

​Whitelist Approach

​Blacklist Approach

​Using MCP Tools via HTTP

​Automatic Tool Integration

​Manual Tool Execution

​Multi-Turn Conversations with MCP Tools

​Request-Level Tool Filtering

​MCP Management API Endpoints

​GET /api/mcp/clients - List All MCP Clients

​POST /api/mcp/client - Add New MCP Client

​PUT /api/mcp/client/ - Edit Client Tools

​DELETE /api/mcp/client/ - Remove MCP Client

​POST /api/mcp/client//reconnect - Reconnect Client

​POST /v1/mcp/tool/execute - Execute MCP Tool

​Error Responses

​Management Workflow Example

​Environment Variables

​Required Variables for MCP Servers

​Docker with MCP

​Go Binary with MCP (Supports all connection types)

​Testing MCP Integration

​Verify MCP Tools Are Available

​Test Manual Tool Execution

​Check Server Logs

​Multi-Tool Workflow Example

​Complete Configuration

​Complex Request