ContextForge MCP Gateway - Frequently Asked Questions¶

PyPI (pipx / uvx makes an isolated venv):

# Using pipx - pip install pipx
pipx run mcp-contextforge-gateway

# Or uvx - pip install uv (default: admin/changeme)
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

OCI image (Docker/Podman) - shares host network so localhost works:

podman run --network=host -p 4444:4444 ghcr.io/ibm/mcp-context-forge:0.7.0

• Admin UI → http://localhost:4444/admin
• Swagger → http://localhost:4444/docs
• ReDoc → http://localhost:4444/redoc

cp .env.example .env

Then edit:

BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=changeme
JWT_SECRET_KEY=my-test-key

• Basic: HOST, PORT, APP_ROOT_PATH
• Auth: AUTH_REQUIRED, BASIC_AUTH_*, JWT_SECRET_KEY
• Logging: LOG_LEVEL, LOG_FORMAT, LOG_TO_FILE, LOG_FILE, LOG_FOLDER, LOG_ROTATION_ENABLED, LOG_MAX_SIZE_MB, LOG_BACKUP_COUNT
• Transport: TRANSPORT_TYPE, WEBSOCKET_PING_INTERVAL, SSE_RETRY_TIMEOUT
• Tools: TOOL_TIMEOUT, MAX_TOOL_RETRIES, TOOL_RATE_LIMIT, TOOL_CONCURRENT_LIMIT
• Federation: FEDERATION_ENABLED, FEDERATION_PEERS, FEDERATION_SYNC_INTERVAL

make podman # or make docker
make podman-run-ssl # or make docker-run-ssl
make podman-run-ssl-host # or make docker-run-ssl-host

Docker Compose is also available, ex: make compose-up.

See the Deployment Documentation for detailed deployment instructions across local, docker, podman, compose, AWS, Azure, GCP, IBM Cloud, Helm, Minikube, Kubernetes, OpenShift and more.

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
    --username admin@example.com --exp 10080 --secret my-test-key)
curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools

The token is used for all API interactions and can be configured to expire using -exp.

• Use make podman-run-ssl for self-signed certs or drop your own certificate under certs.
• Set ALLOWED_ORIGINS or CORS_ENABLED for CORS headers.

When MCP Gateway uses authentication (JWT/Bearer/Basic/OAuth), there's a conflict if you need to pass different Authorization headers to upstream MCP servers.

Solution: Use X-Upstream-Authorization header

# Send X-Upstream-Authorization header - gateway automatically renames it to Authorization for upstream
curl -H "Authorization: Bearer $GATEWAY_TOKEN" \
     -H "X-Upstream-Authorization: Bearer $UPSTREAM_TOKEN" \
     -X POST http://localhost:4444/tools/invoke/my_tool \
     -d '{"arguments": {}}'

The gateway will: 1. Use the Authorization header for gateway authentication 2. Rename X-Upstream-Authorization to Authorization when forwarding to the upstream MCP server 3. This solves the header conflict and allows different auth tokens for gateway vs upstream

A "Gateway" is another MCP Server. The MCP Gateway itself is an MCP Server. This means you can add any MCP Server under "Gateways" and it will retrieve Tools/Resources/Prompts.

curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \\
     -d '{"name":"peer","url":"http://peer:4444"}' \\
     http://localhost:4444/gateways

A Virtual Server is a MCP Server composed from Tools/Resources/Prompts from multiple servers. Add one or more MCP Servers under "Gateways", then select which Tools/Prompts/Resources to use to create your Virtual Server.

• TOOL_CONCURRENT_LIMIT
• TOOL_RATE_LIMIT
• WEBSOCKET_PING_INTERVAL
• SSE_RETRY_TIMEOUT

• GUNICORN_WORKERS (for Gunicorn)
• UVICORN_WORKERS (for Uvicorn)

Use hey against /rpc with sample payloads from tests/hey. Focus on p99 latency, error rate, and throughput.

Use OpenTelemetry (OTLP) to export traces to Phoenix, Jaeger, Zipkin, Tempo, DataDog, etc.

export OTEL_ENABLE_OBSERVABILITY=true
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

See the Observability docs for backend-specific setup. Admin UI also shows tool/server/prompt stats. A Prometheus /metrics endpoint may be added later.

• LOG_FORMAT=json or text
• Adjust with LOG_LEVEL

Yes - see the basic testing guide: Testing › Basic.

Add the following to your .env:

EMAIL_AUTH_ENABLED=true
PLATFORM_ADMIN_EMAIL=admin@example.com
PLATFORM_ADMIN_PASSWORD=changeme
AUTO_CREATE_PERSONAL_TEAMS=true

Upgrading from v0.7.0? Follow MIGRATION-0.7.0.md.

Yes. Use provider‑specific mappings to assign users on first login:

# GitHub
GITHUB_ORG_TEAM_MAPPING={"your-org": "team-id"}

# Google Groups
GOOGLE_GROUPS_MAPPING={"group@yourcompany.com": "team-id"}

# Okta
OKTA_GROUP_MAPPING={"MCP Gateway Users": "team-id"}

See the SSO guides under Manage › SSO for details.

Configure a stdio server in your client:

{
  "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"
      }
    }
  }
}

See: mcpgateway.wrapper.

Yes - build as arm64 and reduce RAM/workers.