mcp-context-forge

Federates multiple Model Context Protocol (MCP) servers into a single unified HTTP/SSE endpoint using a transport abstraction layer that handles protocol translation. The gateway maintains a ServerRegistry that tracks all connected MCP servers, routes incoming requests through a ToolService that normalizes tool schemas across heterogeneous servers, and exposes both streamable HTTP and SSE transports via FastAPI endpoints (streamable_http_auth, sse_endpoint). This enables clients to interact with dozens of MCP servers through a single gateway URL without managing individual server connections.

Implements a middleware-based authentication system (RBAC middleware in mcpgateway/middleware/rbac.py) that enforces role-based access control across all federated servers and tools. The gateway supports JWT token validation, OAuth/SSO integration, and multi-tenant isolation via a SessionRegistry that tracks authenticated sessions and their associated permissions. Each request is validated against a permission matrix that maps users/teams to allowed tools and servers, with enforcement happening at the gateway layer before requests reach downstream MCP servers or APIs.

Implements a guardrail system that enforces policies on tool execution through pre-execution validation and post-execution result filtering. Pre-execution hooks validate tool invocations against policies (e.g., rate limits, cost budgets, parameter constraints) and can reject or modify requests. Post-execution hooks filter or transform results based on policies (e.g., redact sensitive data, enforce output size limits). Policies are defined declaratively in configuration and can be customized per tool, user, or team. The guardrail system integrates with the plugin system, allowing custom policies to be implemented as plugins.

Provides export/import functionality that enables administrators to backup and migrate gateway state (tool definitions, RBAC rules, plugin configurations) between gateway instances. Export generates a JSON or YAML file containing all gateway configuration and tool metadata. Import reads this file and restores the gateway state, enabling disaster recovery and environment promotion (dev → staging → prod). The export/import system preserves all metadata and relationships, enabling lossless round-trip migrations.

Provides production-ready Kubernetes deployment through Helm charts (in charts/mcp-stack/) that configure the gateway, database, Redis cache, and nginx ingress as a complete stack. The Helm charts support auto-scaling based on metrics (CPU, memory, request latency), enabling the gateway to scale horizontally under load. Deployment includes health checks (liveness and readiness probes), resource limits, and pod disruption budgets for high availability. The charts are parameterized to support multiple environments (dev, staging, prod) through Helm values overrides.

Provides a Docker Compose configuration (docker-compose.yml) that spins up a complete local development environment with the gateway, PostgreSQL database, Redis cache, and nginx reverse proxy. The Compose file includes environment variable configuration, volume mounts for code changes (enabling hot-reload during development), and networking setup. This enables developers to run the entire gateway stack locally without installing dependencies, facilitating rapid iteration and testing.

Implements a multi-layer caching strategy using Redis as the distributed cache backend, with cache keys derived from tool name, parameters, and user context. The gateway caches tool invocation results based on configurable TTL policies and cache invalidation rules (e.g., invalidate cache for tool X when tool Y is invoked). Cache hits bypass downstream MCP servers entirely, reducing latency and load. The caching layer is transparent to clients and respects RBAC boundaries (cached results are isolated per user/team).

Exposes the same underlying tool registry through multiple transport protocols simultaneously: streamable HTTP with authentication (streamable_http_auth endpoint), Server-Sent Events (SSE) for streaming responses, and gRPC for high-performance integrations. The transport layer abstracts protocol-specific details (request/response serialization, streaming semantics, error handling) through a common interface, allowing clients to choose their preferred transport without gateway reconfiguration. This is implemented via transport adapters that translate between MCP JSON-RPC messages and protocol-specific formats.

Implements a ToolService that discovers all available tools from federated MCP servers, normalizes their schemas into a unified format, and exposes them via a discovery API. The gateway periodically polls connected servers for tool updates, caches the normalized schemas, and serves them to clients through a single /tools endpoint. Schema normalization handles differences in parameter types, descriptions, and required fields across servers, presenting a consistent interface to clients regardless of upstream server implementation details.

Provides a plugin architecture that allows developers to extend gateway behavior through custom middleware, tool handlers, and event listeners. Plugins are loaded from a plugins directory, registered with the FastAPI application, and can hook into request/response lifecycle events (pre-tool-invocation, post-tool-invocation, on-error). The plugin system uses a standardized interface (BasePlugin class) that plugins implement to add custom logic like request transformation, response filtering, or integration with external systems. Plugins have access to the gateway's service layer (ToolService, GatewayService) for deep integration.

Provides comprehensive observability through structured logging (JSON format with context fields), metrics collection (request latency, cache hit rates, tool invocation counts), and integration with monitoring backends (Prometheus, OpenTelemetry). The gateway logs all tool invocations with context (user, team, tool name, parameters, result, duration), enabling audit trails and performance analysis. Metrics are exported in Prometheus format and can be scraped by monitoring systems. Distributed tracing support (via OpenTelemetry) enables end-to-end request tracking across the gateway and downstream services.

Supports multiple configuration sources (environment variables, YAML files, environment-specific overrides) with a unified config schema (defined in config.py and config.schema.json). Configuration is loaded at startup and can be partially updated at runtime through the admin API without full gateway restart. The config system uses Pydantic for validation and type-checking, ensuring invalid configurations are caught early. Sensitive values (API keys, database credentials) are stored in .env files or secrets management systems and are not logged or exposed in debug output.

Provides an A2A gateway that enables agents to discover and invoke other agents through a unified endpoint, similar to how agents invoke tools. The A2A gateway maintains an agent registry, handles agent authentication and authorization, and routes agent-to-agent requests through the same middleware stack (RBAC, caching, observability) as tool invocations. This enables complex multi-agent workflows where agents can coordinate with each other without direct peer-to-peer connections, with all communication flowing through the gateway for governance and observability.

Implements a SessionRegistry that tracks active sessions (authenticated user connections) with associated metadata (user ID, team, permissions, session start time). The gateway emits events for significant state changes (tool invocation, cache invalidation, permission changes) through an event service that can be consumed by clients via WebSocket or SSE. This enables real-time updates to clients when gateway state changes, supporting use cases like live tool execution monitoring and collaborative tool usage tracking.