Configuration

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

File Locations

Location	Scope	Priority
~/.mcp-gateway/config.yaml	Global (all projects)	Lowest
./.mcp-gateway.yaml	Project-specific	Highest

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

Profiles & Workspaces

The gateway uses profiles (reusable bundles of servers, capabilities, and credentials) and workspaces (directories that inherit from profiles).

Profile Structure

A profile bundles everything needed for a specific service or environment:

profiles:
  supabase-prod:
    capabilities: [supabase, database, postgres]
    servers:
      supabase:
        url: https://mcp.supabase.com/mcp?project_ref=${SUPABASE_PROJECT_REF}
        auth:
          type: bearer
          token: ${SUPABASE_ACCESS_TOKEN}
    env:
      SUPABASE_PROJECT_REF: prod-abcd1234
      SUPABASE_ACCESS_TOKEN: ${SUPABASE_PROD_TOKEN}  # From ~/.mcp-gateway/.env

Workspace Structure

A workspace maps a directory to one or more profiles:

workspaces:
  my-app:
    path: /home/user/my-app
    profiles: [supabase-prod, github-work, context7]

When you work in /home/user/my-app, the gateway automatically merges all three profiles—combining their capabilities, servers, and environment variables.

Why Profiles?

Scenario	Without Profiles	With Profiles
Same server, different credentials	Duplicate server configs	Separate profiles (supabase-prod, supabase-staging)
Share credentials across projects	Copy .env files everywhere	Reference same profile
Switch environments	Edit config or .env	Change profile list

Basic Structure (Legacy)

info

The servers: + projects: format below still works but profiles are recommended for new setups.

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

Environment variables can be stored in two locations:

Gateway .env (shared defaults)

# ~/.mcp-gateway/.env
SUPABASE_PROD_TOKEN=sbp_prod_xxxxx
SUPABASE_STAGING_TOKEN=sbp_staging_xxxxx
GITHUB_WORK_TOKEN=ghp_work_xxxxx

Workspace .env (local overrides)

# /my-project/.env
GITHUB_TOKEN=ghp_project_specific_xxxxx  # Overrides gateway default
DEBUG=true

Workspace .env has highest priority—use it to override gateway defaults for specific projects.

Security

Never commit .env files to version control. Add .env to your .gitignore.

Complete Example

# ~/.mcp-gateway/config.yaml

settings:
  port: 8989
  host: "127.0.0.1"

profiles:
  # Supabase production
  supabase-prod:
    capabilities: [supabase, database, postgres]
    servers:
      supabase:
        url: https://mcp.supabase.com/mcp?project_ref=${SUPABASE_PROJECT_REF}
        auth:
          type: bearer
          token: ${SUPABASE_ACCESS_TOKEN}
    env:
      SUPABASE_PROJECT_REF: prod-abcd1234
      SUPABASE_ACCESS_TOKEN: ${SUPABASE_PROD_TOKEN}

  # Supabase staging
  supabase-staging:
    capabilities: [supabase, database, postgres]
    servers:
      supabase:
        url: https://mcp.supabase.com/mcp?project_ref=${SUPABASE_PROJECT_REF}
        auth:
          type: bearer
          token: ${SUPABASE_ACCESS_TOKEN}
    env:
      SUPABASE_PROJECT_REF: staging-5678
      SUPABASE_ACCESS_TOKEN: ${SUPABASE_STAGING_TOKEN}

  # GitHub with work credentials
  github-work:
    capabilities: [github, git]
    servers:
      github:
        transport: stdio
        command: npx
        args: [-y, "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_WORK_TOKEN}

  # Context7 for documentation (no credentials needed)
  context7:
    capabilities: [docs, libraries]
    servers:
      context7:
        url: https://mcp.context7.com/mcp

workspaces:
  # Production app
  my-app:
    path: /home/user/my-app
    profiles: [supabase-prod, github-work, context7]

  # Staging environment
  my-app-staging:
    path: /home/user/my-app-staging
    profiles: [supabase-staging, github-work, context7]

# ~/.mcp-gateway/.env
SUPABASE_PROD_TOKEN=sbp_prod_xxxxx
SUPABASE_STAGING_TOKEN=sbp_staging_xxxxx
GITHUB_WORK_TOKEN=ghp_work_xxxxx

HTTP Security (Optional)

info

No authentication required for localhost. By default, the gateway accepts unauthenticated requests from 127.0.0.1. Token authentication is only needed for remote access or additional security.

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

Remote Access

When binding to 0.0.0.0 for network access, authentication is required. The gateway will refuse to start without a token configured.

Port Configuration

The gateway defaults to port 8989. Override via:

Method	Example	Priority
CLI flag	mcpg start --port 9000	Highest
Environment	MCP_GATEWAY_PORT=9000	Medium
Config file	gateway.port: 9000	Lowest

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.

tip

Add a new server to your config and it's immediately available—no need to restart terminals or the gateway.