Configuration Reference¶

This guide provides comprehensive configuration options for ContextForge, 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¶

ContextForge 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]

🔧 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-but-now-longer-than-32-bytes)

UI Features¶

For detailed guidance on embedding and section customization, see Admin UI Customization.

/admin/?ui_hide=prompts,resources,teams

/admin/?ui_hide=

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

Experimental Dataplane Publisher¶

User configuration keys expire after twice the configured snapshot interval plus 10 seconds. Shorter intervals can reduce convergence time in test environments; production deployments should retain the default unless their Redis and database capacity has been sized for more frequent snapshots.

Direct Proxy Mode¶

Configuration Effects:

• MCPGATEWAY_DIRECT_PROXY_ENABLED=false (default): Gateways cannot use gateway_mode=direct_proxy; existing ones fall back to cache mode
• MCPGATEWAY_DIRECT_PROXY_ENABLED=true: Enables pass-through MCP operations bypassing the caching layer

Usage: Register a gateway with "gateway_mode": "direct_proxy", then send requests with the X-Context-Forge-Gateway-Id header set to the gateway's ID. All MCP operations (tools/list, tools/call, resources/list, resources/read) will be proxied directly to the remote server.

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 ContextForge 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¶

Changing PROTECT_ALL_ADMINS does not control peer-administrator removal. An administrator with admin.user_management can demote or deactivate another administrator while at least one active administrator remains. Protect administrator credentials accordingly; deployments requiring dual control should enforce that process outside this endpoint.

When PASSWORD_RESET_ENABLED=false, self-service forgot/reset endpoints are disabled (403 on API and disabled/redirected UI flows). When SMTP_ENABLED=false, reset requests are accepted but no email is delivered.

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¶

CSRF Protection¶

ContextForge provides Cross-Site Request Forgery (CSRF) protection through three independent implementations optimized for different request paths. Understanding the distinctions is critical for configuration.

Three Independent CSRF Implementations:

ContextForge implements CSRF protection in three distinct paths:

1. CSRFMiddleware (global protection): Applies to non-exempt routes (e.g., /llm/*, /v1/mcp/*) and also to versioned admin routes (/v1/admin/*)
2. enforce_admin_csrf (per-route dependency): Applies to admin routes at both the legacy (/admin/*, /admin/llm/*) and versioned (/v1/admin/*, /v1/admin/llm/*) mounts
3. enforce_fetch_tools_csrf (per-route dependency, mcpgateway/routers/oauth_router.py): Applies only to POST /oauth/fetch-tools/{gateway_id} — the reason that path is in CSRF_EXEMPT_PATHS rather than relying on CSRFMiddleware. It duplicates its own module-level ADMIN_CSRF_COOKIE_NAME/ADMIN_CSRF_HEADER_NAME constants (not imported from admin.py) and its own Origin/Referer same-origin check, independent of both CSRFMiddleware's and enforce_admin_csrf's origin-check logic.

The five settings marked as "middleware-path-only" in the table above govern only the first path; the other two dependencies use hardcoded equivalents for all cookie and header attributes:

Default Exempt Paths (middleware only):

["/health", "/auth/login", "/auth/logout", "/auth/refresh", "/auth/email/login", "/auth/email/register", "/auth/email/forgot-password", "/auth/email/reset-password", "/admin", "/admin/login", "/admin/forgot-password", "/admin/reset-password", "/oauth/fetch-tools", "/docs", "/redoc", "/openapi.json", "/metrics", "/mcp/", "/sse", "/message", "/rpc", "/api/metrics/", "/toolops/", "/tokens", "/teams/", "/llmchat/", "/api/logs/", "/_internal/mcp/"]

Identity Propagation¶

MCP Gateway can propagate end-user identity to upstream MCP servers when proxying requests. This enables upstream services to make authorization decisions based on the original caller's identity, and supports audit trails that track the full delegation chain.

Propagation modes:

• headers: Sends identity as HTTP headers (X-Forwarded-User-Id, X-Forwarded-User-Email, X-Forwarded-User-Groups, etc.) to upstream servers.
• meta: Injects identity into the MCP _meta field for MCP protocol-level propagation.
• both (default): Uses both headers and _meta propagation.

SSRF Protection¶

ContextForge 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=false
SSRF_ALLOW_PRIVATE_NETWORKS=false
SSRF_DNS_FAIL_CLOSED=true

SSRF_PROTECTION_ENABLED=true
SSRF_ALLOW_LOCALHOST=false
SSRF_ALLOW_PRIVATE_NETWORKS=false
SSRF_ALLOWED_NETWORKS='["10.20.0.0/16","192.168.50.0/24"]'

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

Helm/Kubernetes registration examples¶

When deployed with the Helm chart, the testing registration jobs create gateways pointing to in-cluster Service DNS names:

• Fast-time: http://<release>-mcp-fast-time-server:80/http
• Fast-test: http://<release>-fast-test-server:8880/mcp

Under strict defaults (SSRF_ALLOW_PRIVATE_NETWORKS=false, SSRF_ALLOWED_NETWORKS=[]), these private destinations are rejected with 422 during /gateways creation.

Recommended approach for cluster deployments is to keep private networks blocked globally and allow only known internal CIDRs:

mcpContextForge:
  config:
    SSRF_PROTECTION_ENABLED: "true"
    SSRF_ALLOW_LOCALHOST: "false"
    SSRF_ALLOW_PRIVATE_NETWORKS: "false"
    SSRF_ALLOWED_NETWORKS: '["10.96.0.0/12"]' # example Service CIDR, adjust to your environment
    SSRF_DNS_FAIL_CLOSED: "true"

For local benchmark profiles where broad private access is acceptable, use:

mcpContextForge:
  config:
    SSRF_ALLOW_PRIVATE_NETWORKS: "true"

Content Security - Size Limits¶

Content size limits prevent DoS attacks and resource exhaustion from oversized content submissions. Validation occurs at the service layer before database writes and returns HTTP 413 Payload Too Large with structured error details.

{
  "detail": {
    "error": "Resource content size limit exceeded",
    "message": "Resource content size (195.3 KB) exceeds maximum allowed size (100.0 KB)",
    "actual_size": 200000,
    "max_size": 102400
  }
}

Ed25519 Certificate Signing¶

ContextForge 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¶

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

Logging¶

Observability (OpenTelemetry)¶

ContextForge 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¶

MCPGATEWAY_WS_RELAY_ENABLED and MCPGATEWAY_REVERSE_PROXY_ENABLED are disabled by default and should be enabled only when those WebSocket transport paths are explicitly required.

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¶

Rate Limiter Redis¶

Migration: Existing deployments continue using main Redis. Set RATELIMITER_REDIS_URL to enable dedicated instance.

Rate Limiter Redis Fallback Behavior During Runtime¶

When RATELIMITER_REDIS_URL is configured but the dedicated Redis instance becomes unavailable mid-runtime:

• Each worker process falls back to independent in-memory rate limiting
• Rate limits are no longer enforced globally across workers
• A client can effectively multiply their rate limit by the number of worker processes
• This is a degraded service state that operators must monitor

Example: With 4 workers and a 100 req/min limit:

• Normal: 100 req/min enforced globally via Redis
• Degraded: Each worker enforces 100 req/min independently = 400 req/min effective limit

Monitoring: Watch for WARNING logs: "Rate limiter Redis unavailable: ..."

Recovery: The gateway does not automatically reconnect to Redis after initial failure. Restart the gateway to restore shared rate limiting.

Connection Pool Sizing¶

When using a dedicated rate limiter Redis (RATELIMITER_REDIS_URL), the gateway maintains two separate connection pools:

• Main Redis pool: REDIS_MAX_CONNECTIONS (default: 50)
• Rate limiter Redis pool: RATELIMITER_REDIS_MAX_CONNECTIONS (default: 50)

Total Redis connections: 100 (with defaults)

Planning: Ensure your Redis maxclients setting accommodates:

maxclients >= (num_gateway_instances × (REDIS_MAX_CONNECTIONS + RATELIMITER_REDIS_MAX_CONNECTIONS))

Example: 3 gateway instances with defaults = 300 total connections needed

Use `memory` for dev, `database` for local persistence, or `redis` for distributed caching across multiple instances. `none` disables caching entirely.

Tool Lookup Cache¶

Metrics Aggregation Cache¶

MCP Session Pool¶

Development¶

Well-Known URI Configuration¶

Header Passthrough Configuration¶

Plugins Configuration¶

Plugin settings are documented separately to match the plugin-framework settings split in code.

• See Plugin Configuration Reference for all PLUGINS_* settings and aliases.

Gateway-Level Plugin Security Overrides¶

These settings control how much authority plugins have over gateway security decisions. They are part of the core gateway Settings (not the plugin framework's PluginsSettings) and require a server restart to take effect.

Both default to false (secure by default). Only enable them when all loaded plugins are fully trusted.

Plugin Framework (Standalone) Settings¶

The plugin framework has its own configuration via pydantic-settings with the PLUGINS_ env var prefix. These settings allow the plugin framework to operate independently of the gateway configuration. When the plugin framework is used standalone (e.g., via the mcpplugins CLI or as a library), only these PLUGINS_-prefixed variables are needed. When running inside the gateway, both the gateway settings (above) and these framework settings are in effect.

PLUGINS_ENABLED, PLUGINS_CLI_COMPLETION, and PLUGINS_CLI_MARKUP_MODE are shared — the same env var is read by both the gateway and the plugin framework. The HTTP client and SSL settings below are scoped specifically to plugin requests.

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=postgresql+psycopg://postgres:changeme@postgres:5432/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
# Embedded UI mode (hides logout + team selector by default)
MCPGATEWAY_UI_EMBEDDED=false
# CSV/JSON list of UI sections/header items to hide (optional)
MCPGATEWAY_UI_HIDE_SECTIONS=
MCPGATEWAY_UI_HIDE_HEADER_ITEMS=

Docker Compose with PostgreSQL¶

version: "3.9"

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

  postgres:
    image: postgres:17
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=changeme
      - POSTGRES_DB=mcp
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 30s
      timeout: 10s
      retries: 5

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

volumes:
  pg_data:
  redis_data:

☸️ Kubernetes Configuration¶

ConfigMap Example¶

apiVersion: v1
kind: ConfigMap
metadata:
  name: mcpgateway-config
data:
  DATABASE_URL: "postgresql+psycopg://postgres:changeme@postgres-service:5432/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"

📚 Related Documentation¶

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