ContextForge Gateway

What does this agent do, and when should you use it?

ContextForge is IBM's open-source registry and proxy for federating MCP servers, A2A servers, and REST/gRPC APIs. Its FastAPI application lives in mcpgateway/ and includes routers, middleware, service-layer components, and SSE, WebSocket, stdio, and streamable-HTTP transports. It can virtualize REST services and reflection-discovered gRPC services as MCP tools, then group registered tools into virtual MCP servers. The gateway adds authentication, retries, rate limiting, centralized discovery, and OpenTelemetry observability for Phoenix, Jaeger, Zipkin, and other OTLP backends. It can run from PyPI, containers, Docker Compose, or Helm; the full container stack uses PostgreSQL, Redis, Nginx, and multiple gateway replicas.

An administrator can register an MCP endpoint with POST /gateways, read the resulting catalog through GET /tools, and create a virtual server with POST /servers using associated_tools. A client then connects to /servers/UUID_OF_SERVER_1/mcp over streamable HTTP. mcpgateway.translate can run a stdio command such as uvx mcp-server-git and expose both /sse and /mcp; it can also discover gRPC services and methods through server reflection for gRPC-to-MCP translation. At runtime, the gateway can apply authentication, retries, rate limiting, and reverse-proxy behavior, while emitting OpenTelemetry traces for gateway, tool, prompt, and resource operations. mcpgateway.wrapper uses MCP_AUTH and MCP_SERVER_URL to present an authenticated remote gateway as a stdio process for MCP clients.

1. A platform engineering team needs one authenticated, observable discovery endpoint for several internal MCP services.
2. A backend team wants to expose an existing REST API as MCP tools without rewriting the service.
3. A team operating gRPC services wants reflection-based service and method discovery for MCP clients.
4. An organization routing OpenAI, Anthropic, and custom external agents needs an A2A-capable gateway layer.
5. An infrastructure team needs to deploy tool infrastructure across Kubernetes clusters with Redis-backed caching and federation.
6. A user of a stdio-only MCP client needs to reach an authenticated remote gateway through mcpgateway.wrapper.

What are this agent's strengths and limitations?

How do you install or deploy this agent?

Python 3.11 or later is required. Install the PyPI package and generate the required secrets:

python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install mcp-contextforge-gateway
curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
cp .env.example .env
python3 -m mcpgateway.scripts.init_secrets --patch-env .env
mcpgateway --host 0.0.0.0 --port 4444

JWT_SECRET_KEY and AUTH_ENCRYPTION_SECRET must contain real values or the gateway will fail at startup.

How do you use this agent?

Read the JWT secret from .env and create a token:

export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username [email protected] --exp 10080 --secret "$JWT_SECRET_KEY")

Register an SSE MCP service:

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

Then retrieve tool IDs with GET /tools, POST a server object with name, description, and associated_tools to /servers, and point an MCP client to http://localhost:4444/servers/UUID_OF_SERVER_1/mcp. A running instance also exposes /docs, /redoc, /health, and /version.

FAQ