• Sits in front of any MCP server or REST API
• Lets you choose your MCP protocol version (e.g.,2025-03-26)
• Exposes a single, unified interface for diverse backends

• Auto-discovers or configures peer gateways (via mDNS or manual)
• Performs health checks and merges remote registries transparently
• Supports Redis-backed syncing and fail-over

• Wraps non-MCP services as virtual MCP servers
• Registers tools, prompts, and resources with minimal configuration
• gRPC-to-MCP translation via server reflection protocol
• Automatic service discovery and method introspection

• Adapts REST APIs into tools with:

  • Automatic JSON Schema extraction
  • Support for headers, tokens, and custom auth
  • Retry, timeout, and rate-limit policies

• Prompts: Jinja2 templates, multimodal support, rollback/versioning
• Resources: URI-based access, MIME detection, caching, SSE updates
• Tools: Native or adapted, with input validation and concurrency controls

• Admin UI built with HTMX + Alpine.js
• Real-time log viewer with filtering, search, and export capabilities
• Auth: Basic, JWT, or custom schemes
• Structured logs, health endpoints, metrics
• 400+ tests, Makefile targets, live reload, pre-commit hooks

• Vendor-agnostic tracing with OpenTelemetry (OTLP) protocol support
• Multiple backend support: Phoenix (LLM-focused), Jaeger, Zipkin, Tempo, DataDog, New Relic
• Distributed tracing across federated gateways and services
• Automatic instrumentation of tools, prompts, resources, and gateway operations
• LLM-specific metrics: Token usage, costs, model performance
• Zero-overhead when disabled with graceful degradation
• Easy configuration via environment variables

Quick start with Phoenix (LLM observability):

# Start Phoenixdocker run -p 6006:6006 -p 4317:4317 arizephoenix/phoenix:latest# Configure gatewayexport OTEL_ENABLE_OBSERVABILITY=trueexport OTEL_TRACES_EXPORTER=otlpexport OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317# Run gateway - traces automatically sent to Phoenixmcpgateway

SeeObservability Documentation for detailed setup with other backends.

• Python ≥ 3.10 (3.11 recommended)
• curl + jq - only for the last smoke-test step

Copy.env.example to.env and tweak any of the settings (or use them as env variables).

export MCP_AUTH="Bearer${MCPGATEWAY_BEARER_TOKEN}"export MCP_SERVER_URL=http://localhost:4444/servers/UUID_OF_SERVER_1/mcppython3 -m mcpgateway.wrapper# Ctrl-C to exit

You can also run it withuv or inside Docker/Podman - see theContainers section above.

In MCP Inspector, defineMCP_AUTH andMCP_SERVER_URL env variables, and selectpython3 as the Command, and-m mcpgateway.wrapper as Arguments.

echo$PWD/.venv/bin/python3# Using the Python3 full path ensures you have a working venvexport MCP_SERVER_URL='http://localhost:4444/servers/UUID_OF_SERVER_1/mcp'export MCP_AUTH="Bearer${MCPGATEWAY_BEARER_TOKEN}"npx -y @modelcontextprotocol/inspector

or

Pass the url and auth as arguments (no need to set environment variables)

npx -y @modelcontextprotocol/inspectorcommand as`python`Arguments as`-m mcpgateway.wrapper --url"http://localhost:4444/servers/UUID_OF_SERVER_1/mcp" --auth"Bearer <your token>"`

When using a MCP Client such as Claude with stdio:

{"mcpServers": {"mcpgateway-wrapper": {"command":"python","args": ["-m","mcpgateway.wrapper"],"env": {"MCP_AUTH":"Bearer your-token-here","MCP_SERVER_URL":"http://localhost:4444/servers/UUID_OF_SERVER_1","MCP_TOOL_CALL_TIMEOUT":"120"      }    }  }}

• .env files - Put all the-e FOO= lines into a file and replace them with--env-file .env. See the provided.env.example for reference.

• Pinned tags - Use an explicit version (e.g.v0.9.0) instead oflatest for reproducible builds.

• JWT tokens - Generate one in the running container:

  dockerexec mcpgateway python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key

• Upgrades - Stop, remove, and rerun with the same-v $(pwd)/data:/data mount; your DB and config stay intact.

