Configuration

MCP Gateway is configured through YAML files. The global configuration lives at~/.mcp-gateway/config.yaml, with optional project-specific overrides.

File Locations

Project-specific configurations are merged with global settings. Project settings take precedence when there are conflicts.

Basic Structure

servers:
  context7:
    url: https://mcp.context7.com/mcp
    scope: global

  supabase:
    url: https://mcp.supabase.com/mcp
    env:
      SUPABASE_PROJECT_REF: "${SUPABASE_PROJECT_REF}"
      SUPABASE_ACCESS_TOKEN: "${SUPABASE_ACCESS_TOKEN}"
    scope: workspace

Server Configuration Options

url (required for HTTP servers)

The HTTP endpoint for the MCP server.

url: "https://mcp.context7.com/mcp"
url: "http://localhost:9001/mcp"

command / args (for local servers)

For servers that need to be spawned locally.

command: "docker"
args: ["run", "-i", "--rm", "mcp/fetch:latest"]

env (optional)

Environment variables for the server. Use ${VAR} syntax to reference variables from your .env file.

"env": {
  "GITHUB_TOKEN": "${GITHUB_TOKEN}",
  "DEBUG": "true"
}

scope (optional)

Determines how the server is shared. See Scoping for details.

• "global" — Shared by all terminals (default)
• "workspace" — One instance per workspace/project
• "credential" — One instance per unique credential set

transport (optional)

How to connect to the server. See Server Types.

• "stdio" — Standard input/output (default)
• "http" — HTTP API
• "docker" — Docker container

Environment Variables

Create a .env file in your project root for sensitive credentials:

# .env
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_KEY=eyJhbGciOiJIUzI1...

Complete Example

# ~/.mcp-gateway/config.yaml

gateway:
  port: 8989
  host: "127.0.0.1"

servers:
  context7:
    url: https://mcp.context7.com/mcp
    scope: global
    description: "Library documentation lookup"

  supabase:
    url: https://mcp.supabase.com/mcp
    env:
      SUPABASE_PROJECT_REF: "${SUPABASE_PROJECT_REF}"
      SUPABASE_ACCESS_TOKEN: "${SUPABASE_ACCESS_TOKEN}"
    scope: workspace
    description: "Supabase database access"

  github:
    url: https://api.github.com/mcp
    env:
      GITHUB_TOKEN: "${GITHUB_TOKEN}"
    scope: credential
    description: "GitHub API access"

  fetch:
    command: docker
    args: ["run", "-i", "--rm", "mcp/fetch:latest"]
    scope: global
    description: "Web content fetching"

projects:
  my-app:
    path: /home/user/my-app
    capabilities: [supabase, github]

HTTP Security (Optional)

To enable token authentication:

# Generate a token
mcpg enable-http

# View current token
mcpg show-token

# Rotate token (invalidates old)
mcpg rotate-token

# Disable auth (localhost only)
mcpg disable-http

When auth is enabled, include the token in requests:

Authorization: Bearer mcp_xxxxxxxxxxxxxxxxxxxx

Port Configuration

The gateway defaults to port 8989. Override via:

Validating Configuration

mcpg validate

Reports syntax errors, missing environment variables, and unreachable servers.

Hot Reload

The gateway watches configuration files and automatically reloads when they change. No restart required.