ContextForge

An open source registry and proxy that federates MCP, A2A, and REST/gRPC APIs with centralized governance, discovery, and observability. Optimizes Agent & Tool calling, and supports plugins.

     

     

ContextForge is an open source registry and proxy that federates tools, agents, and APIs into one clean endpoint for your AI clients. It provides centralized governance, discovery, and observability across your AI infrastructure:

• Tools Gateway — MCP, REST, gRPC-to-MCP translation, and TOON compression
• Agent Gateway — A2A protocol, OpenAI-compatible and Anthropic agent routing
• API Gateway — Rate limiting, auth, retries, and reverse proxy for REST services
• Plugin Extensibility — 40+ plugins for additional transports, protocols, and integrations
• Observability — OpenTelemetry tracing with Phoenix, Jaeger, Zipkin, and other OTLP backends

It runs as a fully compliant MCP server, deployable via PyPI or Docker, and scales to multi-cluster environments on Kubernetes with Redis-backed federation and caching.

Table of Contents

• Overview & Goals
• Quick Start - PyPI
• Quick Start - Containers
• VS Code Dev Container
• Installation
• Upgrading
• Configuration
• Running
• Cloud Deployment
• API Reference
• Testing
• Project Structure
• Development
• Troubleshooting
• Contributing

---

📌 Quick Links

---

Overview & Goals

ContextForge is an open source registry and proxy that federates any Model Context Protocol (MCP) server, A2A server, or REST/gRPC API, providing centralized governance, discovery, and observability. It optimizes agent and tool calling, and supports plugins. See the project roadmap for more details.

It currently supports:

• Federation across multiple MCP and REST services
• A2A (Agent-to-Agent) integration for external AI agents (OpenAI, Anthropic, custom)
• gRPC-to-MCP translation via automatic reflection-based service discovery
• Virtualization of legacy APIs as MCP-compliant tools and servers
• Transport over HTTP, JSON-RPC, WebSocket, SSE (with configurable keepalive), stdio and streamable-HTTP
• An Admin UI for real-time management, configuration, and log monitoring (with airgapped deployment support)
• Built-in auth, retries, and rate-limiting with user-scoped OAuth tokens and unconditional X-Upstream-Authorization header support
• OpenTelemetry observability with Phoenix, Jaeger, Zipkin, and other OTLP backends
• Scalable deployments via Docker or PyPI, Redis-backed caching, and multi-cluster federation

For a list of upcoming features, check out the ContextForge Roadmap

---

---

Quick Start - PyPI

ContextForge is published on PyPI as mcp-contextforge-gateway.

---

TLDR;: (single command using uv)

# Quick start with environment variables
BASIC_AUTH_PASSWORD=pass \
MCPGATEWAY_UI_ENABLED=true \
MCPGATEWAY_ADMIN_API_ENABLED=true \
[email protected] \
PLATFORM_ADMIN_PASSWORD=changeme \
PLATFORM_ADMIN_FULL_NAME="Platform Administrator" \
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

# Or better: use the provided .env.example
cp .env.example .env
# Edit .env to customize your settings
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

1 - Install & run (copy-paste friendly)

# 1️⃣  Isolated env + install from pypi
mkdir mcpgateway && cd mcpgateway
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install mcp-contextforge-gateway

# 2️⃣  Copy and customize the configuration
# Download the example environment file
curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
cp .env.example .env
# Edit .env to customize your settings (especially passwords!)

# Or set environment variables directly:
export MCPGATEWAY_UI_ENABLED=true
export MCPGATEWAY_ADMIN_API_ENABLED=true
export [email protected]
export PLATFORM_ADMIN_PASSWORD=changeme
export PLATFORM_ADMIN_FULL_NAME="Platform Administrator"

BASIC_AUTH_PASSWORD=pass JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \
  mcpgateway --host 0.0.0.0 --port 4444 &   # admin/pass

# 3️⃣  Generate a bearer token & smoke-test the API
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
    --username [email protected] --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)

curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     http://127.0.0.1:4444/version | jq

---

Quick Start - Containers

