Configuration

MCP Gateway is configured through YAML files. The configuration lives at ~/.mcp-gateway/config.yaml (or MCP_CONFIG_PATH).

File Locations

Location	Scope	Priority
~/.mcp-gateway/config.yaml	Global	Default

tip

You can override the config path with MCP_CONFIG_PATH.

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 workspaces	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: + workspaces: is 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 are resolved in layers, with higher priority sources overriding lower ones.

Resolution Order (Priority)

Priority	Source	Location
5 (highest)	CWD .env	Current working directory
4	Workspace root .env	Matched workspace path
3	Profile/Workspace env:	config.yaml env blocks
2	Gateway .env	~/.mcp-gateway/.env
1 (lowest)	System environment	OS-level variables

Gateway .env (global secrets)

Shared across all workspaces. Store API keys and tokens you use everywhere.

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

Profile/Workspace env: (config-defined)

Variables defined in config.yaml. Can reference gateway .env variables with ${VAR} syntax.

profiles:
  supabase-prod:
    env:
      SUPABASE_ACCESS_TOKEN: ${SUPABASE_PROD_TOKEN}  # From gateway .env

Workspace .env (local overrides)

Project-specific values that override everything above.

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

CWD .env (highest priority)

For monorepos or subdirectory-specific overrides. Only loaded if different from workspace root.

# /my-workspace/packages/api/.env
DEBUG=false  # Overrides workspace root's DEBUG=true
PORT=3001

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

Validate & Export

Validate your config file:

manage_config(action="validate")

Export a masked YAML copy (secrets redacted, ${VAR} placeholders preserved):

manage_config(action="export")

To inspect a specific server’s effective config (including required env vars):

get_server_config(server="supabase")

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

manage_config(action="validate")

Reports syntax errors and invalid values. For missing credentials, use get_server_config(server="...") to see required ${VAR} placeholders.

Hot Reload

Configuration changes are picked up automatically on the next request. No restart required.

tip

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