Configuration Reference¶

This guide provides comprehensive configuration options for MCP Gateway, including database setup, environment variables, and deployment-specific settings.

🔐 Required: Change Before Use¶

These variables have insecure defaults and must be changed before production deployment:

Copy .env.example to .env and update these values.

🔒 Security Defaults (Secure by Default)¶

These settings are enabled by default for security—only disable for backward compatibility:

⚙️ Project Defaults (Dev Setup)¶

These values in .env.example differ from code defaults to provide a working local/dev setup:

🗄️ Database Configuration¶

MCP Gateway supports multiple database backends with full feature parity across all supported systems.

Supported Databases¶

PostgreSQL System Dependencies¶

sudo apt-get install libpq-dev

sudo dnf install postgresql-devel

brew install libpq

pip install .[postgres]

MariaDB/MySQL Setup Details¶

Connection String Format¶

DATABASE_URL=mysql+pymysql://[username]:[password]@[host]:[port]/[database]

Local MariaDB/MySQL Installation¶

# Install MariaDB server
sudo apt update && sudo apt install mariadb-server

# Secure installation (optional)
sudo mariadb-secure-installation

# Create database and user
sudo mariadb -e "CREATE DATABASE mcp;"
sudo mariadb -e "CREATE USER 'mysql'@'localhost' IDENTIFIED BY 'changeme';"
sudo mariadb -e "GRANT ALL PRIVILEGES ON mcp.* TO 'mysql'@'localhost';"
sudo mariadb -e "FLUSH PRIVILEGES;"

# Install MySQL server
sudo apt update && sudo apt install mysql-server

# Secure installation (optional)
sudo mysql_secure_installation

# Create database and user
sudo mysql -e "CREATE DATABASE mcp;"
sudo mysql -e "CREATE USER 'mysql'@'localhost' IDENTIFIED BY 'changeme';"
sudo mysql -e "GRANT ALL PRIVILEGES ON mcp.* TO 'mysql'@'localhost';"
sudo mysql -e "FLUSH PRIVILEGES;"

# Install MariaDB
brew install mariadb
brew services start mariadb

# Create database and user
mariadb -u root -e "CREATE DATABASE mcp;"
mariadb -u root -e "CREATE USER 'mysql'@'localhost' IDENTIFIED BY 'changeme';"
mariadb -u root -e "GRANT ALL PRIVILEGES ON mcp.* TO 'mysql'@'localhost';"
mariadb -u root -e "FLUSH PRIVILEGES;"

Docker MariaDB/MySQL Setup¶

# Start MariaDB container (recommended)
docker run -d --name mariadb-mcp \
  -e MYSQL_ROOT_PASSWORD=mysecretpassword \
  -e MYSQL_DATABASE=mcp \
  -e MYSQL_USER=mysql \
  -e MYSQL_PASSWORD=changeme \
  -p 3306:3306 \
  registry.redhat.io/rhel9/mariadb-106:12.0.2-ubi10

# Or start MySQL container
docker run -d --name mysql-mcp \
  -e MYSQL_ROOT_PASSWORD=mysecretpassword \
  -e MYSQL_DATABASE=mcp \
  -e MYSQL_USER=mysql \
  -e MYSQL_PASSWORD=changeme \
  -p 3306:3306 \
  mysql:8

# Connection string for MCP Gateway (same for both)
DATABASE_URL=mysql+pymysql://mysql:changeme@localhost:3306/mcp

🔧 Environment Variables Reference¶

Basic Settings¶

Authentication¶

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token ...)
curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/api/...

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key)

UI Features¶

A2A (Agent-to-Agent) Features¶

Configuration Effects:

• MCPGATEWAY_A2A_ENABLED=false: Completely disables A2A features (API endpoints return 404, admin tab hidden)
• MCPGATEWAY_A2A_METRICS_ENABLED=false: Disables metrics collection while keeping functionality

ToolOps¶

ToolOps streamlines the entire workflow by enabling seamless tool enrichment, automated test case generation, and comprehensive tool validation.

LLM Chat MCP Client¶