Use the official OCI image from GHCR with Docker or Podman. Please note: Currently, arm64 is not supported on production. If you are e.g. running on MacOS with Apple Silicon chips (M1, M2, etc), you can run the containers using Rosetta or install via PyPi instead.

🚀 Quick Start - Docker Compose

Get a full stack running with PostgreSQL and Redis in under 30 seconds:

# Clone and start the stack
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge

# Start with PostgreSQL (recommended for production)
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f gateway

# Access Admin UI: http://localhost:8080/admin (login with PLATFORM_ADMIN_EMAIL/PASSWORD)
# Generate API token
docker compose exec gateway python3 -m mcpgateway.utils.create_jwt_token \
  --username [email protected] --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes

What you get:

• 🗄️ PostgreSQL - Production-ready database with 55+ tables
• 🚀 ContextForge - Full-featured gateway with Admin UI
• 📊 Redis - High-performance caching and session storage
• 🔧 Admin Tools - pgAdmin, Redis Insight for database management
• 🌐 Nginx Proxy - Caching reverse proxy on port 8080

Enable HTTPS (optional):

# Start with TLS enabled (auto-generates self-signed certs)
make compose-tls

# Access via HTTPS: https://localhost:8443/admin

# Or bring your own certificates:
# Unencrypted key:
mkdir -p certs
cp your-cert.pem certs/cert.pem && cp your-key.pem certs/key.pem
make compose-tls

# Passphrase-protected key:
mkdir -p certs
cp your-cert.pem certs/cert.pem && cp your-encrypted-key.pem certs/key-encrypted.pem
echo "KEY_FILE_PASSWORD=your-passphrase" >> .env
make compose-tls

☸️ Quick Start - Helm (Kubernetes)

Deploy to Kubernetes with enterprise-grade features:

# Add Helm repository (when available)
# helm repo add mcp-context-forge https://ibm.github.io/mcp-context-forge
# helm repo update

# For now, use local chart
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge/charts/mcp-stack

# Install with PostgreSQL (default)
helm install mcp-gateway . \
  --set mcpContextForge.secret.PLATFORM_ADMIN_EMAIL=admin@yourcompany.com \
  --set mcpContextForge.secret.PLATFORM_ADMIN_PASSWORD=changeme \
  --set mcpContextForge.secret.JWT_SECRET_KEY=your-secret-key

# Check deployment status
kubectl get pods -l app.kubernetes.io/name=mcp-context-forge

# Port forward to access Admin UI
kubectl port-forward svc/mcp-gateway-mcp-context-forge 4444:80
# Access: http://localhost:4444/admin

# Generate API token
kubectl exec deployment/mcp-gateway-mcp-context-forge -- \
  python3 -m mcpgateway.utils.create_jwt_token \
  --username [email protected] --exp 10080 --secret your-secret-key

SSRF note: Helm defaults to strict SSRF settings (SSRF_ALLOW_PRIVATE_NETWORKS=false). If you register in-cluster tool URLs (for example fast-time or fast-test services), allow only your cluster CIDRs via mcpContextForge.config.SSRF_ALLOWED_NETWORKS or, for local-only benchmark setups, temporarily set SSRF_ALLOW_PRIVATE_NETWORKS=true. See docs/docs/manage/configuration.md#ssrf-protection and docs/docs/deployment/helm.md.

Enterprise Features:

• 🔄 Auto-scaling - HPA with CPU/memory targets
• 🗄️ Database Choice - PostgreSQL (prod), SQLite (dev)
• 📊 Observability - Prometheus metrics, OpenTelemetry tracing
• 🔒 Security - RBAC, network policies, secret management
• 🚀 High Availability - Multi-replica deployments with Redis clustering
• 📈 Monitoring - Built-in Grafana dashboards and alerting

---

🐳 Docker (Single Container)

