MCP Context Forge Project Details

Project Overview

MCP Context Forge is a feature-rich, FastAPI-driven Model Context Protocol (MCP) gateway open-sourced by IBM. It unifies and federates tools, resources, prompts, servers, and peer gateways, wrapping any REST API as an MCP-compliant tool or virtual server. The project supports exposing all functionalities through HTTP/JSON-RPC, WebSocket, Server-Sent Events (SSE), and stdio transport protocols. It also provides a rich interactive management UI, packaged as a container, and supports any SQLAlchemy-supported database.

Core Features

1. Protocol Gateway Functionality

• True Gateway Architecture: Centralized registry for tools, resources, and prompts, while adhering to the official MCP 2025-03-26 protocol standard.
• Multi-Server Federation: Unifies multiple MCP servers into a single endpoint – automatically discovers peer nodes (mDNS or explicit configuration), performs health checks, and merges their functionalities.
• Virtualization Service: Virtualizes non-MCP services into "virtual servers," allowing registration of any REST API or function endpoint and exposing them under MCP semantics.

2. API Adaptation Functionality

• REST to MCP Adapter: Adapts arbitrary REST/HTTP APIs into MCP tools, supporting JSON-Schema input validation, retry/rate limiting policies, and transparent JSON-RPC calls.
• Protocol Conversion: Supports conversion between various transport protocols (stdio, SSE, Streamable HTTP).

3. Deployment and Management

• Complete Management UI: Provides rich transport protocols, pre-built development experience pipelines, and production-grade observability.
• Enterprise-Grade Features: Includes complete functionalities such as authentication and authorization, caching, health checks, and metrics collection.

System Architecture

The project adopts a modular architecture design:

┌─────────────────┐    ┌──────────────────┐
│  🖥️ Admin UI    │    │  🔐 Authentication │
│  Management UI   │    │  JWT + Basic     │
└─────────────────┘    └──────────────────┘
         │                        │
         └────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │        🚪 MCP Gateway Core       │
    │     Protocol Initialization Ping Complete      │
    │        Federation Manager        │
    │   Transport Protocols HTTP WS SSE Stdio  │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │           Service Layer           │
    │  🧰 Tool Service  📁 Resource Service      │
    │  📝 Prompt Service  🧩 Server Service    │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │          Persistence Layer          │
    │    💾 Database SQLAlchemy       │
    │    ⚡ Cache Redis/Memory       │
    └───────────────────────────────┘

Technical Features

Supported Protocols and Transports

• Full MCP 2025-03-26 Support: initialize, ping, notify, completion, sampling (SSE), and JSON-RPC fallback.
• Multiple Transport Protocols: HTTP/JSON-RPC, WebSocket (ping/pong), SSE (unidirectional + return channel), stdio.
• Protocol Conversion: Supports seamless conversion between different transport protocols.

Federation and Discovery

• Auto-Discovery: Supports mDNS or explicitly configured peer gateway discovery.
• Health Checks: Periodic health checks with failover support.
• Transparent Merging: Transparently merges remote registries into a unified directory.

Resource Management

• Templated URIs: Supports parameterized resource URIs.
• Smart Caching: LRU+TTL caching mechanism, MIME type detection.
• Real-time Subscription: Supports SSE real-time subscription to resource changes.

Prompt Management

• Jinja2 Templates: Powerful template engine support.
• Schema Validation: JSON-Schema enforced validation.
• Multi-Modal Support: Supports multi-modal content blocks.
• Version Control: Version management and rollback functionality.

Tool Management

• Multi-Type Support: Native MCP or REST-based tools.
• Input Validation: Complete input validation mechanism.
• Retry Logic: Intelligent retry and rate limiting/concurrency control.

Management and Monitoring Features

Web Management Interface

• Tech Stack: HTMX + Alpine.js + Tailwind CSS
• Complete CRUD: Complete management of servers, tools, resources, prompts, gateways, root directories, and metrics.
• Real-time Monitoring: Real-time status monitoring and log viewing.

Authentication and Authorization

• Multiple Authentication Methods: Basic authentication, JWT Bearer, custom header authentication.
• Fine-Grained Control: Dependency injection control for each endpoint.
• Secure Encryption: AES encrypted storage of tool authentication headers.

Persistence and Migration

• ORM Support: Asynchronous SQLAlchemy ORM (SQLite, PostgreSQL, MySQL, etc.).
• Automatic Migration: Alembic automatic database migration.
• Connection Pool: Complete database connection pool configuration.

Event System and Observability

• Unified Events: Unified event wrapping for WS/SSE fan-out.
• Server-Side Filtering: Server-side event filtering and callback hooks.
• Structured Logging: Structured JSON logging.
• Health Checks: /health endpoint and latency metrics decorator.
• Complete Metrics: Metrics collection for each handler.

Development Experience

Development Tools

• Makefile Targets: Over 100 pre-defined development targets.
• Code Quality: pre-commit hooks (ruff, black, mypy, isort).
• Live Reloading: Development server supports live reloading.
• Test Coverage: 400+ test cases.
• CI/CD: Complete CI badges and automation processes.

Deployment Options

• Containerized Deployment: Docker/Podman support.
• Cloud Native: IBM Cloud Code Engine deployment support.
• Multi-Environment: Development, testing, and production environment configurations.
• SSL/TLS: Complete HTTPS support.

Configuration Options

