Skip to content

CONFIG.md

Latest commit

 

History

History
591 lines (449 loc) · 10.8 KB

CONFIG.md

File metadata and controls

591 lines (449 loc) · 10.8 KB

Configuration Reference

Overview

The MCP Bridge uses YAML configuration files to define bridge settings and MCP server configurations. This document provides a complete reference for all available configuration options.

Configuration Structure

The configuration file has two main sections:

bridge:                    # Bridge-level settings
  port: 8080
  # ... bridge options

servers:                   # Server configurations
  server_name:            # Key = namespace
    name: "server_name"
    # ... server options

Required Fields

The following fields are required and will cause validation errors if missing:

  • bridge.port - Bridge listening port
  • bridge.allowed_origins - CORS origins list (at least one required)
  • servers.{name}.binary - Server executable path
  • servers.{name}.args - Server command arguments

Bridge Settings

Bridge settings control the HTTP server behavior and global options.

port (required)

The port number the bridge listens on.

  • Type: Integer
  • Required: Yes
  • Default: None (must be specified)
  • Example: 8080
bridge:
  port: 8080

Notes:

  • Must be greater than 0
  • Must not be in use by another process
  • Common ports: 8080, 3000, 8000

allowed_origins (required)

CORS origins that are allowed to connect to the bridge.

  • Type: Array of strings
  • Required: Yes (at least one)
  • Default: None
  • Example:
bridge:
  allowed_origins:
    - http://localhost:3000
    - http://127.0.0.1:3000

