{"id":50101829,"url":"https://ibm.github.io/mcp-context-forge/","last_synced_at":"2026-06-08T23:01:14.860Z","repository":{"id":292121491,"uuid":"979886407","full_name":"IBM/mcp-context-forge","owner":"IBM","description":"An AI Gateway, registry, and proxy that sits in front of any MCP, A2A, or REST/gRPC APIs, exposing a unified endpoint with centralized discovery, guardrails and management. Optimizes Agent \u0026 Tool calling, and supports plugins.","archived":false,"fork":false,"pushed_at":"2026-06-03T02:13:05.000Z","size":347204,"stargazers_count":3808,"open_issues_count":1111,"forks_count":682,"subscribers_count":32,"default_branch":"main","last_synced_at":"2026-06-03T04:11:44.354Z","etag":null,"topics":["agents","ai","api-gateway","asyncio","authentication-middleware","devops","docker","fastapi","federation","gateway","generative-ai","jwt","kubernetes","llm-agents","mcp","model-context-protocol","observability","prompt-engineering","python","tools"],"latest_commit_sha":null,"homepage":"https://ibm.github.io/mcp-context-forge/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IBM.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":"DCO.txt","cla":null}},"created_at":"2025-05-08T08:16:59.000Z","updated_at":"2026-06-03T04:09:26.000Z","dependencies_parsed_at":"2025-05-08T09:32:02.813Z","dependency_job_id":"590e748f-65f6-4f72-b2fb-2a789c270120","html_url":"https://github.com/IBM/mcp-context-forge","commit_stats":null,"previous_names":["ibm/mcp-context-forge"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/IBM/mcp-context-forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fmcp-context-forge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fmcp-context-forge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fmcp-context-forge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fmcp-context-forge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IBM","download_url":"https://codeload.github.com/IBM/mcp-context-forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fmcp-context-forge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34083848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","api-gateway","asyncio","authentication-middleware","devops","docker","fastapi","federation","gateway","generative-ai","jwt","kubernetes","llm-agents","mcp","model-context-protocol","observability","prompt-engineering","python","tools"],"created_at":"2026-05-23T08:00:31.591Z","updated_at":"2026-06-08T23:01:14.852Z","avatar_url":"https://github.com/IBM.png","language":"Python","funding_links":[],"categories":["🔌 MCP Security"],"sub_categories":["Gateways and Proxies"],"readme":"# ContextForge\n\n\u003e An open source registry and proxy that federates MCP, A2A, and REST/gRPC APIs with centralized governance, discovery, and observability. Optimizes Agent \u0026 Tool calling, and supports plugins.\n\n![ContextForge Banner](docs/docs/images/contextforge-logo_horizontal_black.png)\n\n\u003c!-- === CI / Security / Build Badges === --\u003e\n[![Build Python Package](https://github.com/IBM/mcp-context-forge/actions/workflows/python-package.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/python-package.yml)\u0026nbsp;\n[![Dependency Review](https://github.com/IBM/mcp-context-forge/actions/workflows/dependency-review.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/dependency-review.yml)\u0026nbsp;\n[![Tests \u0026 Coverage](https://github.com/IBM/mcp-context-forge/actions/workflows/pytest.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/pytest.yml)\u0026nbsp;\n[![Lint \u0026 Static Analysis](https://github.com/IBM/mcp-context-forge/actions/workflows/lint.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/lint.yml)\n\n\u003c!-- === Package / Container === --\u003e\n[![Async](https://img.shields.io/badge/async-await-green.svg)](https://docs.python.org/3/library/asyncio.html)\n[![License](https://img.shields.io/github/license/ibm/mcp-context-forge)](LICENSE)\u0026nbsp;\n[![PyPI](https://img.shields.io/pypi/v/mcp-contextforge-gateway)](https://pypi.org/project/mcp-contextforge-gateway/)\u0026nbsp;\n[![Docker Image](https://img.shields.io/badge/docker-ghcr.io%2Fibm%2Fmcp--context--forge-blue)](https://github.com/ibm/mcp-context-forge/pkgs/container/mcp-context-forge)\u0026nbsp;\n\n\n**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:\n\n- **Tools Gateway** — MCP, REST, gRPC-to-MCP translation, and TOON compression\n- **Agent Gateway** — A2A protocol, OpenAI-compatible and Anthropic agent routing\n- **API Gateway** — Rate limiting, auth, retries, and reverse proxy for REST services\n- **Plugin Extensibility** — 40+ plugins for additional transports, protocols, and integrations\n- **Observability** — OpenTelemetry tracing with Phoenix, Jaeger, Zipkin, and other OTLP backends\n\nIt 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.\n\n![ContextForge](https://ibm.github.io/mcp-context-forge/images/mcpgateway.gif)\n---\n\n\u003c!-- vscode-markdown-toc --\u003e\n## Table of Contents\n\n- [Overview \u0026 Goals](#overview--goals)\n- [Quick Start - PyPI](#quick-start---pypi)\n- [Quick Start - Containers](#quick-start---containers)\n- [VS Code Dev Container](#quick-start-vs-code-dev-container)\n- [Installation](#installation)\n- [Upgrading](#upgrading)\n- [Configuration](#configuration)\n- [Running](#running)\n- [Cloud Deployment](#cloud-deployment)\n- [API Reference](#api-reference)\n- [Testing](#testing)\n- [Project Structure](#project-structure)\n- [Development](#development)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n\n---\n\n### 📌 Quick Links\n\n| Resource | Description |\n|----------|-------------|\n| **[5-Minute Setup](https://github.com/IBM/mcp-context-forge/issues/2503)** | Get started fast — uvx, Docker, Compose, or local dev |\n| **[Getting Help](https://github.com/IBM/mcp-context-forge/issues/2504)** | Support options, FAQ, community channels |\n| **[Issue Guide](https://github.com/IBM/mcp-context-forge/issues/2502)** | How to file bugs, request features, contribute |\n| **[Full Documentation](https://ibm.github.io/mcp-context-forge/)** | Complete guides, tutorials, API reference |\n\n---\n\n## Overview \u0026 Goals\n\n**ContextForge** is an open source registry and proxy that federates any [Model Context Protocol](https://modelcontextprotocol.io) (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](https://ibm.github.io/mcp-context-forge/architecture/roadmap/) for more details.\n\nIt currently supports:\n\n* Federation across multiple MCP and REST services\n* **A2A (Agent-to-Agent) integration** for external AI agents (OpenAI, Anthropic, custom)\n* **gRPC-to-MCP translation** via automatic reflection-based service discovery\n* Virtualization of legacy APIs as MCP-compliant tools and servers\n* Transport over HTTP, JSON-RPC, WebSocket, SSE (with configurable keepalive), stdio and streamable-HTTP\n* An Admin UI for real-time management, configuration, and log monitoring (with airgapped deployment support)\n* Built-in auth, retries, and rate-limiting with user-scoped OAuth tokens and unconditional X-Upstream-Authorization header support\n* **OpenTelemetry observability** with Phoenix, Jaeger, Zipkin, and other OTLP backends\n* Scalable deployments via Docker or PyPI, Redis-backed caching, and multi-cluster federation\n\n![ContextForge Architecture](https://ibm.github.io/mcp-context-forge/images/mcpgateway.svg)\n\nFor a list of upcoming features, check out the [ContextForge Roadmap](https://ibm.github.io/mcp-context-forge/architecture/roadmap/)\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔌 Gateway Layer with Protocol Flexibility\u003c/strong\u003e\u003c/summary\u003e\n\n* Federates any MCP server or REST API\n* Lets you choose your MCP protocol version (e.g., `2025-11-25`)\n* Exposes a single, unified interface for diverse backends\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🧩 Virtualization of REST/gRPC Services\u003c/strong\u003e\u003c/summary\u003e\n\n* Wraps non-MCP services as virtual MCP servers\n* Registers tools, prompts, and resources with minimal configuration\n* **gRPC-to-MCP translation** via server reflection protocol\n* Automatic service discovery and method introspection\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔁 REST-to-MCP Tool Adapter\u003c/strong\u003e\u003c/summary\u003e\n\n* Adapts REST APIs into tools with:\n\n  * Automatic JSON Schema extraction\n  * Support for headers, tokens, and custom auth\n  * Retry, timeout, and rate-limit policies\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🧠 Unified Registries\u003c/strong\u003e\u003c/summary\u003e\n\n* **Prompts**: Jinja2 templates, multimodal support, rollback/versioning\n* **Resources**: URI-based access, MIME detection, caching, SSE updates\n* **Tools**: Native or adapted, with input validation and concurrency controls\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📈 Admin UI, Observability \u0026 Dev Experience\u003c/strong\u003e\u003c/summary\u003e\n\n* Admin UI built with HTMX 2.0.3 (bundled) + Alpine.js\n* Real-time log viewer with filtering, search, and export capabilities\n* Auth: Basic, JWT, or custom schemes\n* Structured logs, health endpoints, metrics\n* 7,000+ tests, Makefile targets, live reload, pre-commit hooks\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔍 OpenTelemetry Observability\u003c/strong\u003e\u003c/summary\u003e\n\n* **Vendor-agnostic tracing** with OpenTelemetry (OTLP) protocol support\n* **Multiple backend support**: Phoenix (LLM-focused), Jaeger, Zipkin, Tempo, DataDog, New Relic\n* **Distributed tracing** across federated gateways and services\n* **Automatic instrumentation** of tools, prompts, resources, and gateway operations\n* **LLM-specific metrics**: Token usage, costs, model performance\n* **Zero-overhead when disabled** with graceful degradation\n\nSee **[Observability Documentation](https://ibm.github.io/mcp-context-forge/manage/observability/)** for setup guides with Phoenix, Jaeger, and other backends.\n\n\u003c/details\u003e\n\n---\n\n## Quick Start - PyPI\n\nContextForge is published on [PyPI](https://pypi.org/project/mcp-contextforge-gateway/) as `mcp-contextforge-gateway`.\n\n---\n\n**TLDR;**:\n(single command using [uv](https://docs.astral.sh/uv/))\n\n```bash\n# Quick start with environment variables\nBASIC_AUTH_PASSWORD=pass \\\nMCPGATEWAY_UI_ENABLED=true \\\nMCPGATEWAY_ADMIN_API_ENABLED=true \\\nPLATFORM_ADMIN_EMAIL=admin@example.com \\\nPLATFORM_ADMIN_PASSWORD=changeme \\\nPLATFORM_ADMIN_FULL_NAME=\"Platform Administrator\" \\\nuvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444\n\n# Or better: use the provided .env.example\ncp .env.example .env\n# Edit .env to customize your settings\nuvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📋 Prerequisites\u003c/strong\u003e\u003c/summary\u003e\n\n* **Python ≥ 3.11**\n* **curl + jq** - only for the last smoke-test step\n\n\u003c/details\u003e\n\n### 1 - Install \u0026 run (copy-paste friendly)\n\n```bash\n# 1️⃣  Isolated env + install from pypi\nmkdir mcpgateway \u0026\u0026 cd mcpgateway\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install --upgrade pip\npip install mcp-contextforge-gateway\n\n# 2️⃣  Copy and customize the configuration\n# Download the example environment file\ncurl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example\ncp .env.example .env\n# Edit .env to customize your settings (especially passwords!)\n\n# Or set environment variables directly:\nexport MCPGATEWAY_UI_ENABLED=true\nexport MCPGATEWAY_ADMIN_API_ENABLED=true\nexport PLATFORM_ADMIN_EMAIL=admin@example.com\nexport PLATFORM_ADMIN_PASSWORD=changeme\nexport PLATFORM_ADMIN_FULL_NAME=\"Platform Administrator\"\n\nBASIC_AUTH_PASSWORD=pass JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \\\n  mcpgateway --host 0.0.0.0 --port 4444 \u0026   # admin/pass\n\n# 3️⃣  Generate a bearer token \u0026 smoke-test the API\nexport MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \\\n    --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)\n\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     http://127.0.0.1:4444/version | jq\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWindows (PowerShell) quick-start\u003c/strong\u003e\u003c/summary\u003e\n\n```powershell\n# 1️⃣  Isolated env + install from PyPI\nmkdir mcpgateway ; cd mcpgateway\npython3 -m venv .venv ; .\\.venv\\Scripts\\Activate.ps1\npip install --upgrade pip\npip install mcp-contextforge-gateway\n\n# 2️⃣  Copy and customize the configuration\n# Download the example environment file\nInvoke-WebRequest -Uri \"https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example\" -OutFile \".env.example\"\nCopy-Item .env.example .env\n# Edit .env to customize your settings\n\n# Or set environment variables (session-only)\n$Env:MCPGATEWAY_UI_ENABLED        = \"true\"\n$Env:MCPGATEWAY_ADMIN_API_ENABLED = \"true\"\n# Note: Basic auth for API is disabled by default (API_ALLOW_BASIC_AUTH=false)\n$Env:JWT_SECRET_KEY               = \"my-test-key-but-now-longer-than-32-bytes\"\n$Env:PLATFORM_ADMIN_EMAIL         = \"admin@example.com\"\n$Env:PLATFORM_ADMIN_PASSWORD      = \"changeme\"\n$Env:PLATFORM_ADMIN_FULL_NAME     = \"Platform Administrator\"\n\n# 3️⃣  Launch the gateway\nmcpgateway.exe --host 0.0.0.0 --port 4444\n\n#   Optional: background it\n# Start-Process -FilePath \"mcpgateway.exe\" -ArgumentList \"--host 0.0.0.0 --port 4444\"\n\n# 4️⃣  Bearer token and smoke-test\n$Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token `\n    --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes\n\ncurl -s -H \"Authorization: Bearer $Env:MCPGATEWAY_BEARER_TOKEN\" `\n     http://127.0.0.1:4444/version | jq\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e⚡ Alternative: uv (faster)\u003c/strong\u003e\u003c/summary\u003e\n\n```powershell\n# 1️⃣  Isolated env + install from PyPI using uv\nmkdir mcpgateway ; cd mcpgateway\nuv venv\n.\\.venv\\Scripts\\activate\nuv pip install mcp-contextforge-gateway\n\n# Continue with steps 2️⃣-4️⃣ above...\n```\n\n\u003c/details\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMore configuration\u003c/strong\u003e\u003c/summary\u003e\n\nCopy [.env.example](https://github.com/IBM/mcp-context-forge/blob/main/.env.example) to `.env` and tweak any of the settings (or use them as env variables).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🚀 End-to-end demo (register a local MCP server)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# 1️⃣  Spin up the sample GO MCP time server using mcpgateway.translate \u0026 docker (replace docker with podman if needed)\npython3 -m mcpgateway.translate \\\n     --stdio \"docker run --rm -i ghcr.io/ibm/fast-time-server:latest -transport=stdio\" \\\n     --expose-sse \\\n     --port 8003\n\n# Or using the official mcp-server-git using uvx:\npip install uv # to install uvx, if not already installed\npython3 -m mcpgateway.translate --stdio \"uvx mcp-server-git\" --expose-sse --port 9000\n\n# Alternative: running the local binary\n# cd mcp-servers/go/fast-time-server; make build\n# python3 -m mcpgateway.translate --stdio \"./dist/fast-time-server -transport=stdio\" --expose-sse --port 8002\n\n# NEW: Expose via multiple protocols simultaneously!\npython3 -m mcpgateway.translate \\\n     --stdio \"uvx mcp-server-git\" \\\n     --expose-sse \\\n     --expose-streamable-http \\\n     --port 9000\n# Now accessible via both /sse (SSE) and /mcp (streamable HTTP) endpoints\n\n# 2️⃣  Register it with the gateway\ncurl -s -X POST -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"name\":\"fast_time\",\"url\":\"http://localhost:8003/sse\"}' \\\n     http://localhost:4444/gateways\n\n# 3️⃣  Verify tool catalog\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" http://localhost:4444/tools | jq\n\n# 4️⃣  Create a *virtual server* bundling those tools. Use the ID of tools from the tool catalog (Step #3) and pass them in the associatedTools list.\ncurl -s -X POST -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"server\":{\"name\":\"time_server\",\"description\":\"Fast time tools\",\"associated_tools\":[\u003cID_OF_TOOLS\u003e]}}' \\\n     http://localhost:4444/servers | jq\n\n# Example curl\ncurl -s -X POST -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"server\":{\"name\":\"time_server\",\"description\":\"Fast time tools\",\"associated_tools\":[\"6018ca46d32a4ac6b4c054c13a1726a2\"]}}' \\\n     http://localhost:4444/servers | jq\n\n# 5️⃣  List servers (should now include the UUID of the newly created virtual server)\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" http://localhost:4444/servers | jq\n\n# 6️⃣  Client HTTP endpoint. Inspect it interactively with the MCP Inspector CLI (or use any MCP client)\nnpx -y @modelcontextprotocol/inspector\n# Transport Type: Streamable HTTP, URL: http://localhost:4444/servers/UUID_OF_SERVER_1/mcp,  Header Name: \"Authorization\", Bearer Token\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🖧 Using the stdio wrapper (mcpgateway-wrapper)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\nexport MCP_AUTH=\"Bearer ${MCPGATEWAY_BEARER_TOKEN}\"\nexport MCP_SERVER_URL=http://localhost:4444/servers/UUID_OF_SERVER_1/mcp\npython3 -m mcpgateway.wrapper  # Ctrl-C to exit\n```\n\nYou can also run it with `uv` or inside Docker/Podman - see the *Containers* section above.\n\nIn MCP Inspector, define `MCP_AUTH` and `MCP_SERVER_URL` env variables, and select `python3` as the Command, and `-m mcpgateway.wrapper` as Arguments.\n\n```bash\necho $PWD/.venv/bin/python3 # Using the Python3 full path ensures you have a working venv\nexport MCP_SERVER_URL='http://localhost:4444/servers/UUID_OF_SERVER_1/mcp'\nexport MCP_AUTH=\"Bearer ${MCPGATEWAY_BEARER_TOKEN}\"\nnpx -y @modelcontextprotocol/inspector\n```\n\nor\n\nPass the url and auth as arguments (no need to set environment variables)\n```bash\nnpx -y @modelcontextprotocol/inspector\ncommand as `python`\nArguments as `-m mcpgateway.wrapper --url \"http://localhost:4444/servers/UUID_OF_SERVER_1/mcp\" --auth \"Bearer \u003cyour token\u003e\"`\n```\n\n\nWhen using a MCP Client such as Claude with stdio:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcpgateway-wrapper\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcpgateway.wrapper\"],\n      \"env\": {\n        \"MCP_AUTH\": \"Bearer your-token-here\",\n        \"MCP_SERVER_URL\": \"http://localhost:4444/servers/UUID_OF_SERVER_1\",\n        \"MCP_TOOL_CALL_TIMEOUT\": \"120\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n---\n\n## Quick Start - Containers\n\nUse the official OCI image from GHCR with **Docker** *or* **Podman**.\nPlease note: Currently, arm64 is not supported on production. If you are e.g. running on MacOS with Apple Silicon chips (M1, M2, etc), you can run the containers using Rosetta or install via PyPi instead.\n\n### 🚀 Quick Start - Docker Compose\n\nGet a full stack running with PostgreSQL and Redis in under 30 seconds:\n\n```bash\n# Clone and start the stack\ngit clone https://github.com/IBM/mcp-context-forge.git\ncd mcp-context-forge\n\n# Start with PostgreSQL (recommended for production)\ndocker compose up -d\n\n# Check status\ndocker compose ps\n\n# View logs\ndocker compose logs -f gateway\n\n# Access Admin UI: http://localhost:8080/admin (login with PLATFORM_ADMIN_EMAIL/PASSWORD)\n# Generate API token\ndocker compose exec gateway python3 -m mcpgateway.utils.create_jwt_token \\\n  --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes\n```\n\n**What you get:**\n- 🗄️ **PostgreSQL** - Production-ready database with 55+ tables\n- 🚀 **ContextForge** - Full-featured gateway with Admin UI\n- 📊 **Redis** - High-performance caching and session storage\n- 🔧 **Admin Tools** - pgAdmin, Redis Insight for database management\n- 🌐 **Nginx Proxy** - Caching reverse proxy on port 8080\n\n**Enable HTTPS (optional):**\n```bash\n# Start with TLS enabled (auto-generates self-signed certs)\nmake compose-tls\n\n# Access via HTTPS: https://localhost:8443/admin\n\n# Or bring your own certificates:\n# Unencrypted key:\nmkdir -p certs\ncp your-cert.pem certs/cert.pem \u0026\u0026 cp your-key.pem certs/key.pem\nmake compose-tls\n\n# Passphrase-protected key:\nmkdir -p certs\ncp your-cert.pem certs/cert.pem \u0026\u0026 cp your-encrypted-key.pem certs/key-encrypted.pem\necho \"KEY_FILE_PASSWORD=your-passphrase\" \u003e\u003e .env\nmake compose-tls\n```\n\n### ☸️ Quick Start - Helm (Kubernetes)\n\nDeploy to Kubernetes with enterprise-grade features:\n\n```bash\n# Add Helm repository (when available)\n# helm repo add mcp-context-forge https://ibm.github.io/mcp-context-forge\n# helm repo update\n\n# For now, use local chart\ngit clone https://github.com/IBM/mcp-context-forge.git\ncd mcp-context-forge/charts/mcp-stack\n\n# Install with PostgreSQL (default)\nhelm install mcp-gateway . \\\n  --set mcpContextForge.secret.PLATFORM_ADMIN_EMAIL=admin@yourcompany.com \\\n  --set mcpContextForge.secret.PLATFORM_ADMIN_PASSWORD=changeme \\\n  --set mcpContextForge.secret.JWT_SECRET_KEY=your-secret-key\n\n# Check deployment status\nkubectl get pods -l app.kubernetes.io/name=mcp-context-forge\n\n# Port forward to access Admin UI\nkubectl port-forward svc/mcp-gateway-mcp-context-forge 4444:80\n# Access: http://localhost:4444/admin\n\n# Generate API token\nkubectl exec deployment/mcp-gateway-mcp-context-forge -- \\\n  python3 -m mcpgateway.utils.create_jwt_token \\\n  --username admin@yourcompany.com --exp 10080 --secret your-secret-key\n```\n\n\u003e SSRF note: Helm defaults to strict SSRF settings (`SSRF_ALLOW_PRIVATE_NETWORKS=false`).\n\u003e If you register in-cluster tool URLs (for example fast-time or fast-test services),\n\u003e allow only your cluster CIDRs via `mcpContextForge.config.SSRF_ALLOWED_NETWORKS` or,\n\u003e for local-only benchmark setups, temporarily set `SSRF_ALLOW_PRIVATE_NETWORKS=true`.\n\u003e See `docs/docs/manage/configuration.md#ssrf-protection` and `docs/docs/deployment/helm.md`.\n\n**Enterprise Features:**\n- 🔄 **Auto-scaling** - HPA with CPU/memory targets\n- 🗄️ **Database Choice** - PostgreSQL (prod), SQLite (dev)\n- 📊 **Observability** - Prometheus metrics, OpenTelemetry tracing\n- 🔒 **Security** - RBAC, network policies, secret management\n- 🚀 **High Availability** - Multi-replica deployments with Redis clustering\n- 📈 **Monitoring** - Built-in Grafana dashboards and alerting\n\n---\n\n### 🐳 Docker (Single Container)\n\n```bash\ndocker run -d --name mcpgateway \\\n  -p 4444:4444 \\\n  -e MCPGATEWAY_UI_ENABLED=true \\\n  -e MCPGATEWAY_ADMIN_API_ENABLED=true \\\n  -e HOST=0.0.0.0 \\\n  -e JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \\\n  -e AUTH_REQUIRED=true \\\n  -e PLATFORM_ADMIN_EMAIL=admin@example.com \\\n  -e PLATFORM_ADMIN_PASSWORD=changeme \\\n  -e PLATFORM_ADMIN_FULL_NAME=\"Platform Administrator\" \\\n  -e DATABASE_URL=sqlite:///./mcp.db \\\n  -e SECURE_COOKIES=false \\\n  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3\n\n# Tail logs and generate API key\ndocker logs -f mcpgateway\ndocker run --rm -it ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3 \\\n  python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes\n```\n\nBrowse to **[http://localhost:4444/admin](http://localhost:4444/admin)** and login with `PLATFORM_ADMIN_EMAIL` / `PLATFORM_ADMIN_PASSWORD`.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAdvanced: Persistent storage, host networking, airgapped\u003c/strong\u003e\u003c/summary\u003e\n\n**Persist SQLite database:**\n```bash\nmkdir -p $(pwd)/data \u0026\u0026 touch $(pwd)/data/mcp.db \u0026\u0026 chmod 777 $(pwd)/data\ndocker run -d --name mcpgateway --restart unless-stopped \\\n  -p 4444:4444 -v $(pwd)/data:/data \\\n  -e DATABASE_URL=sqlite:////data/mcp.db \\\n  -e MCPGATEWAY_UI_ENABLED=true -e MCPGATEWAY_ADMIN_API_ENABLED=true \\\n  -e HOST=0.0.0.0 -e JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \\\n  -e PLATFORM_ADMIN_EMAIL=admin@example.com -e PLATFORM_ADMIN_PASSWORD=changeme \\\n  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3\n```\n\n**Host networking** (access local MCP servers):\n```bash\ndocker run -d --name mcpgateway --network=host \\\n  -v $(pwd)/data:/data -e DATABASE_URL=sqlite:////data/mcp.db \\\n  -e MCPGATEWAY_UI_ENABLED=true -e HOST=0.0.0.0 -e PORT=4444 \\\n  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3\n```\n\n**Airgapped deployment** (no internet):\n```bash\ndocker build -f Containerfile.lite -t mcpgateway:airgapped .\ndocker run -d --name mcpgateway -p 4444:4444 \\\n  -e MCPGATEWAY_UI_AIRGAPPED=true -e MCPGATEWAY_UI_ENABLED=true \\\n  -e HOST=0.0.0.0 -e JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \\\n  mcpgateway:airgapped\n```\n\n\u003c/details\u003e\n\n---\n\n### 🦭 Podman (rootless-friendly)\n\n```bash\npodman run -d --name mcpgateway \\\n  -p 4444:4444 -e HOST=0.0.0.0 -e DATABASE_URL=sqlite:///./mcp.db \\\n  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAdvanced: Persistent storage, host networking\u003c/strong\u003e\u003c/summary\u003e\n\n**Persist SQLite:**\n```bash\nmkdir -p $(pwd)/data \u0026\u0026 chmod 777 $(pwd)/data\npodman run -d --name mcpgateway --restart=on-failure \\\n  -p 4444:4444 -v $(pwd)/data:/data \\\n  -e DATABASE_URL=sqlite:////data/mcp.db \\\n  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3\n```\n\n**Host networking:**\n```bash\npodman run -d --name mcpgateway --network=host \\\n  -v $(pwd)/data:/data -e DATABASE_URL=sqlite:////data/mcp.db \\\n  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3\n```\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e✏️ Docker/Podman tips\u003c/strong\u003e\u003c/summary\u003e\n\n* **.env files** - Put all the `-e FOO=` lines into a file and replace them with `--env-file .env`. See the provided [.env.example](https://github.com/IBM/mcp-context-forge/blob/main/.env.example) for reference.\n* **Pinned tags** - Use an explicit version (e.g. `1.0.0-RC-3`) instead of `latest` for reproducible builds.\n* **JWT tokens** - Generate one in the running container:\n\n  ```bash\n  docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes\n  ```\n* **Upgrades** - Stop, remove, and rerun with the same `-v $(pwd)/data:/data` mount; your DB and config stay intact.\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🚑 Smoke-test the running container\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     http://localhost:4444/health | jq\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     http://localhost:4444/tools | jq\ncurl -s -H \"Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN\" \\\n     http://localhost:4444/version | jq\n```\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🖧 Running ContextForge stdio wrapper\u003c/strong\u003e\u003c/summary\u003e\n\nThe `mcpgateway.wrapper` lets you connect to the gateway over **stdio** while keeping JWT authentication. You should run this from the MCP Client. The example below is just for testing.\n\n```bash\n# Set environment variables\nexport MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)\nexport MCP_AUTH=\"Bearer ${MCPGATEWAY_BEARER_TOKEN}\"\nexport MCP_SERVER_URL='http://localhost:4444/servers/UUID_OF_SERVER_1/mcp'\nexport MCP_TOOL_CALL_TIMEOUT=120\nexport MCP_WRAPPER_LOG_LEVEL=DEBUG  # or OFF to disable logging\n\ndocker run --rm -i \\\n  -e MCP_AUTH=$MCP_AUTH \\\n  -e MCP_SERVER_URL=http://host.docker.internal:4444/servers/UUID_OF_SERVER_1/mcp \\\n  -e MCP_TOOL_CALL_TIMEOUT=120 \\\n  -e MCP_WRAPPER_LOG_LEVEL=DEBUG \\\n  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3 \\\n  python3 -m mcpgateway.wrapper\n```\n\n\u003c/details\u003e\n\n---\n\n\n## Quick Start: VS Code Dev Container\n\nClone the repo and open in VS Code—it will detect `.devcontainer` and prompt to **\"Reopen in Container\"**. The container includes Python 3.11, Docker CLI, and all project dependencies.\n\nFor detailed setup, workflows, and GitHub Codespaces instructions, see **[Developer Onboarding](https://ibm.github.io/mcp-context-forge/development/developer-onboarding/)**.\n\n---\n\n## Installation\n\n```bash\nmake venv install-dev      # create .venv + install deps + build Admin UI\nmake serve                 # gunicorn on :4444\n```\n\nRust workspace note:\n- Workspace-owned Rust crates live under `crates/` and are picked up by the root `Cargo.toml` via `crates/*`.\n- Run `cargo build`, `cargo test`, and `cargo check` from the repo root to cover the shared workspace.\n- `mcp-servers/rust/` stays outside the shared workspace on purpose and is managed separately.\n- `make venv install-dev` creates the root `.venv`, which is also reused by the workspace's PyO3/maturin builds.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAlternative: UV or pip\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# UV (faster)\nuv venv \u0026\u0026 source .venv/bin/activate\nuv pip install -e '.[dev]'\n\n# pip\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e \".[dev]\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePostgreSQL adapter setup\u003c/strong\u003e\u003c/summary\u003e\n\nInstall the `psycopg` driver for PostgreSQL:\n\n```bash\n# Install system dependencies first\n# Debian/Ubuntu: sudo apt-get install libpq-dev\n# macOS: brew install libpq\n\nuv pip install 'psycopg[binary]'   # dev (pre-built wheels)\n# or: uv pip install 'psycopg[c]'  # production (requires compiler)\n```\n\nConnection URL format:\n```bash\nDATABASE_URL=postgresql+psycopg://user:password@localhost:5432/mcp\n```\n\nQuick Postgres container:\n```bash\ndocker run --name mcp-postgres \\\n  -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=mysecretpassword \\\n  -e POSTGRES_DB=mcp -p 5432:5432 -d postgres\n```\n\n\u003c/details\u003e\n\n---\n\n## Upgrading\n\nFor upgrade instructions, migration guides, and rollback procedures, see:\n\n- **[Upgrade Guide](https://ibm.github.io/mcp-context-forge/manage/upgrade/)** — General upgrade procedures\n- **[CHANGELOG.md](./CHANGELOG.md)** — Version history and breaking changes\n\n---\n\n## Configuration\n\n\u003e ⚠️ If any required `.env` variable is missing or invalid, the gateway will fail fast at startup with a validation error via Pydantic.\n\nCopy the provided [.env.example](https://github.com/IBM/mcp-context-forge/blob/main/.env.example) to `.env` and update the security-sensitive values below.\n\n### 🔐 Required: Change Before Use\n\nThese variables have insecure defaults and **must be changed** before production deployment:\n\n| Variable | Description | Default | Action Required |\n|----------|-------------|---------|-----------------|\n| `JWT_SECRET_KEY` | Secret key for signing JWT tokens (32+ chars) | `my-test-key-but-now-longer-than-32-bytes` | Generate with `openssl rand -hex 32` |\n| `AUTH_ENCRYPTION_SECRET` | Passphrase for encrypting stored credentials | `my-test-salt` | Generate with `openssl rand -hex 32` |\n| `BASIC_AUTH_USER` | Username for HTTP Basic auth | `admin` | Change for production |\n| `BASIC_AUTH_PASSWORD` | Password for HTTP Basic auth | `changeme` | Set a strong password |\n| `PLATFORM_ADMIN_EMAIL` | Email for bootstrap admin user | `admin@example.com` | Use real admin email |\n| `PLATFORM_ADMIN_PASSWORD` | Password for bootstrap admin user | `changeme` | Set a strong password |\n| `PLATFORM_ADMIN_FULL_NAME` | Display name for bootstrap admin | `Admin User` | Set admin name |\n\n### 🔒 Security Defaults (Secure by Default)\n\nThese settings are enabled by default for security—only disable for backward compatibility:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `REQUIRE_JTI` | Require JTI claim in tokens for revocation support | `true` |\n| `REQUIRE_TOKEN_EXPIRATION` | Require exp claim in tokens | `true` |\n| `PUBLIC_REGISTRATION_ENABLED` | Allow public user self-registration | `false` |\n### 🛡️ Content Security\n\nContent size limits prevent DoS attacks and ensure system stability:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `CONTENT_MAX_RESOURCE_SIZE` | Maximum resource content size (bytes) | `102400` (100KB) |\n| `CONTENT_MAX_PROMPT_SIZE` | Maximum prompt template size (bytes) | `10240` (10KB) |\n\n**Note:** Size limits apply only to new create/update operations. Existing content is not retroactively validated.\n\n### 🌐 UAID Cross-Gateway Routing Security\n\n#### UAID Security Configuration\n\n**Production Requirements:**\n\nCross-gateway UAID routing requires explicit security configuration:\n\n1. **Configure Domain Allowlist:**\n   ```bash\n   UAID_ALLOWED_DOMAINS=[\"gateway1.example.com\", \"gateway2.example.com\"]\n   ```\n\n2. **Ensure JWT Trust:**\n   - Both gateways must trust the same JWT issuer\n   - Option A: Shared secret (same `JWT_SECRET_KEY` on all gateways)\n   - Option B: Federated SSO (Google, GitHub, Entra ID)\n\n3. **Enable Authentication:**\n   ```bash\n   AUTH_REQUIRED=true\n   UAID_FORWARD_AUTH=true\n   ```\n\n**Authentication Flow:**\n\nCross-gateway calls forward the user's bearer token via the `Authorization` header.\nRemote gateways validate tokens through existing auth middleware, preserving RBAC context.\n\n**Security Features:**\n\n- ✅ Fail-closed default: Empty allowlist blocks all cross-gateway routing\n- ✅ Bearer token forwarding: User authentication preserved across hops\n- ✅ Audit trail: Source gateway and user tracked in headers\n- ✅ Clear error messages: Misconfigurations caught at startup and runtime\n\n**Troubleshooting:**\n\n- **\"UAID_ALLOWED_DOMAINS not configured\" error:** Add trusted domains to allowlist in .env\n- **401/403 from remote gateway:** Verify both gateways trust same JWT issuer\n- **\"proceeding without authentication token\" warning:** Check auth middleware extracts token to `request.state.bearer_token`\n\nFor detailed security architecture, see `docs/security/uaid-cross-gateway-auth.md`.\n\n### ⚙️ Project Defaults (Dev Setup)\n\nThese values differ from code defaults to provide a working local/dev setup:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `HOST` | Bind address | `0.0.0.0` |\n| `MCPGATEWAY_UI_ENABLED` | Enable Admin UI dashboard | `true` |\n| `MCPGATEWAY_ADMIN_API_ENABLED` | Enable Admin API endpoints | `true` |\n| `DATABASE_URL` | SQLAlchemy connection URL | `sqlite:///./mcp.db` |\n| `SECURE_COOKIES` | Set `false` for HTTP (non-HTTPS) dev | `false` |\n\n### 📚 Full Configuration Reference\n\nFor the complete list of 300+ environment variables organized by category (authentication, caching, SSO, observability, etc.), see the **[Configuration Reference](https://ibm.github.io/mcp-context-forge/manage/configuration/)**.\n\n---\n\n## Running\n\n### Quick Reference\n\n| Command | Server | Port | Database | Use Case |\n|---------|--------|------|----------|----------|\n| `make dev` | Uvicorn | **8000** | SQLite | Development (single instance, auto-reload) |\n| `make serve` | Gunicorn | **4444** | SQLite | Production single-node (multi-worker) |\n| `make serve-ssl` | Gunicorn | **4444** | SQLite | Production single-node with HTTPS |\n| `make compose-up` | Docker Compose + Nginx | **8080** | PostgreSQL + Redis | Full stack (3 replicas, load-balanced) |\n| `make compose-sso` | Docker Compose + Keycloak | **8080 / 8180** | PostgreSQL + Redis | Local SSO testing (Keycloak profile) |\n| `make testing-up` | Docker Compose + Nginx | **8080** | PostgreSQL + Redis | Testing environment |\n\n### Development Server (Uvicorn)\n\n```bash\nmake dev                 # Uvicorn on :8000 with auto-reload and SQLite\n# or\n./run.sh --reload --log debug --workers 2\n```\n\n\u003e `run.sh` is a wrapper around `uvicorn` that loads `.env`, supports reload, and passes arguments to the server.\n\nKey flags:\n\n| Flag             | Purpose          | Example            |\n| ---------------- | ---------------- | ------------------ |\n| `-e, --env FILE` | load env-file    | `--env prod.env`   |\n| `-H, --host`     | bind address     | `--host 127.0.0.1` |\n| `-p, --port`     | listen port      | `--port 8080`      |\n| `-w, --workers`  | gunicorn workers | `--workers 4`      |\n| `-r, --reload`   | auto-reload      | `--reload`         |\n\n### Production Server (Gunicorn)\n\n```bash\nmake serve               # Gunicorn on :4444 with multiple workers\nmake serve-ssl           # Gunicorn behind HTTPS on :4444 (uses ./certs)\n```\n\n### Docker Compose (Full Stack)\n\n```bash\nmake compose-up          # Start full stack: PostgreSQL, Redis, 3 gateway replicas, Nginx on :8080\nmake compose-sso         # Start SSO stack with Keycloak on :8180\nmake sso-test-login      # Run SSO smoke checks (providers + login URL + test users)\nmake compose-logs        # Tail logs from all services\nmake compose-down        # Stop the stack\n```\n\n### Manual (Uvicorn)\n\n```bash\nuvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444 --workers 4\n```\n\n---\n\n## Cloud Deployment\n\nContextForge can be deployed to any major cloud platform:\n\n| Platform | Guide |\n|----------|-------|\n| **AWS** | [ECS/EKS Deployment](https://ibm.github.io/mcp-context-forge/deployment/aws/) |\n| **Azure** | [AKS Deployment](https://ibm.github.io/mcp-context-forge/deployment/azure/) |\n| **Google Cloud** | [Cloud Run](https://ibm.github.io/mcp-context-forge/deployment/google-cloud-run/) |\n| **IBM Cloud** | [Code Engine](https://ibm.github.io/mcp-context-forge/deployment/ibm-code-engine/) |\n| **Kubernetes** | [Helm Charts](https://ibm.github.io/mcp-context-forge/deployment/minikube/) |\n| **OpenShift** | [OpenShift Deployment](https://ibm.github.io/mcp-context-forge/deployment/openshift/) |\n\nFor comprehensive deployment guides, see **[Deployment Documentation](https://ibm.github.io/mcp-context-forge/deployment/)**.\n\n---\n\n## API Reference\n\nInteractive API documentation is available when the server is running:\n\n- **[Swagger UI](http://localhost:4444/docs)** — Try API calls directly in your browser\n- **[ReDoc](http://localhost:4444/redoc)** — Browse the complete endpoint reference\n\n**Quick Authentication:**\n```bash\n# Generate a JWT token\nexport TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \\\n  --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes)\n\n# Test API access\ncurl -H \"Authorization: Bearer $TOKEN\" http://localhost:4444/health\n```\n\nFor comprehensive curl examples covering all endpoints, see the **[API Usage Guide](https://ibm.github.io/mcp-context-forge/manage/api-usage/)**.\n\n---\n\n## Testing\n\n```bash\nmake test            # Run unit tests\nmake lint            # Run all linters\nmake doctest         # Run doctests\nmake coverage        # Generate coverage report\n```\n\nSee [Doctest Coverage Guide](https://ibm.github.io/mcp-context-forge/development/doctest-coverage/) for documentation testing details.\n\n---\n\n## Project Structure\n\n```\nmcpgateway/          # Core FastAPI application\n├── main.py          # Entry point\n├── config.py        # Pydantic Settings configuration\n├── db.py            # SQLAlchemy ORM models\n├── schemas.py       # Pydantic validation schemas\n├── services/        # Business logic layer (50+ services)\n├── routers/         # HTTP endpoint definitions\n├── middleware/      # Cross-cutting concerns\n└── transports/      # SSE, WebSocket, stdio, streamable HTTP\n\ntests/               # Test suite (7,000+ tests)\ndocs/docs/           # Full documentation (MkDocs)\ncharts/              # Kubernetes/Helm charts\nplugins/             # Plugin framework and implementations\nmcp-servers/         # Sample/test MCP servers (see note below)\n```\n\n\u003e **Note:** The `mcp-servers/` directory contains **unsupported sample and test servers**,\n\u003e most originating from community contributions, provided for demonstration and integration\n\u003e testing purposes only. They generally lack session management, persistent state,\n\u003e multi-tenancy, authentication, and other production concerns. They do not go through\n\u003e the same review, testing, and security rigor as the core ContextForge codebase and\n\u003e **should not be run in production**.\n\u003e\n\u003e **Security:** Never run untrusted MCP servers directly on your local filesystem.\n\u003e Always use a sandbox, container, or microVM (e.g. gVisor, Firecracker) with\n\u003e restricted capabilities. Exercise caution when registering any remote MCP server,\n\u003e including servers from public catalogs — perform your own security evaluation\n\u003e before granting access to your gateway.\n\nFor complete structure, see [CONTRIBUTING.md](./CONTRIBUTING.md) or run `tree -L 2`.\n\n---\n\n## Development\n\n```bash\nmake dev             # Dev server with auto-reload (:8000)\nmake test            # Run test suite\nmake lint            # Run all linters\nmake coverage        # Generate coverage report\n```\n\nRun `make` to see all available targets.\n\nFor development workflows, see:\n- **[Developer Workstation Setup](https://ibm.github.io/mcp-context-forge/development/developer-workstation/)**\n- **[Building \u0026 Packaging](https://ibm.github.io/mcp-context-forge/development/building/)**\n\n---\n\n## Troubleshooting\n\nCommon issues and solutions:\n\n| Issue | Quick Fix |\n|-------|-----------|\n| SQLite \"disk I/O error\" on macOS | Avoid iCloud-synced directories; use `~/mcp-context-forge/data` |\n| Port 4444 not accessible on WSL2 | Configure WSL integration in Docker Desktop |\n| Gateway exits immediately | Copy `.env.example` to `.env` and configure required vars |\n| `ModuleNotFoundError` | Run `make install-dev` |\n\nFor detailed troubleshooting guides, see **[Troubleshooting Documentation](https://ibm.github.io/mcp-context-forge/manage/troubleshooting/)**.\n\n---\n\n## Contributing\n\n1. Fork the repo, create a feature branch.\n2. Run `make lint` and fix any issues.\n3. Keep `make test` green.\n4. Open a PR with signed commits (`git commit -s`).\n\nSee **[CONTRIBUTING.md](CONTRIBUTING.md)** for full guidelines and **[Issue Guide #2502](https://github.com/IBM/mcp-context-forge/issues/2502)** for how to file bugs, request features, and find issues to work on.\n\n---\n\n## Changelog\n\nA complete changelog can be found here: [CHANGELOG.md](./CHANGELOG.md)\n\n## License\n\nLicensed under the **Apache License 2.0** - see [LICENSE](./LICENSE)\n\n\n## Core Authors and Maintainers\n\n- [Mihai Criveti](https://www.linkedin.com/in/crivetimihai) - Distinguished Engineer, Agentic AI\n\nSpecial thanks to our contributors for helping us improve ContextForge:\n\n\u003ca href=\"https://github.com/ibm/mcp-context-forge/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=ibm/mcp-context-forge\u0026max=100\u0026anon=0\u0026columns=10\" alt=\"Contributors to the mcp-context-forge repository\" /\u003e\n\u003c/a\u003e\n\n## Star History and Project Activity\n\n[![Star History Chart](https://api.star-history.com/svg?repos=ibm/mcp-context-forge\u0026type=Date)](https://www.star-history.com/#ibm/mcp-context-forge\u0026Date)\n\n\u003c!-- === Usage Stats === --\u003e\n[![PyPi Downloads](https://static.pepy.tech/badge/mcp-contextforge-gateway/month)](https://pepy.tech/project/mcp-contextforge-gateway)\u0026nbsp;\n[![Stars](https://img.shields.io/github/stars/ibm/mcp-context-forge?style=social)](https://github.com/ibm/mcp-context-forge/stargazers)\u0026nbsp;\n[![Forks](https://img.shields.io/github/forks/ibm/mcp-context-forge?style=social)](https://github.com/ibm/mcp-context-forge/network/members)\u0026nbsp;\n[![Contributors](https://img.shields.io/github/contributors/ibm/mcp-context-forge)](https://github.com/ibm/mcp-context-forge/graphs/contributors)\u0026nbsp;\n[![Last Commit](https://img.shields.io/github/last-commit/ibm/mcp-context-forge)](https://github.com/ibm/mcp-context-forge/commits)\u0026nbsp;\n[![Open Issues](https://img.shields.io/github/issues/ibm/mcp-context-forge)](https://github.com/ibm/mcp-context-forge/issues)\u0026nbsp;\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/ibm.github.io%2Fmcp-context-forge%2F","html_url":"https://awesome.ecosyste.ms/projects/ibm.github.io%2Fmcp-context-forge%2F","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/ibm.github.io%2Fmcp-context-forge%2F/lists"}