The LLM Chat MCP Client allows you to interact with MCP servers using conversational AI from multiple LLM providers.

Azure OpenAI Configuration:

OpenAI Configuration:

Anthropic Claude Configuration:

AWS Bedrock Configuration:

IBM WatsonX AI Configuration:

Ollama Configuration:

Provider Requirements:

• Azure OpenAI: Requires AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, and AZURE_OPENAI_DEPLOYMENT
• OpenAI: Requires OPENAI_API_KEY
• Anthropic: Requires ANTHROPIC_API_KEY and pip install langchain-anthropic
• AWS Bedrock: Requires AWS_BEDROCK_MODEL_ID and pip install langchain-aws boto3. Uses AWS credential chain if explicit credentials not provided.
• IBM WatsonX AI: Requires WATSONX_URL, WATSONX_APIKEY, WATSONX_PROJECT_ID, WATSONX_MODEL_ID and pip install langchain-ibm
• Ollama: Requires local Ollama instance running (default: http://localhost:11434)

Redis Configurations for Chat Sessions:

LLM Settings (Internal API)¶

The LLM Settings feature enables MCP Gateway to act as a unified LLM provider with an OpenAI-compatible API.

Gateway Provider Settings:

API Endpoints:

# List available models
curl -H "Authorization: Bearer $TOKEN" http://localhost:4444/v1/models

# Chat completion
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}' \
  http://localhost:4444/v1/chat/completions

Email-Based Authentication & User Management¶

MCP Client Authentication¶

SSO (Single Sign-On) Configuration¶

GitHub OAuth:

Google OAuth:

IBM Security Verify OIDC:

Keycloak OIDC:

Microsoft Entra ID OIDC:

Generic OIDC Provider (Auth0, Authentik, etc.):

Okta OIDC:

OAuth 2.0 Dynamic Client Registration (DCR) & PKCE¶

ContextForge implements OAuth 2.0 Dynamic Client Registration (RFC 7591) and PKCE (RFC 7636) for seamless integration with OAuth-protected MCP servers.

Personal Teams Configuration¶

MCP Server Catalog¶

Security¶

SSRF Protection¶

MCP Gateway includes Server-Side Request Forgery (SSRF) protection to prevent the gateway from being used to access internal resources or cloud metadata services.

Default Blocked Networks (always blocked regardless of other settings):

["169.254.169.254/32", "169.254.169.123/32", "fd00::1/128", "169.254.0.0/16", "fe80::/10"]

Default Blocked Hosts:

["metadata.google.internal", "metadata.internal"]

SSRF_PROTECTION_ENABLED=true
SSRF_ALLOW_LOCALHOST=true
SSRF_ALLOW_PRIVATE_NETWORKS=true

SSRF_PROTECTION_ENABLED=true
SSRF_ALLOW_LOCALHOST=false
SSRF_ALLOW_PRIVATE_NETWORKS=false

SSRF_BLOCKED_NETWORKS='["169.254.169.254/32","169.254.0.0/16","100.64.0.0/10"]'

Ed25519 Certificate Signing¶

MCP Gateway supports Ed25519 digital signatures for certificate validation and integrity verification.

Key Generation:

# Generate a new Ed25519 key pair
python mcpgateway/utils/generate_keys.py

Response Compression¶

MCP Gateway includes automatic response compression middleware that reduces bandwidth usage by 30-70% for text-based responses.

Logging¶

Observability (OpenTelemetry)¶

MCP Gateway includes vendor-agnostic OpenTelemetry support for distributed tracing. Works with Phoenix, Jaeger, Zipkin, Tempo, DataDog, New Relic, and any OTLP-compatible backend.

OTLP Configuration:

Performance Tuning:

Internal Observability & Tracing¶

The gateway includes built-in observability features for tracking HTTP requests, spans, and traces independent of OpenTelemetry.

Prometheus Metrics¶

Metrics Cleanup & Rollup¶

Transport¶

Federation¶

Resources¶

Tools¶

Prompts¶

Schema Validation¶

Strict Mode Scenarios:

• true (Default): Invalid schemas (e.g., unknown types, malformed JSON Schema) will cause registration to fail with a 400 error. This ensures that only valid, spec-compliant tools and prompts are registered, preventing runtime issues later.
• false: Invalid schemas will be logged as warnings but successfully persisted. Use this only for backward compatibility if you have legacy tools with broken schemas that cannot be immediately updated. Invalid schemas may still cause runtime errors when used by LLMs or downstream tools.

Health Checks¶

Database Connection Pool¶

Cache Backend¶

Tool Lookup Cache¶

Metrics Aggregation Cache¶

MCP Session Pool¶

Development¶

Well-Known URI Configuration¶

Header Passthrough Configuration¶

Plugin Configuration¶

HTTP Retry Configuration¶

CPU Spin Loop Mitigation¶

These settings mitigate CPU spin loops that can occur when SSE/MCP connections are cancelled.

Layer 1: SSE Connection Protection

Layer 2: Cleanup Timeouts

Layer 3: EXPERIMENTAL - anyio Monkey-Patch

🐳 Container Configuration¶

Docker Environment File¶

Create a .env file for Docker deployments:

# .env file for Docker
HOST=0.0.0.0
PORT=4444
DATABASE_URL=mysql+pymysql://mysql:changeme@mysql:3306/mcp
REDIS_URL=redis://redis:6379/0
JWT_SECRET_KEY=my-secret-key
BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=changeme
MCPGATEWAY_UI_ENABLED=true
MCPGATEWAY_ADMIN_API_ENABLED=true

Docker Compose with MySQL¶

version: "3.9"

services:
  gateway:
    image: ghcr.io/ibm/mcp-context-forge:latest
    ports:
      - "4444:4444"
    environment:
      - DATABASE_URL=mysql+pymysql://mysql:changeme@mysql:3306/mcp
      - REDIS_URL=redis://redis:6379/0
      - JWT_SECRET_KEY=my-secret-key
    depends_on:
      mysql:
        condition: service_healthy
      redis:
        condition: service_started

  mysql:
    image: mysql:8
    environment:
      - MYSQL_ROOT_PASSWORD=mysecretpassword
      - MYSQL_DATABASE=mcp
      - MYSQL_USER=mysql
      - MYSQL_PASSWORD=changeme
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 30s
      timeout: 10s
      retries: 5

  redis:
    image: redis:7
    volumes:
      - redis_data:/data

volumes:
  mysql_data:
  redis_data:

☸️ Kubernetes Configuration¶

ConfigMap Example¶

apiVersion: v1
kind: ConfigMap
metadata:
  name: mcpgateway-config
data:
  DATABASE_URL: "mysql+pymysql://mysql:changeme@mysql-service:3306/mcp"
  REDIS_URL: "redis://redis-service:6379/0"
  JWT_SECRET_KEY: "your-secret-key"
  BASIC_AUTH_USER: "admin"
  BASIC_AUTH_PASSWORD: "changeme"
  MCPGATEWAY_UI_ENABLED: "true"
  MCPGATEWAY_ADMIN_API_ENABLED: "true"
  LOG_LEVEL: "INFO"

MySQL Service Example¶

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mysql
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
        - name: mysql
          image: mysql:8
          env:
            - name: MYSQL_ROOT_PASSWORD
              value: "mysecretpassword"
            - name: MYSQL_DATABASE
              value: "mcp"
            - name: MYSQL_USER
              value: "mysql"
            - name: MYSQL_PASSWORD
              value: "changeme"
          volumeMounts:
            - name: mysql-storage
              mountPath: /var/lib/mysql
      volumes:
        - name: mysql-storage
          persistentVolumeClaim:
            claimName: mysql-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: mysql-service
spec:
  selector:
    app: mysql
  ports:
    - port: 3306
      targetPort: 3306

📚 Related Documentation¶

• Docker Compose Deployment
• Local Development Setup
• Kubernetes Deployment
• Backup & Restore
• Logging Configuration
• SSO Configuration
• OAuth Configuration
• MCP Server Catalog