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.

<!-- === CI / Security / Build Badges === -->

     

<!-- === Package / Container === -->

     

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.

<!-- vscode-markdown-toc -->

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

| Resource | Description | |----------|-------------| | 5-Minute Setup | Get started fast — uvx, Docker, Compose, or local dev | | Getting Help | Support options, FAQ, community channels | | Issue Guide | How to file bugs, request features, contribute | | Full Documentation | Complete guides, tutorials, API reference | | Deprecations | Deprecated runtime paths and migration guidance |

---

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

---

<details> <summary><strong>🔌 Gateway Layer with Protocol Flexibility</strong></summary>

• Federates any MCP server or REST API
• Lets you choose your MCP protocol version (e.g., 2025-11-25)
• Exposes a single, unified interface for diverse backends

</details> <details> <summary><strong>🧩 Virtualization of REST/gRPC Services</strong></summary>

• 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

</details> <details> <summary><strong>🔁 REST-to-MCP Tool Adapter</strong></summary>

• Adapts REST APIs into tools with:

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

</details> <details> <summary><strong>🧠 Unified Registries</strong></summary>

• 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

</details> <details> <summary><strong>📈 Admin UI, Observability & Dev Experience</strong></summary>

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

</details> <details> <summary><strong>🔍 OpenTelemetry Observability</strong></summary>

• 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

See Observability Documentation for setup guides with Phoenix, Jaeger, and other backends.

</details>

---

Quick Start - PyPI

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

---

⚠️ JWT_SECRET_KEY and AUTH_ENCRYPTION_SECRET are required in every environment — including local development. The gateway will not start without them. Generate real secrets with python3 -m mcpgateway.scripts.init_secrets before first run.

TLDR — single command using uv:

# 1️⃣  Generate secure secrets (creates .env.secrets)
python3 -m mcpgateway.scripts.init_secrets

# 2️⃣  Export the generated values
export JWT_SECRET_KEY="$(grep '^JWT_SECRET_KEY=' .env.secrets | cut -d= -f2)"
export AUTH_ENCRYPTION_SECRET="$(grep '^AUTH_ENCRYPTION_SECRET=' .env.secrets | cut -d= -f2)"

# 3️⃣  Start the gateway
JWT_SECRET_KEY="$JWT_SECRET_KEY" \
AUTH_ENCRYPTION_SECRET="$AUTH_ENCRYPTION_SECRET" \
MCPGATEWAY_UI_ENABLED=true \
MCPGATEWAY_ADMIN_API_ENABLED=true \
PLATFORM_ADMIN_EMAIL=admin@example.com \
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

<details> <summary><strong>📋 Prerequisites</strong></summary>

• Python ≥ 3.11
• curl + jq - only for the last smoke-test step

</details>

1 - Install & run (copy-paste friendly)

# 1️⃣  Create an isolated env and 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️⃣  Download .env.example and generate real secrets
curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
cp .env.example .env

# Generate cryptographically secure secrets into .env.secrets
python3 -m mcpgateway.scripts.init_secrets

# Patch the generated secrets into .env (replaces __REPLACE_ME__ placeholders)
python3 -m mcpgateway.scripts.init_secrets --patch-env .env

# 3️⃣  Start the gateway
mcpgateway --host 0.0.0.0 --port 4444 &

# 4️⃣  Generate a bearer token and smoke-test
export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
    --username admin@example.com --exp 10080 --secret "$JWT_SECRET_KEY")

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

<details> <summary><strong>Windows (PowerShell) quick-start</strong></summary>

# 1️⃣  Isolated env + install from PyPI
mkdir mcpgateway ; cd mcpgateway
python3 -m venv .venv ; .\.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install mcp-contextforge-gateway

# 2️⃣  Download .env.example and generate real secrets
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example" -OutFile ".env.example"
Copy-Item .env.example .env

# Generate cryptographically secure secrets into .env.secrets
python3 -m mcpgateway.scripts.init_secrets

# Patch the generated secrets into .env (replaces __REPLACE_ME__ placeholders)
python3 -m mcpgateway.scripts.init_secrets --patch-env .env

# 3️⃣  Launch the gateway
mcpgateway.exe --host 0.0.0.0 --port 4444

# 4️⃣  Bearer token and smoke-test
$Env:JWT_SECRET_KEY = (Get-Content .env | Select-String '^JWT_SECRET_KEY=').ToString().Split('=')[1]
$Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token `
    --username admin@example.com --exp 10080 --secret $Env:JWT_SECRET_KEY

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

<details> <summary><strong>⚡ Alternative: uv (faster)</strong></summary>

# 1️⃣  Isolated env + install from PyPI using uv
mkdir mcpgateway ; cd mcpgateway
uv venv
.\.venv\Scripts\activate
uv pip install mcp-contextforge-gateway

# Continue with steps 2️⃣-4️⃣ above...

</details> </details> <details> <summary><strong>More configuration</strong></summary>

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

</details> <details> <summary><strong>🚀 End-to-end demo (register a local MCP server)</strong></summary>

# 1️⃣  Spin up the sample MCP time server using mcpgateway.translate & docker (replace docker with podman if needed)
python3 -m mcpgateway.translate \
     --stdio "docker run --rm -i ghcr.io/ibm