docker run -d --name mcpgateway \
  -p 4444:4444 \
  -e MCPGATEWAY_UI_ENABLED=true \
  -e MCPGATEWAY_ADMIN_API_ENABLED=true \
  -e HOST=0.0.0.0 \
  -e JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \
  -e AUTH_REQUIRED=true \
  -e [email protected] \
  -e PLATFORM_ADMIN_PASSWORD=changeme \
  -e PLATFORM_ADMIN_FULL_NAME="Platform Administrator" \
  -e DATABASE_URL=sqlite:///./mcp.db \
  -e SECURE_COOKIES=false \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3

# Tail logs and generate API key
docker logs -f mcpgateway
docker run --rm -it ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3 \
  python3 -m mcpgateway.utils.create_jwt_token --username [email protected] --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes

Browse to http://localhost:4444/admin and login with PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD.

---

🦭 Podman (rootless-friendly)

podman run -d --name mcpgateway \
  -p 4444:4444 -e HOST=0.0.0.0 -e DATABASE_URL=sqlite:///./mcp.db \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3

---

---

---

---

Quick Start: VS Code Dev Container

Clone the repo and open in VS Code—it will detect .devcontainer and prompt to “Reopen in Container”. The container includes Python 3.11, Docker CLI, and all project dependencies.

For detailed setup, workflows, and GitHub Codespaces instructions, see Developer Onboarding.

---

Installation

make venv install-dev      # create .venv + install deps + build Admin UI
make serve                 # gunicorn on :4444

Rust workspace note:

• Workspace-owned Rust crates live under crates/ and are picked up by the root Cargo.toml via crates/*.
• Run cargo build, cargo test, and cargo check from the repo root to cover the shared workspace.
• Rust sample servers under mcp-servers/rust/ are usually managed separately; workspace-owned ones are listed explicitly in the root Cargo.toml.
• make venv install-dev creates the root .venv, which is also reused by the workspace’s PyO3/maturin builds.

---

Upgrading

For upgrade instructions, migration guides, and rollback procedures, see:

• Upgrade Guide — General upgrade procedures
• MIGRATION.md — Breaking changes and step-by-step upgrade instructions
• CHANGELOG.md — Version history and breaking changes

---

Configuration

⚠️ If any required .env variable is missing or invalid, the gateway will fail fast at startup with a validation error via Pydantic.

Copy the provided .env.example to .env and update the security-sensitive values below.

🔐 Required: Change Before Use

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

🔒 Security Defaults (Secure by Default)

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

🛡️ Content Security

Content size limits prevent DoS attacks and ensure system stability:

Note: Size limits apply only to new create/update operations. Existing content is not retroactively validated.

🌐 UAID Cross-Gateway Routing Security

UAID Security Configuration

Production Requirements:

Cross-gateway UAID routing requires explicit security configuration:

1. Configure Domain Allowlist:

   UAID_ALLOWED_DOMAINS=["gateway1.example.com", "gateway2.example.com"]
   

2. Ensure JWT Trust:

   • Both gateways must trust the same JWT issuer
   • Option A: Shared secret (same JWT_SECRET_KEY on all gateways)
   • Option B: Federated SSO (Google, GitHub, Entra ID)

3. Enable Authentication:

   AUTH_REQUIRED=true
   UAID_FORWARD_AUTH=true
   

Authentication Flow:

Cross-gateway calls forward the user’s bearer token via the Authorization header. Remote gateways validate tokens through existing auth middleware, preserving RBAC context.

Security Features:

• ✅ Fail-closed default: Empty allowlist blocks all cross-gateway routing
• ✅ Bearer token forwarding: User authentication preserved across hops
• ✅ Audit trail: Source gateway and user tracked in headers
• ✅ Clear error messages: Misconfigurations caught at startup and runtime

Troubleshooting:

• “UAID_ALLOWED_DOMAINS not configured” error: Add trusted domains to allowlist in .env
• 401/403 from remote gateway: Verify both gateways trust same JWT issuer
• “proceeding without authentication token” warning: Check auth middleware extracts token to request.state.bearer_token

For detailed security architecture, see docs/security/uaid-cross-gateway-auth.md.

⚙️ Project Defaults (Dev Setup)

These values differ from code defaults to provide a working local/dev setup:

📚 Full Configuration Reference

For the complete list of 300+ environment variables organized by category (authentication, caching, SSO, observability, etc.), see the Configuration Reference.

---

Running

Quick Reference

Development Server (Uvicorn)

make dev                 # Uvicorn on :8000 with auto-reload and SQLite
# or
./run.sh --reload --log debug --workers 2

run.sh is a wrapper around uvicorn that loads .env, supports reload, and passes arguments to the server.

Key flags:

Production Server (Gunicorn)

make serve               # Gunicorn on :4444 with multiple workers
make serve-ssl           # Gunicorn behind HTTPS on :4444 (uses ./certs)

Docker Compose (Full Stack)

make compose-up          # Start full stack: PostgreSQL, Redis, 3 gateway replicas, Nginx on :8080
make compose-sso         # Start SSO stack with Keycloak on :8180
make sso-test-login      # Run SSO smoke checks (providers + login URL + test users)
make compose-logs        # Tail logs from all services
make compose-down        # Stop the stack

Manual (Uvicorn)

uvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444 --workers 4

---

Cloud Deployment

ContextForge can be deployed to any major cloud platform:

For comprehensive deployment guides, see Deployment Documentation.

---

API Reference

Interactive API documentation is available when the server is running:

• Swagger UI — Try API calls directly in your browser
• ReDoc — Browse the complete endpoint reference

Quick Authentication:

# Generate a JWT token
export TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
  --username [email protected] --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)

# Test API access
curl -H "Authorization: Bearer $TOKEN" http://localhost:4444/health

For comprehensive curl examples covering all endpoints, see the API Usage Guide.

---

Testing

make test            # Run unit tests
make lint            # Run all linters
make doctest         # Run doctests
make coverage        # Generate coverage report

See Doctest Coverage Guide for documentation testing details.

---

Project Structure

mcpgateway/          # Core FastAPI application
├── main.py          # Entry point
├── config.py        # Pydantic Settings configuration
├── db.py            # SQLAlchemy ORM models
├── schemas.py       # Pydantic validation schemas
├── services/        # Business logic layer (50+ services)
├── routers/         # HTTP endpoint definitions
├── middleware/      # Cross-cutting concerns
└── transports/      # SSE, WebSocket, stdio, streamable HTTP

tests/               # Test suite (7,000+ tests)
docs/docs/           # Full documentation (MkDocs)
charts/              # Kubernetes/Helm charts
plugins/             # Plugin framework and implementations
mcp-servers/         # Sample/test MCP servers (see note below)

Note: The mcp-servers/ directory contains unsupported sample and test servers, most originating from community contributions, provided for demonstration and integration testing purposes only. They generally lack session management, persistent state, multi-tenancy, authentication, and other production concerns. They do not go through the same review, testing, and security rigor as the core ContextForge codebase and should not be run in production.

Security: Never run untrusted MCP servers directly on your local filesystem. Always use a sandbox, container, or microVM (e.g. gVisor, Firecracker) with restricted capabilities. Exercise caution when registering any remote MCP server, including servers from public catalogs — perform your own security evaluation before granting access to your gateway.

For complete structure, see CONTRIBUTING.md or run tree -L 2.

---

Development

make dev             # Dev server with auto-reload (:8000)
make test            # Run test suite
make lint            # Run all linters
make coverage        # Generate coverage report

Run make to see all available targets.

For development workflows, see:

• Developer Workstation Setup
• Building & Packaging

---

Troubleshooting

Common issues and solutions:

For detailed troubleshooting guides, see Troubleshooting Documentation.

---

Contributing

1. Fork the repo, create a feature branch.
2. Run make lint and fix any issues.
3. Keep make test green.
4. Open a PR with signed commits (git commit -s).

See CONTRIBUTING.md for full guidelines and Issue Guide #2502 for how to file bugs, request features, and find issues to work on.

---

Changelog

A complete changelog can be found here: CHANGELOG.md

License

Licensed under the Apache License 2.0 - see LICENSE

Core Authors and Maintainers

• Mihai Criveti - Distinguished Engineer, Agentic AI

Special thanks to our contributors for helping us improve ContextForge:

Star History and Project Activity