Configuration files support using ${VAR:default} syntax for environment variable injection. If environment variables are not set, default values will be used.

A common practice is to inject through different .env, .env.development, .env.prod files, though you can also directly modify the configuration to hardcode a value.

​
Basic Configuration

port: ${MCP_GATEWAY_PORT:5235}                      # Service listening port
pid: "${MCP_GATEWAY_PID:/var/run/mcp-gateway.pid}"  # PID file path

The PID here should be consistent with the PIDs mentioned below, used for service management and hot reload functionality.

​
Storage Configuration

The storage configuration module is mainly used to store gateway proxy configuration information. Currently supports two storage methods:

disk storage

Configurations are stored as files on disk, with each configuration as a separate file, similar to nginx vhost

db storage

Store in database, each configuration is a record, supports SQLite3, PostgreSQL, MySQL

​
Configuration Example

storage:
  type: "${GATEWAY_STORAGE_TYPE:db}"                    # Storage type: db, disk

  # Database configuration (used when type is 'db')
  database:
    type: "${GATEWAY_DB_TYPE:sqlite}"                   # Database type (sqlite, postgres, mysql)
    host: "${GATEWAY_DB_HOST:localhost}"                # Database host address
    port: ${GATEWAY_DB_PORT:5432}                       # Database port
    user: "${GATEWAY_DB_USER:postgres}"                 # Database username
    password: "${GATEWAY_DB_PASSWORD:example}"          # Database password
    dbname: "${GATEWAY_DB_NAME:./data/mcp-gateway.db}"  # Database name or file path
    sslmode: "${GATEWAY_DB_SSL_MODE:disable}"           # SSL mode for database connection

  # Disk configuration (used when type is 'disk')
  disk:
    path: "${GATEWAY_STORAGE_DISK_PATH:}"               # Data file storage path

​
Notification Configuration

The notification configuration module is mainly used to let mcp-gateway detect updates and perform hot reloads without restarting the service when configuration updates occur.

​
Supported Notification Methods

signal

Notify by sending operating system signals, similar to kill -SIGHUP <pid> or nginx -s reload

api

Notify by calling an API, mcp-gateway will listen on an independent port

redis

Notify through redis publish/subscribe functionality, suitable for single machine or cluster deployment

composite

Composite notification, combining multiple methods, signal and api are always enabled by default

​
Notification Role Description

​
Configuration Example

notifier:
  role: "${NOTIFIER_ROLE:receiver}" # Role: 'sender' or 'receiver'
  type: "${NOTIFIER_TYPE:signal}"   # Type: 'signal', 'api', 'redis' or 'composite'

  # Signal configuration (used when type is 'signal')
  signal:
    signal: "${NOTIFIER_SIGNAL:SIGHUP}"                     # Signal to send
    pid: "${NOTIFIER_SIGNAL_PID:/var/run/mcp-gateway.pid}"  # PID file path

  # API configuration (used when type is 'api')
  api:
    port: ${NOTIFIER_API_PORT:5235}                                         # API port
    target_url: "${NOTIFIER_API_TARGET_URL:http://localhost:5235/_reload}"  # Reload endpoint

  # Redis configuration (used when type is 'redis')
  redis:
    addr: "${NOTIFIER_REDIS_ADDR:localhost:6379}"                               # Redis address
    password: "${NOTIFIER_REDIS_PASSWORD:UseStrongPasswordIsAGoodPractice}"     # Redis password
    db: ${NOTIFIER_REDIS_DB:0}                                                  # Redis database number
    topic: "${NOTIFIER_REDIS_TOPIC:mcp-gateway:reload}"                         # Redis publish/subscribe topic

​
Session Storage Configuration

Session storage configuration is used to store session information in MCP. Different storage methods can be chosen based on different deployment scenarios:

memory storage

Memory storage, suitable for single machine deployment (note: restart will lose session information)

redis storage

Redis storage, suitable for single machine or cluster deployment, supports persistence

​
Configuration Example

session:
  type: "${SESSION_STORAGE_TYPE:memory}"                    # Storage type: memory, redis
  redis:
    addr: "${SESSION_REDIS_ADDR:localhost:6379}"            # Redis address
    password: "${SESSION_REDIS_PASSWORD:}"                  # Redis password
    db: ${SESSION_REDIS_DB:0}                               # Redis database number
    topic: "${SESSION_REDIS_TOPIC:mcp-gateway:session}"     # Redis publish/subscribe topic

