✨ Features Overview¶

ContextForge is an open source registry and proxy that federates MCP, A2A, and REST/gRPC APIs with centralized governance, discovery, and observability. It provides MCP federation, agent and tool call optimization, rate limiting, auth, caching, plugins, and an HTMX-powered Admin UI.

Gateway URL

Direct installs (uvx, pip, or docker run): http://localhost:4444
Docker Compose (nginx proxy): http://localhost:8080

🌐 Multi-Transport Core¶

Supported Transports

Transport	Description	Typical Use-case
HTTP / JSON-RPC	Low-latency request-response, default for most REST clients	Simple tool invocations
WebSocket	Bi-directional, full-duplex	Streaming chat or incremental tool results
Server-Sent Events (SSE)	Uni-directional server → client stream	LLM completions or real-time updates
STDIO	Local process pipes via `mcpgateway-wrapper`	Editor plugins, headless CLI clients

Try it: SSE from curl

curl -N -H "Accept: text/event-stream" \
     -H "Authorization: Bearer $TOKEN" \
     http://localhost:4444/servers/UUID_OF_SERVER_1/sse

🔐 Security¶

Auth mechanisms

JWT bearer (default, signed with JWT_SECRET_KEY)
Email/password for the Admin UI (PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD)
HTTP Basic (optional) for API/docs when API_ALLOW_BASIC_AUTH=true or DOCS_ALLOW_BASIC_AUTH=true
Custom headers (e.g., API keys) per tool or gateway

Rate limiting

Set MAX_TOOL_CALLS_PER_MINUTE to throttle abusive clients. Exceeding the limit returns HTTP 429 with a Retry-After header.

Generate a 24 h token

python3 -m mcpgateway.utils.create_jwt_token \
  --username alice --exp 1440 --secret "$JWT_SECRET_KEY"

🛠 Tool & Server Registry¶

What you can register

Registry	Entities	Notes
Tools	Native MCP tools or wrapped REST / CLI functions	JSON Schema input validation
Resources	URIs for blobs, text, images	Optional SSE change notifications
Prompts	Jinja2 templates + multimodal content	Versioning & rollback
Servers	Virtual collections of tools/prompts/resources	Exposed as full MCP servers
gRPC Services	gRPC microservices via automatic reflection	Protocol translation to MCP/JSON

REST tool example

curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "joke_api",
           "url": "https://icanhazdadjoke.com/",
           "requestType": "GET",
           "integrationType": "REST",
           "headers": {"Accept":"application/json"}
         }' \
     http://localhost:4444/tools

🧠 LLM Providers & Chat¶

The LLM Gateway unifies multiple AI providers behind a single OpenAI-compatible API surface, and provides an interactive chat agent that connects LLMs to MCP virtual servers. All LLM features are controlled by the master flag LLMCHAT_ENABLED (default: true).

LLM Architecture

The LLM Gateway consists of three surfaces (all loaded under LLMCHAT_ENABLED=true):

