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

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

---

🔌 Gateway Layer with Protocol Flexibility

• 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

🧩 Virtualization of REST/gRPC Services

• 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

🔁 REST-to-MCP Tool Adapter

• Adapts REST APIs into tools with:

• Automatic JSON Schema extraction

• Support for headers, tokens, and custom auth
• Retry, timeout, and rate-limit policies

🧠 Unified Registries

• 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, Observability & Dev Experience

• 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

🔍 OpenTelemetry Observability

• 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.

---

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 \
PLATFORM_ADMIN_EMAIL=admin@example.com \
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

📋 Prerequisites

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

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 PLATFORM_ADMIN_EMAIL=admin@example.com
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 admin@example.com --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

Windows (PowerShell) quick-start

# 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️⃣  Copy and customize the configuration
# Download the example environment file
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example" -OutFile ".env.example"
Copy-Item .env.example .env
# Edit .env to customize your settings

# Or set environment variables (session-only)
$Env:MCPGATEWAY_UI_ENABLED        = "true"
$Env:MCPGATEWAY_ADMIN_API_ENABLED = "true"
# Note: Basic auth for API is disabled by default (API_ALLOW_BASIC_AUTH=false)
$Env:JWT_SECRET_KEY               = "my-test-key-but-now-longer-than-32-bytes"
$Env:PLATFORM_ADMIN_EMAIL         = "admin@example.com"
$Env:PLATFORM_ADMIN_PASSWORD      = "changeme"
$Env:PLATFORM_ADMIN_FULL_NAME     = "Platform Administrator"

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

#   Optional: background it
# Start-Process -FilePath "mcpgateway.exe" -ArgumentList "--host 0.0.0.0 --port 4444"

# 4️⃣  Bearer token and smoke-test
$Env: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

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

⚡ Alternative: uv (faster)

# 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...

More configuration

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

🚀 End-to-end demo (register a local MCP server)

```bash

1️⃣ Spin up the sample GO 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/fast-time-server:latest -transport=stdio" \ --expose-sse \ --port 8003

Or using the official mcp-server-git using uvx:

pip install uv # to install uvx, if not already installed python3 -m mcpgateway.translate --stdio "uvx mcp-server-git" --expose-sse --port 9000

Alternative: running the local binary

cd mcp-servers/go/fast-time-server; make build

python3 -m mcpgateway.translate --stdio "./dist/fast-time-server -transport=stdio" --expose-sse --port 8002

NEW: Expose via multiple protocols simultaneously!

python3 -m mcpgateway.translate \ --stdio "uvx mcp-server-git" \ --expose-sse \ --expose-streamable-http \ --port 9000

Now accessible via both /sse (SSE) and /mcp (streamable HTTP) endpoints

2️⃣ Register it with the gateway

curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"fast_time","url":"http://localhost:8003/sse"}' \ http://localhost:4444/gateways

3️⃣ Verify tool catalog

curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools | jq

4️⃣ Create a virtual server bundling those tools. Use the ID of tools from the tool catalog (Step #3) and pass them in the associatedTools list.

curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ -H "Content-Type: application/json" \ -d '{"server":{"name":"time_server","description":"Fast time tools","associated_tools":[]}}' \ http://localhost:4444/servers | jq

Example curl

curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ -H "Content-Type: application/json" \ -d '{"server":{"name":"time_server","description":"Fast time tools","associated_tools":["6018ca46d32a4ac6b4c054c13a1726a2"]}}' \ http://localhost:4444/servers | jq

5️⃣ List servers (should now include the UUID of the newl