Themcpgateway.wrapper lets you connect to the gateway overstdio while keeping JWT authentication. You should run this from the MCP Client. The example below is just for testing.

# Set environment variablesexport MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key)export MCP_AUTH="Bearer${MCPGATEWAY_BEARER_TOKEN}"export MCP_SERVER_URL='http://localhost:4444/servers/UUID_OF_SERVER_1/mcp'export MCP_TOOL_CALL_TIMEOUT=120export MCP_WRAPPER_LOG_LEVEL=DEBUG# or OFF to disable loggingdocker run --rm -i \  -e MCP_AUTH=$MCP_AUTH \  -e MCP_SERVER_URL=http://host.docker.internal:4444/servers/UUID_OF_SERVER_1/mcp \  -e MCP_TOOL_CALL_TIMEOUT=120 \  -e MCP_WRAPPER_LOG_LEVEL=DEBUG \  ghcr.io/ibm/mcp-context-forge:1.0.0-BETA-1 \  python3 -m mcpgateway.wrapper

# Install gateway package in its own isolated venvpipx install --include-deps mcp-contextforge-gateway# Run the stdio wrapperMCP_AUTH="Bearer${MCPGATEWAY_BEARER_TOKEN}" \MCP_SERVER_URL=http://localhost:4444/servers/UUID_OF_SERVER_1/mcp \python3 -m mcpgateway.wrapper# Alternatively with uvuv run --directory. -m mcpgateway.wrapper

Claude Desktop JSON (uses the host Python that pipx injected):

{"mcpServers": {"mcpgateway-wrapper": {"command":"python3","args": ["-m","mcpgateway.wrapper"],"env": {"MCP_AUTH":"Bearer <your-token>","MCP_SERVER_URL":"http://localhost:4444/servers/UUID_OF_SERVER_1/mcp","MCP_TOOL_CALL_TIMEOUT":"120"      }    }  }}

• VS Code with theDev Containers extension
• Docker orPodman installed and running locally

git clone https://github.com/ibm/mcp-context-forge.gitcd mcp-context-forgecode.

VS Code will detect the.devcontainer and prompt:"Reopen in Container"or manually run:Ctrl/Cmd ⇧ P →Dev Containers: Reopen in Container

The container build will:

• Install system packages & Python 3.11
• Runmake install-dev to pull all dependencies
• Execute tests to verify the toolchain

You'll land in/workspace ready to develop.

Common tasks inside the container:

# Start dev server (hot reload)make dev# http://localhost:4444# Run tests & lintersmaketestmake lint

Optional:

• make bash - drop into an interactive shell
• make clean - clear build artefacts & caches
• Port forwarding is automatic (customize via.devcontainer/devcontainer.json)

No local Docker? Use Codespaces:

1. Go to the repo →Code ▸ Codespaces ▸ Create codespace on main
2. Wait for the container image to build in the cloud
3. Develop using the same workflow above

💡 UseAPP_ROOT_PATH=/foo if reverse-proxying under a subpath likehttps://host.com/foo/.🔄 UseFORGE_CONTENT_TYPE=application/x-www-form-urlencoded to send URL-encoded form data instead of JSON.

🔐BASIC_AUTH_USER/PASSWORD are used for:

• Logging into the web-based Admin UI
• Accessing APIs via Basic Auth (curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN")

🔑JWT_SECRET_KEY is used to:

• Sign JSON Web Tokens (Authorization: Bearer <token>)

• Generate tokens via:

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

• Tokens allow non-interactive API clients to authenticate securely.

🧪 SetAUTH_REQUIRED=false during development if you want to disable all authentication (e.g. for local testing or open APIs) or clients that don't support SSE authentication.In production, you should use the SSE to stdiomcpgateway-wrapper for such tools that don't support authenticated SSE, while still ensuring the gateway uses authentication.

🔐AUTH_ENCRYPTION_SECRET is used to encrypt and decrypt tool authentication credentials (auth_value).You must set the same value across environments to decode previously stored encrypted auth values.Recommended: use a long, random string.

🖥️ Set both UI and Admin API tofalse to disable management UI and APIs in production.📥 The bulk import endpoint allows importing up to 200 tools in a single request via/admin/tools/import.⏱️ IncreaseMCPGATEWAY_UI_TOOL_TEST_TIMEOUT if your tools make multiple API calls or operate in high-latency environments.

🤖A2A Integration: Register external AI agents (OpenAI, Anthropic, custom) and expose them as MCP tools📊Metrics: Track agent performance, success rates, and response times🔒Security: Encrypted credential storage and configurable authentication🎛️Admin UI: Dedicated tab for agent management with test functionality

A2A 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 streamlines the entire workflow by enabling seamless tool enrichment, automated test case generation, and comprehensive tool validation.

The LLM Chat MCP Client allows you to interact with MCP servers using conversational AI from multiple LLM providers. This feature enables natural language interaction with tools, resources, and prompts exposed by MCP servers.

Azure OpenAI Configuration:

OpenAI Configuration:

Anthropic Claude Configuration:

AWS Bedrock Configuration:

IBM WatsonX AI

Ollama Configuration:

⚙️ToolOps: To manage the complete tool workflow — enrich tools, generate test cases automatically, and validate them with ease.🤖LLM Chat Integration: Chat with MCP servers using natural language powered by Azure OpenAI, OpenAI, Anthropic Claude, AWS Bedrock, or Ollama🔧Flexible Providers: Switch between different LLM providers without changing your MCP integration🔒Security: API keys and credentials are securely stored and never exposed in responses🎛️Admin UI: Dedicated LLM Chat tab in the admin interface for interactive conversations

ToolOps Configuration Effects:

• TOOLOPS_ENABLED=false (default): Completely disables ToolOps features (API endpoints return 404, admin tab hidden)
• TOOLOPS_ENABLED=true: Enables ToolOps functionality in the UI

LLM Chat Configuration Effects:

• LLMCHAT_ENABLED=false (default): Completely disables LLM Chat features (API endpoints return 404, admin tab hidden)
• LLMCHAT_ENABLED=true: Enables LLM Chat functionality with the selected provider

Provider Requirements:

• Azure OpenAI: RequiresAZURE_OPENAI_ENDPOINT,AZURE_OPENAI_API_KEY, andAZURE_OPENAI_DEPLOYMENT
• OpenAI: RequiresOPENAI_API_KEY
• Anthropic: RequiresANTHROPIC_API_KEY andpip install langchain-anthropic
• AWS Bedrock: RequiresAWS_BEDROCK_MODEL_ID andpip install langchain-aws boto3. Uses AWS credential chain if explicit credentials not provided.IBM WatsonX AI: RequiresWATSONX_URL,WATSONX_APIKEY,WATSONX_PROJECT_ID,WATSONX_MODEL_ID andpip install langchain-ibm.
• Ollama: Requires local Ollama instance running (default:http://localhost:11434)

Redis Configurations: For maintaining Chat Sessions in multi-worker environment

Documentation:

• LLM Chat Guide - Complete LLM Chat setup and provider configuration

The LLM Settings feature enables MCP Gateway to act as a unified LLM provider with an OpenAI-compatible API. Configure multiple external LLM providers through the Admin UI and expose them through a single proxy endpoint.

Gateway Provider Settings (for LLM Chat with provider=gateway):

Features:

• OpenAI-Compatible API: Exposes/v1/chat/completions and/v1/models endpoints compatible with any OpenAI client
• Multi-Provider Support: Configure OpenAI, Azure OpenAI, Anthropic, Ollama, Google, Mistral, Cohere, AWS Bedrock, Groq, and more
• Admin UI Management: Add, edit, enable/disable, and test providers through the Admin UI (LLM Settings tab)
• Model Discovery: Fetch available models from providers and sync them to the database
• Health Monitoring: Automatic health checks with status indicators
• Unified Interface: Route requests to any configured provider through a single API

API Endpoints:

# List available modelscurl -H"Authorization: Bearer$TOKEN" http://localhost:4444/v1/models# Chat completioncurl -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

🔧Configuration: Providers are managed through the Admin UI under "LLM Settings > Providers"📋Models: View and manage models under "LLM Settings > Models"⚡Testing: Test models directly from the Admin UI with the "Test" feature

🔐MCP Client Auth: WhenMCP_CLIENT_AUTH_ENABLED=false, you must setTRUST_PROXY_AUTH=true if using a trusted authentication proxy. This is a security-sensitive setting.

GitHub OAuth:

Google OAuth:

IBM Security Verify OIDC:

Keycloak OIDC:

Microsoft Entra ID OIDC:

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

Okta OIDC:

SSO Admin Assignment:

ContextForge implementsOAuth 2.0 Dynamic Client Registration (RFC 7591) andPKCE (RFC 7636) for seamless integration with OAuth-protected MCP servers and upstream API gateways like HyperMCP.

Key Features:

• ✅ Automatic client registration with Authorization Servers (no manual credential configuration)
• ✅ Authorization Server metadata discovery (RFC 8414)
• ✅ PKCE (Proof Key for Code Exchange) enabled for all Authorization Code flows
• ✅ Support for public clients (PKCE-only, no client secret)
• ✅ Encrypted credential storage with Fernet encryption
• ✅ Configurable issuer allowlist for security

Documentation:

• DCR Configuration Guide - Complete DCR setup and troubleshooting
• OAuth 2.0 Integration - OAuth configuration and PKCE details
• HyperMCP Tutorial - End-to-end DCR setup with HyperMCP gateway

🆕New in v0.7.0: The MCP Server Catalog allows you to define a catalog of pre-configured MCP servers in a YAML file for easy discovery and management via the Admin UI.

Key Features:

• 🔄 Refresh Button - Manually refresh catalog without page reload
• 🔍 Debounced Search - Optimized search with 300ms debounce
• 📝 Custom Server Names - Specify custom names when registering
• 🔌 Transport Detection - Auto-detect SSE, WebSocket, or HTTP transports
• 🔐 OAuth Support - Register OAuth servers and configure later
• ⚡ Better Error Messages - User-friendly errors for common issues

Documentation:

• MCP Server Catalog Guide - Complete catalog setup and configuration

CORS Configuration: WhenENVIRONMENT=development, CORS origins are automatically configured for common development ports (3000, 8080, gateway port). In production, origins are constructed fromAPP_DOMAIN (e.g.,https://yourdomain.com,https://app.yourdomain.com). You can override this by explicitly settingALLOWED_ORIGINS.

Security Headers: The gateway automatically adds configurable security headers to all responses including CSP, X-Frame-Options, X-Content-Type-Options, X-Download-Options, and HSTS (on HTTPS). All headers can be individually enabled/disabled. Sensitive server headers are removed.

Security Validation: SetREQUIRE_STRONG_SECRETS=true to enforce minimum lengths for JWT secrets and passwords at startup. This helps prevent weak credentials in production. Default isfalse for backward compatibility.

iframe Embedding: The gateway controls iframe embedding through bothX-Frame-Options header and CSPframe-ancestors directive (both are automatically synced). Options:

• X_FRAME_OPTIONS=DENY (default): Blocks all iframe embedding
• X_FRAME_OPTIONS=SAMEORIGIN: Allows embedding from same domain only
• X_FRAME_OPTIONS="ALLOW-ALL": Allows embedding from all sources (setsframe-ancestors * file: http: https:)
• X_FRAME_OPTIONS=null ornone: Completely removes iframe restrictions (no headers sent)

Modern browsers prioritize CSPframe-ancestors over the legacyX-Frame-Options header. Both are now kept in sync automatically.

Cookie Security: Authentication cookies are automatically configured with HttpOnly, Secure (in production), and SameSite attributes for CSRF protection.

Note: do not quote the ALLOWED_ORIGINS values, this needs to be valid JSON, such as:ALLOWED_ORIGINS=["http://localhost", "http://localhost:4444"]

Documentation endpoints (/docs,/redoc,/openapi.json) are always protected by authentication.By default, they require Bearer token authentication. SettingDOCS_ALLOW_BASIC_AUTH=true enables HTTP Basic Authentication as an additional method using the same credentials asBASIC_AUTH_USER andBASIC_AUTH_PASSWORD.

MCP Gateway supportsEd25519 digital signatures for certificate validation and integrity verification. This cryptographic signing mechanism ensures that CA certificates used by the gateway are authentic and haven't been tampered with.

How It Works:

1. Certificate Signing - WhenENABLE_ED25519_SIGNING=true, the gateway signs the CA certificate of each MCP server/gateway using the Ed25519 private key.

2. Certificate Validation - Before using a CA certificate for subsequent calls, the gateway validates its signature to ensure authenticity and integrity.

3. Disabled Mode - WhenENABLE_ED25519_SIGNING=false, certificates are neither signed nor validated (default behavior).

Key Generation:

# Generate a new Ed25519 key pairpython mcpgateway/utils/generate_keys.py# Output will show:# - Private key (set this to ED25519_PRIVATE_KEY)

Key Rotation:

To rotate keys without invalidating existing signed certificates:

1. Move the currentED25519_PRIVATE_KEY value toPREV_ED25519_PRIVATE_KEY
2. Generate a new key pair using the command above
3. Set the new private key toED25519_PRIVATE_KEY
4. The gateway will automatically re-sign valid certificates at the point of key change

Example Configuration:

# Enable Ed25519 signingENABLE_ED25519_SIGNING=true# Current signing key (PEM format)ED25519_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----MC4CAQAwBQYDK2VwBCIEIJ5pW... (your key here)-----END PRIVATE KEY-----"# Previous key for rotation (optional)PREV_ED25519_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----MC4CAQAwBQYDK2VwBCIEIOld... (old key here)-----END PRIVATE KEY-----"

🔐Security Best Practices:

• Store private keys securely (use secrets management tools like Vault, AWS Secrets Manager, etc.)
• Rotate keys periodically (recommended: every 90-180 days)
• Never commit private keys to version control
• Use environment variables or encrypted config files

🔑Public Key Derivation:

• Public keys are automatically derived from private keys
• No need to configure public keys separately
• BothED25519_PUBLIC_KEY andPREV_ED25519_PUBLIC_KEY are computed at startup

⚡Performance:

• Ed25519 signing is extremely fast (~64 microseconds per signature)
• Minimal impact on gateway performance
• Recommended for production deployments requiring certificate integrity

MCP Gateway includes automatic response compression middleware that reduces bandwidth usage by 30-70% for text-based responses (JSON, HTML, CSS, JS). Compression is negotiated automatically based on clientAccept-Encoding headers with algorithm priority:Brotli (best compression) >Zstd (fastest) >GZip (universal fallback).

Compression Behavior:

• Automatically negotiates algorithm based on clientAccept-Encoding header
• Only compresses responses larger thanCOMPRESSION_MINIMUM_SIZE bytes (small responses not worth compression overhead)
• AddsVary: Accept-Encoding header for proper cache behavior
• No client changes required (browsers/clients handle decompression automatically)
• Typical compression ratios: JSON responses 40-60%, HTML responses 50-70%

Performance Impact:

• CPU overhead: <5% (balanced settings)
• Bandwidth reduction: 30-70% for text responses
• Latency impact: <10ms for typical responses

Testing Compression:

# Start servermake dev# Test Brotli (best compression)curl -H"Accept-Encoding: br" http://localhost:8000/openapi.json -v| grep -i"content-encoding"# Test GZip (universal fallback)curl -H"Accept-Encoding: gzip" http://localhost:8000/openapi.json -v| grep -i"content-encoding"# Test Zstd (fastest)curl -H"Accept-Encoding: zstd" http://localhost:8000/openapi.json -v| grep -i"content-encoding"

Tuning for Production:

# High-traffic (optimize for speed)COMPRESSION_GZIP_LEVEL=4COMPRESSION_BROTLI_QUALITY=3COMPRESSION_ZSTD_LEVEL=1# Bandwidth-constrained (optimize for size)COMPRESSION_GZIP_LEVEL=9COMPRESSION_BROTLI_QUALITY=11COMPRESSION_ZSTD_LEVEL=9

Note: SeeScaling Guide for compression performance optimization at scale.

MCP Gateway provides flexible logging withstdout/stderr output by default andoptional file-based logging. When file logging is enabled, it provides JSON formatting for structured logs and text formatting for console output.

Logging Behavior:

• Default: Logs only tostdout/stderr with human-readable text format
• File Logging: WhenLOG_TO_FILE=true, logs toboth file (JSON format) and console (text format)
• Log Rotation: WhenLOG_ROTATION_ENABLED=true, files rotate atLOG_MAX_SIZE_MB withLOG_BACKUP_COUNT backup files (e.g.,.log.1,.log.2)
• Directory Creation: Log folder is automatically created if it doesn't exist
• Centralized Service: All modules use the unifiedLoggingService for consistent formatting

Example Configurations:

# Default: stdout/stderr only (recommended for containers)LOG_LEVEL=INFO# No additional config needed - logs to stdout/stderr# Optional: Enable file logging (no rotation)LOG_TO_FILE=trueLOG_FOLDER=/var/log/mcpgatewayLOG_FILE=gateway.logLOG_FILEMODE=a+# Optional: Enable file logging with rotationLOG_TO_FILE=trueLOG_ROTATION_ENABLED=trueLOG_MAX_SIZE_MB=10LOG_BACKUP_COUNT=3LOG_FOLDER=/var/log/mcpgatewayLOG_FILE=gateway.log

Default Behavior:

• Logs are writtenonly to stdout/stderr in human-readable text format
• File logging isdisabled by default (no files created)
• SetLOG_TO_FILE=true to enable optional file logging with JSON format

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

OTLP Configuration (for Phoenix, Tempo, DataDog, etc.):

Alternative Backends (optional):

Performance Tuning:

Quick Start with Phoenix:

# Start Phoenix for LLM observabilitydocker run -p 6006:6006 -p 4317:4317 arizephoenix/phoenix:latest# Configure gatewayexport OTEL_ENABLE_OBSERVABILITY=trueexport OTEL_TRACES_EXPORTER=otlpexport OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317# Run gateway - traces automatically sent to Phoenixmcpgateway

🔍What Gets Traced: Tool invocations, prompt rendering, resource fetching, gateway federation, health checks, plugin execution (if enabled)

🚀Zero Overhead: WhenOTEL_ENABLE_OBSERVABILITY=false, all tracing is disabled with no performance impact

📊View Traces: Phoenix UI athttp://localhost:6006, Jaeger athttp://localhost:16686, or your configured backend

The gateway includes built-in observability features for tracking HTTP requests, spans, and traces independent of OpenTelemetry. This provides database-backed trace storage and analysis directly in the Admin UI.

Key Features:

• 📊Database-backed storage: Traces stored in SQLite/PostgreSQL for persistence
• 🔍Admin UI integration: View traces, spans, and metrics in the diagnostics tab
• 🎯Sampling control: Configure sampling rate to reduce overhead in high-traffic scenarios
• 🕐Automatic cleanup: Old traces automatically purged based on retention settings
• 🚫Path filtering: Exclude health checks and static resources from tracing

Configuration Effects:

• OBSERVABILITY_ENABLED=false: Completely disables internal observability (no database writes, zero overhead)
• OBSERVABILITY_SAMPLE_RATE=0.1: Traces 10% of requests (useful for high-volume production)
• OBSERVABILITY_EXCLUDE_PATHS=/health,/metrics: Prevents noisy endpoints from creating traces

📝Note: This is separate from OpenTelemetry. You can use both systems simultaneously - internal observability for Admin UI visibility and OpenTelemetry for external systems like Phoenix/Jaeger.

🎛️Admin UI Access: When enabled, traces appear inAdmin → Diagnostics → Observability tab with filtering, search, and export capabilities

The gateway exposes Prometheus-compatible metrics at/metrics/prometheus for monitoring and alerting.

Key Features:

• 📊Standard metrics: HTTP request duration, response codes, active requests
• 🏷️Custom labels: Add static labels (environment, region, team) for filtering in Prometheus/Grafana
• 🚫Path exclusions: Prevent high-cardinality issues by excluding dynamic paths
• 📈Namespace isolation: Group metrics by application or organization

Configuration Examples:

# Production deployment with custom labelsENABLE_METRICS=trueMETRICS_NAMESPACE=mycompanyMETRICS_SUBSYSTEM=gatewayMETRICS_CUSTOM_LABELS=environment=production,region=us-east-1,team=platform# Exclude high-volume endpoints from metricsMETRICS_EXCLUDED_HANDLERS=/servers/.*/sse,/static/.*,.*health.*# Disable metrics for developmentENABLE_METRICS=false

Metric Names:

• With namespace + subsystem:mycompany_gateway_http_requests_total
• Default (no namespace/subsystem):default_http_requests_total

⚠️High-Cardinality Warning: Never use high-cardinality values (user IDs, request IDs, timestamps) inMETRICS_CUSTOM_LABELS. Only use low-cardinality static values (environment, region, cluster).

📊Prometheus Endpoint: Access metrics atGET /metrics/prometheus (requires authentication ifAUTH_REQUIRED=true)

🎯Grafana Integration: Import metrics into Grafana dashboards using the configured namespace as a filter

💡 SSE Keepalive Events: The gateway sends periodic keepalive events to prevent connection timeouts with proxies and load balancers. Disable withSSE_KEEPALIVE_ENABLED=false if your client doesn't handle unknown event types. Common intervals: 30s (default), 60s (AWS ALB), 240s (Azure).

🧠none disables caching entirely. Usememory for dev,database for local persistence, orredis for distributed caching across multiple instances.

MCP Gateway uses Alembic for database migrations. Common commands:

• make db-current - Show current database version
• make db-upgrade - Apply pending migrations
• make db-migrate - Create new migration
• make db-history - Show migration history
• make db-status - Detailed migration status

Common Issues:

• "No 'script_location' key found": Ensure you're running from the project root directory.

• "Unknown SSE event: keepalive" warnings: Some MCP clients don't recognize keepalive events. These warnings are harmless and don't affect functionality. To disable:SSE_KEEPALIVE_ENABLED=false

• Connection timeouts with proxies/load balancers: If experiencing timeouts, adjust keepalive interval to match your infrastructure:SSE_KEEPALIVE_INTERVAL=60 (AWS ALB) or240 (Azure).

🔍robots.txt: By default, blocks all crawlers for security. Customize for your needs.

🔐security.txt: Define security contact information per RFC 9116. Leave empty to disable.

📄Custom Files: Add arbitrary well-known files likeai.txt,dnt-policy.txt, etc.

⚠️Security Warning: Header passthrough is disabled by default for security. Only enable if you understand the implications and have reviewed which headers should be passed through to backing MCP servers. Authorization headers are not included in defaults.

• Podmanor Docker installed locally
• IBM Cloud CLI (usemake ibmcloud-cli-install to install)
• AnIBM Cloud API key with access to Code Engine & Container Registry
• Code Engine and Container Registry servicesenabled in your IBM Cloud account

Create a.env file (or export the variables in your shell).The first block isrequired; the second providestunable defaults you can override:

# ── Required ─────────────────────────────────────────────IBMCLOUD_REGION=us-southIBMCLOUD_RESOURCE_GROUP=defaultIBMCLOUD_PROJECT=my-codeengine-projectIBMCLOUD_CODE_ENGINE_APP=mcpgatewayIBMCLOUD_IMAGE_NAME=us.icr.io/myspace/mcpgateway:latestIBMCLOUD_IMG_PROD=mcpgateway/mcpgatewayIBMCLOUD_API_KEY=your_api_key_here# Optional - omit to use interactive `ibmcloud login --sso`# ── Optional overrides (sensible defaults provided) ──────IBMCLOUD_CPU=1# vCPUs for the appIBMCLOUD_MEMORY=4G# Memory allocationIBMCLOUD_REGISTRY_SECRET=my-regcred# Name of the Container Registry secret

✅Quick check:make ibmcloud-check-env

make ibmcloud-check-envmake ibmcloud-cli-installmake ibmcloud-loginmake ibmcloud-ce-loginmake ibmcloud-tagmake ibmcloud-pushmake ibmcloud-deploymake ibmcloud-ce-statusmake ibmcloud-ce-logs

# Generic JSON-RPC calls (tools, gateways, roots, etc.)curl -X POST -H"Authorization: Bearer$MCPGATEWAY_BEARER_TOKEN" \     -H"Content-Type: application/json" \     -d'{"jsonrpc":"2.0","id":1,"method":"list_tools"}' \     http://localhost:4444/rpc

Handles any method name:list_tools,list_gateways,prompts/get, or invokes a tool if method matches a registered tool name .