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), and Streamable HTTP; stdio transport available for server-side use
• 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.

---

⚠️ **`JWT_SECRET_K