Provider registry — multi-provider configuration with encrypted API keys, health checks, and auto-synchronization of available models from upstream providers. Supports 12 provider types: OpenAI, Azure OpenAI, Anthropic, AWS Bedrock, Google Vertex, WatsonX, Ollama, OpenAI-compatible, Cohere, Mistral, Groq, and Together.
OpenAI-compatible proxy — POST /v1/chat/completions and GET /v1/models, a drop-in substitute for the OpenAI API. Routes to the configured provider based on the model ID. Returns standard OpenAI chat/completion responses including streaming (SSE).
Chat agent — an optional, session-oriented chat layer (/llmchat/*) powered by LangChain. Connects a selected LLM to one or more MCP virtual servers, creating a ReAct agent that can invoke MCP tools during conversation. Features include chat history (Redis-backed), streaming responses, thinking/reasoning display, and multi-worker session management.

LLM Provider Management

Providers are configured via the Admin UI (Settings → LLM Settings).

Add a provider, select the type, enter API keys and configuration parameters. API keys are encrypted at rest.
Each provider can register multiple models with capability flags (chat, streaming, function calling, vision), context windows, and max-output limits.
Auto-sync available models from the provider's API with one click.
Health checks verify connectivity and credentials.
Enable/disable providers and individual models via toggle switches.

OpenAI-Compatible Proxy

The proxy endpoint (POST /v1/chat/completions, configurable prefix via LLM_API_PREFIX) accepts standard OpenAI request bodies and returns Chat Completion or Chat Completion Chunk responses. Clients never need provider-specific keys or URLs; the gateway resolves the target provider from the database.

RBAC: requires llm.invoke permission for completions, llm.read for models endpoint.

Chat Agent

Chat sessions are initialized via POST /llmchat/connect: select an MCP virtual server, choose a model, and a LangChain ReAct agent is created. Messages sent over POST /llmchat/chat are processed with MCP tool execution feedback interwoven in the conversation.

Session state, chat history, and model configuration are stored per-user (Redis-backed in multi-worker deployments with automatic cleanup on disconnect).

Feature flag

All LLM features (proxy, config, admin, chat) are loaded under a single condition: LLMCHAT_ENABLED=true. Set LLMCHAT_ENABLED=false to completely disable all LLM services.

See also: - LLM Proxy API — OpenAI-compatible proxy endpoint documentation - LLM Provider Settings — Admin UI guide for configuring providers and models - LLM Chat — Interactive chat agent with MCP tool integration

💰 Cost Control (ToolOps)¶

Costs per tool call

Tool-level cost calculation using per-model pricing
Prompt & completion token usage tracking
Cost breakdown per-called with tool-level and total cost summaries
Cost thresholds to prevent runaway spend
Per-tool throttling to control expensive operations
Historical data for optimization
Budget alerts

Enable ToolOps

# Set in your environment or .env file
TOOLOPS_ENABLED=true
TOOLOPS_AUTHORIZATION=<token>

🔌 gRPC-to-MCP Translation¶

Automatic gRPC Integration

Server Reflection - Automatically discovers gRPC services and methods
Protocol Translation - Converts between gRPC/Protobuf ↔ MCP/JSON
Zero Configuration - No manual schema definition required
TLS Support - Secure connections to gRPC servers
Metadata Headers - Custom gRPC metadata for authentication
Admin UI - Manage gRPC services via web interface

Register a gRPC service

# CLI: Expose gRPC service via HTTP/SSE
python3 -m mcpgateway.translate --grpc localhost:50051 --port 9000

# REST API: Register for persistence
curl -X POST -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "payment-service",
           "target": "payments.example.com:50051",
           "reflection_enabled": true,
           "tls_enabled": true
         }' \
     http://localhost:4444/grpc

How it works

Gateway connects to gRPC server using Server Reflection Protocol
Discovers all available services and methods automatically
Translates Protobuf messages to/from JSON
Exposes each gRPC method as an MCP tool
Handles streaming (unary and server-streaming)

Supported gRPC features

Feature	Status	Notes
Unary RPCs	✅ Supported	Request-response methods
Server Streaming	⚠️ Partial	Basic support implemented
Client Streaming	🚧 Planned	Future enhancement
Bidirectional Streaming	🚧 Planned	Future enhancement
TLS/mTLS	✅ Supported	Certificate-based auth
Metadata Headers	✅ Supported	Custom headers for auth
Reflection	✅ Required	Auto-discovery mechanism

🖥 Admin UI¶

Built with

FastAPI + Jinja2 + HTMX + Alpine.js
Tailwind CSS for styling

📊 Audit & Metadata Tracking

Comprehensive metadata for all entities (Tools, Resources, Prompts, Servers, Gateways)
Creation tracking - who, when, from where, how
Modification history - change attribution and versioning
Federation source tracking for MCP server entities
Bulk import batch identification
Auth-agnostic - works with/without authentication
Backwards compatible - legacy entities show graceful fallbacks

🗄 Persistence, Caching & Observability¶

Storage options

SQLite (default, development)
PostgreSQL (recommended for production) - via DATABASE_URL

Redis cache

CACHE_TYPE=redis
REDIS_URL=redis://localhost:6379/0

Observability

Structured JSON logs (tap with jq)
/metrics - Prometheus-friendly counters (tool_calls_total, gateway_up)
/health - readiness + dependency checks

🧩 Dev & Extensibility¶

Highlights

Makefile targets - make dev, make test, make lint
400+ unit tests - Pytest + HTTPX TestClient
VS Code Dev Container - Python 3.11 + Docker/Podman CLI
Plug-in friendly - drop-in FastAPI routers or Pydantic models

Next Steps¶

Hands-on Walk-through → Quick Start
Deployment Guides → Compose, K8s & Cloud
Admin UI deep dive → UI Guide

Ready to explore

With transports, federation, and security handled for you, focus on building great MCP tools, prompts, and agents-the gateway has your back.