When using memory storage, service restart will cause all session information to be lost. Redis storage is recommended for production environments.

​
Forward Headers Configuration

The forward headers configuration allows the MCP Gateway to forward HTTP headers from client requests to downstream services. This feature is useful for authentication, request tracing, and custom header propagation.

Forward headers functionality is disabled by default for backward compatibility. Enable it by setting enabled: true in the configuration.

​
Features

Header Filtering

Control which headers are forwarded using allow/ignore lists with case-insensitive matching

Client Headers

Forward headers from client requests (tools/list and tools/call) to downstream services

Argument Headers

Support forwarding headers passed as tool arguments via configurable parameter names

Override Control

Choose whether to override existing headers or add to them

​
Configuration Options

forward:
  enabled: ${FORWARD_ENABLED:false}                                     # Enable forward headers (default: false)
  
  mcp_arg:
    key_for_header: "${FORWARD_MCP_ARG_KEY_FOR_HEADER:__forwardHeaders}" # Parameter name for tool arguments
  
  header:
    allow_headers: "${FORWARD_ALLOW_HEADERS:}"                          # Comma-separated list of allowed headers (takes priority)
    ignore_headers: "${FORWARD_IGNORE_HEADERS:Accept, Accept-Encoding, Accept-Language, Host, Cookie, Connection, User-Agent, Content-Length, Content-Type}" # Headers to ignore
    case_insensitive: ${FORWARD_HEADER_CASE_INSENSITIVE:true}           # Case insensitive header matching
    override_existing: ${FORWARD_HEADER_OVERRIDE_EXISTING:false}        # Override existing headers instead of adding

​
Header Filtering Logic

The filtering logic follows a priority-based approach:

1

Priority Check

If allow_headers is configured (non-empty), it takes priority and ignore_headers is completely ignored

2

Allow List Mode

When allow_headers is set, only headers in this list are forwarded, all others are ignored

3

Ignore List Mode

When allow_headers is empty, headers in ignore_headers list are filtered out, others are forwarded

4

Case Sensitivity

Header matching respects the case_insensitive setting for both allow and ignore lists

​
Usage Examples

​
Example 1: Allow Only Specific Headers

forward:
  enabled: true
  header:
    allow_headers: "Authorization, X-API-Key, X-Request-ID"
    ignore_headers: "Host, Cookie"  # This will be ignored
    case_insensitive: true

Result: Only Authorization, X-API-Key, and X-Request-ID headers are forwarded.

​
Example 2: Block Specific Headers

forward:
  enabled: true
  header:
    allow_headers: ""  # Empty - use ignore list instead
    ignore_headers: "Accept, Host, Cookie, User-Agent"
    case_insensitive: true

Result: All headers except Accept, Host, Cookie, and User-Agent are forwarded.

​
Example 3: Tool Argument Headers

forward:
  enabled: true
  mcp_arg:
    key_for_header: "custom_headers"
  header:
    override_existing: true

Tools can now pass headers via the custom_headers argument:

{
  "name": "api_call",
  "arguments": {
    "url": "https://api.example.com/data",
    "custom_headers": {
      "Authorization": "Bearer token123",
      "X-Custom-Header": "value"
    }
  }
}

​
Environment Variables

All forward headers settings can be configured via environment variables:

# Enable the feature
FORWARD_ENABLED=true

# Configure header forwarding behavior
FORWARD_MCP_ARG_KEY_FOR_HEADER=__forwardHeaders
FORWARD_ALLOW_HEADERS="Authorization, X-API-Key"
FORWARD_IGNORE_HEADERS="Accept, Host, Cookie"
FORWARD_HEADER_CASE_INSENSITIVE=true
FORWARD_HEADER_OVERRIDE_EXISTING=false

When enabling forward headers in production, carefully review which headers should be forwarded to avoid security risks such as exposing sensitive authentication tokens or cookies.

​
Configuration File Location

By default, configuration files should be placed in the following locations:

  • Container deployment: /app/configs/mcp-gateway.yaml
  • Binary deployment: ./configs/mcp-gateway.yaml

​
Hot Reload Mechanism

MCP Gateway supports hot reload configuration, allowing new configurations to be applied without restarting the service:

1

Configuration Update Detection

When configuration changes occur, reload is triggered through configured notification methods (signal, api, redis)

2

Configuration Validation

Before reloading, the validity of the new configuration is verified to ensure stable service operation

3

Smooth Transition

After validation passes, smoothly switch to the new configuration without interrupting ongoing connections

​
Best Practices