Notes:

  • Include protocol (http:// or https://)
  • Include port if not standard (80, 443)
  • Multiple origins allowed
  • Use wildcard (*) only in development

allowed_hosts (optional)

Host header whitelist to prevent host header injection attacks.

  • Type: Array of strings
  • Required: No
  • Default: ["localhost", "127.0.0.1"]
  • Example:
bridge:
  allowed_hosts:
    - localhost
    - 127.0.0.1
    - api.example.com

request_timeout (optional)

Maximum time allowed for HTTP requests to complete.

  • Type: Duration string
  • Required: No
  • Default: 30s
  • Example: 60s
bridge:
  request_timeout: 30s

Valid formats: s (seconds), m (minutes), h (hours)

Use case: Increase for slow MCP servers that take time to process requests.

idle_timeout (optional)

Maximum time an idle connection can remain open before being closed.

  • Type: Duration string
  • Required: No
  • Default: 5m
  • Example: 10m
bridge:
  idle_timeout: 5m

Use case:

  • Shorter timeouts: Clean up stale connections faster
  • Longer timeouts: Support long-running sessions

connection_limit (optional)

Maximum number of concurrent connections allowed.

  • Type: Integer
  • Required: No
  • Default: 5
  • Example: 10
bridge:
  connection_limit: 5

Notes:

  • Higher limits support more concurrent clients
  • Lower limits protect against DoS attacks
  • Consider your server capacity

request_size_limit (optional)

Maximum size of HTTP request bodies.

  • Type: Integer (bytes)
  • Required: No
  • Default: 1048576 (1 MB)
  • Example: 2097152 (2 MB)
bridge:
  request_size_limit: 1048576

Security: Prevents DoS attacks via large payloads

response_size_limit (optional)

Maximum size of HTTP response bodies.

  • Type: Integer (bytes)
  • Required: No
  • Default: 10485760 (10 MB)
  • Example: 52428800 (50 MB)
bridge:
  response_size_limit: 10485760

Use case: Increase for tools that return large outputs

Server Settings

Server configurations define individual MCP servers. Each server has a unique namespace key.

Per-Server Configuration

servers:
  server_name:
    name: "server_name"
    binary: "/path/to/binary"
    args: ["arg1", "arg2"]
    env:
      VAR: "value"
    timeout: 30s
    max_restarts: 3
    auto_start: true

name (required)

Server identifier (namespace). Used in URL paths.

  • Type: String
  • Required: Yes
  • Example: "git"
servers:
  git:
    name: "git"

URL paths:

  • SSE: /mcp/git
  • POST: /mcp/git/message

Rules:

  • Alphanumeric characters
  • Hyphens allowed
  • No spaces or special characters
  • Case-sensitive

binary (required)

Path to the server executable.

  • Type: String
  • Required: Yes
  • Example: /usr/bin/node or npx
servers:
  git:
    binary: "npx"
    args: ["-y", "@modelcontextprotocol/server-git"]

Notes:

  • Can be absolute path or binary in PATH
  • Must be executable
  • Security: Path is validated to prevent injection

args (required)

Command-line arguments for the server.

  • Type: Array of strings
  • Required: Yes
  • Example:
servers:
  filesystem:
    binary: "/usr/bin/node"
    args:
      - "/path/to/server/index.js"
      - "--allowed-directory=/data"

Notes:

  • Each argument is a separate array element
  • No shell expansion (arguments are literal)
  • Security: Arguments are sanitized

env (optional)

Environment variables for the server process.

  • Type: Map of strings
  • Required: No
  • Example:
servers:
  git:
    binary: "npx"
    args: ["-y", "@modelcontextprotocol/server-git"]
    env:
      REPO_PATH: "/path/to/repo"
      API_KEY: "${API_KEY}"

Notes:

  • Environment variables are inherited from parent process
  • Additional variables can be added here
  • Supports environment variable interpolation

timeout (optional)

Per-server timeout for request processing.

  • Type: Duration string
  • Required: No
  • Default: 30s
  • Example: 60s
servers:
  filesystem:
    timeout: 30s
  git:
    timeout: 60s

Use case:

  • Fast servers: Short timeout (10-30s)
  • Slow servers: Long timeout (60-120s)
  • File operations: Longer timeout recommended

max_restarts (optional)

Maximum number of times the server can restart after crashing.

  • Type: Integer
  • Required: No
  • Default: 3
  • Example: 5
servers:
  unstable:
    max_restarts: 5

Behavior: Exponential backoff between restarts:

  • 1st restart: 1 second
  • 2nd restart: 2 seconds
  • 3rd restart: 4 seconds
  • ...
  • Maximum: 60 seconds

Use case:

  • Stable servers: Lower limit (2-3)
  • Unstable servers: Higher limit (5-10)
  • Production: Monitor and fix root cause

auto_start (optional)

Whether to start the server when the bridge starts.

  • Type: Boolean
  • Required: No
  • Default: false
  • Example: true
servers:
  always_ready:
    auto_start: true
  on_demand:
    auto_start: false

Use case:

  • true: Server starts immediately (faster first request)
  • false: Server starts on first request (saves resources)

allowed_args (optional)

Whitelist of allowed arguments for this server.

  • Type: Array of strings
  • Required: No
  • Default: None (all allowed)
  • Example:
servers:
  filesystem:
    binary: "uvx"
    args: ["mcp-server-filesystem"]
    allowed_args:
      - "--allowed-directory=/data"
      - "--read-only"

Security: Restricts which arguments can be passed

Environment Variable Interpolation

Configuration supports environment variable interpolation using ${VAR_NAME} syntax.

Syntax

servers:
  git:
    env:
      REPO_PATH: "/home/user/${REPO_NAME}"
      API_KEY: "${API_KEY}"

Behavior:

  • ${VAR_NAME} - Replaced with environment variable value
  • Expanded at configuration load time
  • No shell expansion (literal string replacement)

Examples

servers:
  git:
    env:
      REPO_PATH: "/data/${REPO_NAME}"
      API_KEY: "${API_KEY}"
      DEBUG: "${DEBUG:-false}"  # Default if not set

Security Considerations:

  • No shell command execution
  • No command injection
  • Values are literal strings
  • Best practice: Use secrets manager for sensitive values

Complete Example

bridge:
  port: 8080
  allowed_origins:
    - http://localhost:3000
    - http://127.0.0.1:3000
  request_timeout: 30s
  idle_timeout: 5m
  connection_limit: 5
  request_size_limit: 1048576
  response_size_limit: 10485760

servers:
  filesystem:
    name: "filesystem"
    binary: "/usr/bin/node"
    args:
      - "/path/to/mcp-filesystem-server/index.js"
    env:
      HOME: "/home/user"
      PORT: "8081"
    timeout: 30s
    max_restarts: 3
    auto_start: true

  git:
    name: "git"
    binary: "npx"
    args:
      - "-y"
      - "@modelcontextprotocol/server-git"
    env:
      REPO_PATH: "/path/to/repo"
    timeout: 60s
    max_restarts: 5
    auto_start: false

Validation Rules

Validation Errors

The configuration is validated on load. Common errors:

config error: field bridge.port - port must be greater than 0
config error: field bridge.allowed_origins - at least one allowed origin is required
config error: field servers - at least one server is required
server config error: git field binary - binary is required

Common Issues

  1. Port in use: Choose a different port
  2. No servers: Add at least one server
  3. Missing binary: Provide absolute path or PATH binary
  4. Invalid YAML: Check indentation and syntax
  5. Env var not set: Set the environment variable or use default

Tips

Performance Tuning

# High-traffic deployment
bridge:
  connection_limit: 10
  request_timeout: 60s

# Fast servers
servers:
  fast:
    timeout: 10s
    auto_start: true

# Slow servers (filesystem)
servers:
  filesystem:
    timeout: 60s
    auto_start: true

Security Best Practices

# Restrict CORS to trusted origins
bridge:
  allowed_origins:
    - http://localhost:3000

# Restrict hosts
bridge:
  allowed_hosts:
    - localhost
    - 127.0.0.1

# Use allowed_args to restrict server arguments
servers:
  filesystem:
    allowed_args:
      - "--allowed-directory=/data"
      - "--read-only"

Reliability

# Monitor restart counts
servers:
  unstable:
    max_restarts: 5
    timeout: 30s

# Use health checks
bridge:
  request_timeout: 30s

Troubleshooting

Binary Not Found

Symptom: Server won't start

Solution:

# Check if binary exists
which npx
ls -la /usr/bin/node

# Use absolute path
binary: "/usr/bin/node"

Port Conflict

Symptom: Bridge won't start

Solution:

# Check if port is in use
lsof -i :8080

# Use different port
bridge:
  port: 8081

Permission Denied

Symptom: Subprocess can't execute

Solution:

# Check permissions
ls -la /path/to/binary

# Make executable
chmod +x /path/to/binary

Environment Variables Not Set

Symptom: Server fails with missing env vars

Solution:

# Set environment variables
export REPO_PATH=/path/to/repo

# Or in config
servers:
  git:
    env:
      REPO_PATH: "/path/to/repo"

For more configuration examples, see EXAMPLES.md.