Basic Configuration

# Application basic configuration
APP_NAME=MCP Gateway
HOST=0.0.0.0
PORT=4444
DATABASE_URL=sqlite:///./mcp.db
APP_ROOT_PATH=/gateway  # Optional sub-path prefix

Authentication Configuration

# Basic authentication (management UI and API)
BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=changeme

# JWT Configuration
JWT_SECRET_KEY=my-test-key
JWT_ALGORITHM=HS256
TOKEN_EXPIRY=10080  # Minutes

# Authentication Control
AUTH_REQUIRED=true
AUTH_ENCRYPTION_SECRET=my-test-salt

Federation Configuration

# Federation Features
FEDERATION_ENABLED=true
FEDERATION_DISCOVERY=false
FEDERATION_PEERS=["http://peer1:4444","http://peer2:4444"]
FEDERATION_TIMEOUT=30
FEDERATION_SYNC_INTERVAL=300

Quick Start

Running with Docker

docker run -d --name mcpgateway \
  -p 4444:4444 \
  -e HOST=0.0.0.0 \
  -e JWT_SECRET_KEY=my-secret-key \
  -e BASIC_AUTH_USER=admin \
  -e BASIC_AUTH_PASSWORD=changeme \
  -e AUTH_REQUIRED=true \
  -e DATABASE_URL=sqlite:///./mcp.db \
  ghcr.io/ibm/mcp-context-forge:latest

Local Development

# Create a virtual environment and install dependencies
make venv install serve

# Or install manually
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
uvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444

Generate Authentication Token

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret my-test-key)

API Usage Examples

Protocol Initialization

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "protocol_version":"2025-03-26",
    "capabilities":{},
    "client_info":{"name":"MyClient","version":"1.0.0"}
  }' \
  http://localhost:4444/protocol/initialize

Register Tool

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "name":"clock_tool",
    "url":"http://localhost:9000/rpc",
    "description":"Returns current time",
    "input_schema":{
      "type":"object",
      "properties":{"timezone":{"type":"string"}},
      "required":[]
    }
  }' \
  http://localhost:4444/tools

Create Prompt Template

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "name":"greet",
    "template":"Hello, {{ user }}!",
    "argument_schema":{
      "type":"object",
      "properties":{"user":{"type":"string"}},
      "required":["user"]
    }
  }' \
  http://localhost:4444/prompts

Deploy to IBM Cloud Code Engine

The project provides complete IBM Cloud Code Engine deployment support:

Environment Configuration

IBMCLOUD_REGION=us-south
IBMCLOUD_RESOURCE_GROUP=default
IBMCLOUD_PROJECT=my-codeengine-project
IBMCLOUD_CODE_ENGINE_APP=mcpgateway
IBMCLOUD_IMAGE_NAME=us.icr.io/myspace/mcpgateway:latest
IBMCLOUD_API_KEY=your_api_key_here

Deployment Commands

make ibmcloud-check-env      # Check environment variables
make ibmcloud-cli-install    # Install IBM Cloud CLI
make ibmcloud-login          # Login to IBM Cloud
make ibmcloud-ce-login       # Select Code Engine project
make ibmcloud-tag            # Tag container image
make ibmcloud-push           # Push to IBM Container Registry
make ibmcloud-deploy         # Deploy to Code Engine

Project Structure

mcpgateway/
├── admin.py                    # FastAPI routes and management UI controller
├── cache/
│   └── resource_cache.py      # In-memory LRU+TTL cache for resources
├── config.py                  # Pydantic settings loader
├── db.py                      # SQLAlchemy ORM models and database setup
├── federation/
│   ├── discovery.py           # Peer gateway discovery
│   ├── forward.py             # RPC forwarding logic
│   └── manager.py             # Federation coordination and health checks
├── handlers/
│   └── sampling.py            # MCP streaming sampling request handler
├── services/
│   ├── completion_service.py  # Prompt and resource parameter completion logic
│   ├── gateway_service.py     # Peer gateway registration and management
│   ├── prompt_service.py      # Prompt template CRUD and rendering
│   ├── resource_service.py    # Resource registration, retrieval, subscription
│   ├── server_service.py      # Server registration and health monitoring
│   └── tool_service.py        # Tool registration, invocation, metrics
├── transports/
│   ├── sse_transport.py       # Server-Sent Events transport
│   ├── stdio_transport.py     # stdio transport
│   └── websocket_transport.py # WebSocket transport
└── utils/
    ├── create_jwt_token.py    # JWT generation and verification tool
    └── verify_credentials.py # FastAPI authentication dependency

Development and Contribution

Development Environment Setup

# Install development dependencies
make install-dev

# Run code checks
make lint

# Run tests
make test

# Run coverage tests
make coverage

Code Quality Tools

The project integrates various code quality tools:

• Formatting: black, isort, autoflake
• Static Analysis: mypy, pylint, pyright, pyre
• Security Scanning: bandit, pip-audit
• Complexity Analysis: radon, wily
• Dependency Checking: fawltydeps, pip-licenses

Summary

MCP Context Forge is a fully functional, production-ready Model Context Protocol gateway solution, particularly suitable for enterprise-grade LLM application tool integration and management needs. It not only implements the complete functionality of the MCP protocol but also provides rich extension features such as federation discovery, protocol conversion, and virtualization services, making it an ideal infrastructure component for building complex AI application ecosystems.