Skip to content
Back to search

mcp-context-forge

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 & Tool calling, and supports plugins.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/IBM/mcp-context-forge with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/IBM/mcp-context-forge'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ibm--mcp-context-forge/badge.svg)](/listings/ibm--mcp-context-forge)

HTML

<a href="/listings/ibm--mcp-context-forge"><img src="/api/listings/ibm--mcp-context-forge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

ContextForge is published on [PyPI](https://pypi.org/project/mcp-contextforge-gateway/) as `mcp-contextforge-gateway`.

---

> ⚠️ **`JWT_SECRET_KEY` and `AUTH_ENCRYPTION_SECRET` are required in every environment — including local development.** The gateway will not start without them. Generate real secrets with `python3 -m mcpgateway.scripts.init_secrets` before first run.

**TLDR** — single command using [uv](https://docs.astral.sh/uv/):

# 1️⃣  Generate secure secrets (creates .env.secrets)
python3 -m mcpgateway.scripts.init_secrets

# 2️⃣  Export the generated values
export JWT_SECRET_KEY="$(grep '^JWT_SECRET_KEY=' .env.secrets | cut -d= -f2)"
export AUTH_ENCRYPTION_SECRET="$(grep '^AUTH_ENCRYPTION_SECRET=' .env.secrets | cut -d= -f2)"

# 3️⃣  Start the gateway
JWT_SECRET_KEY="$JWT_SECRET_KEY" \
AUTH_ENCRYPTION_SECRET="$AUTH_ENCRYPTION_SECRET" \
MCPGATEWAY_UI_ENABLED=true \
MCPGATEWAY_ADMIN_API_ENABLED=true \
PLATFORM_ADMIN_EMAIL=admin@example.com \
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

<details> <summary><strong>📋 Prerequisites</strong></summary>

* **Python ≥ 3.11** * **curl + jq** - only for the last smoke-test step

</details>

1 - Install & run (copy-paste friendly)

# 1️⃣  Create an isolated env and install from PyPI
mkdir mcpgateway && cd mcpgateway
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install mcp-contextforge-gateway

# 2️⃣  Download .env.example and generate real secrets
curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
cp .env.example .env

# Generate cryptographically secure secrets into .env.secrets
python3 -m mcpgateway.scripts.init_secrets

# Patch the generated secrets into .env (replaces __REPLACE_ME__ placeholders)
python3 -m mcpgateway.scripts.init_secrets --patch-env .env

# 3️⃣  Start the gateway
mcpgateway --host 0.0.0.0 --port 4444 &

# 4️⃣  Generate a bearer token and smoke-test
export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
    --username admin@example.com --exp 10080 --secret "$JWT_SECRET_KEY")

curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     http://127.0.0.1:4444/version | jq

<details> <summary><strong>Windows (PowerShell) quick-start</strong></summary>

# 1️⃣  Isolated env + install from PyPI
mkdir mcpgateway ; cd mcpgateway
python3 -m venv .venv ; .\.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install mcp-contextforge-gateway

# 2️⃣  Download .env.example and generate real secrets
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example" -OutFile ".env.example"
Copy-Item .env.example .env

# Generate cryptographically secure secrets into .env.secrets
python3 -m mcpgateway.scripts.init_secrets

# Patch the generated secrets into .env (replaces __REPLACE_ME__ placeholders)
python3 -m mcpgateway.scripts.init_secrets --patch-env .env

# 3️⃣  Launch the gateway
mcpgateway.exe --host 0.0.0.0 --port 4444

# 4️⃣  Bearer token and smoke-test
$Env:JWT_SECRET_KEY = (Get-Content .env | Select-String '^JWT_SECRET_KEY=').ToString().Split('=')[1]
$Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token `
    --username admin@example.com --exp 10080 --secret $Env:JWT_SECRET_KEY

curl -s -H "Authorization: Bearer $Env:MCPGATEWAY_BEARER_TOKEN" `
     http://127.0.0.1:4444/version | jq

<details> <summary><strong>⚡ Alternative: uv (faster)</strong></summary>

# 1️⃣  Isolated env + install from PyPI using uv
mkdir mcpgateway ; cd mcpgateway
uv venv
.\.venv\Scripts\activate
uv pip install mcp-contextforge-gateway

# Continue with steps 2️⃣-4️⃣ above...

</details>

</details>

<details> <summary><strong>More configuration</strong></summary>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,007 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # ContextForge
  2. > 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.
  3. ![ContextForge Banner](docs/docs/images/contextforge-logo_horizontal_black.png)
  4. <!-- === CI / Security / Build Badges === -->
  5. [![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)&nbsp;
  6. [![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)&nbsp;
  7. [![Tests & 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)&nbsp;
  8. [![Lint & 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)
  9. <!-- === Package / Container === -->
  10. [![Async](https://img.shields.io/badge/async-await-green.svg)](https://docs.python.org/3/library/asyncio.html)
  11. [![License](https://img.shields.io/github/license/ibm/mcp-context-forge)](LICENSE)&nbsp;
  12. [![PyPI](https://img.shields.io/pypi/v/mcp-contextforge-gateway)](https://pypi.org/project/mcp-contextforge-gateway/)&nbsp;
  13. [![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)&nbsp;
  14. **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:
  15. - **Tools Gateway** — MCP, REST, gRPC-to-MCP translation, and TOON compression
  16. - **Agent Gateway** — A2A protocol, OpenAI-compatible and Anthropic agent routing
  17. - **API Gateway** — Rate limiting, auth, retries, and reverse proxy for REST services
  18. - **Plugin Extensibility** — 40+ plugins for additional transports, protocols, and integrations
  19. - **Observability** — OpenTelemetry tracing with Phoenix, Jaeger, Zipkin, and other OTLP backends
  20. 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.
  21. ![ContextForge Web UI](docs/docs/images/mcpgateway.gif)
  22. ---
  23. <!-- vscode-markdown-toc -->
  24. ## Table of Contents
  25. - [Overview & Goals](#overview--goals)
  26. - [Quick Start - PyPI](#quick-start---pypi)
  27. - [Quick Start - Containers](#quick-start---containers)
  28. - [Optional Web UI](#optional-web-ui)
  29. - [VS Code Dev Container](#quick-start-vs-code-dev-container)
  30. - [Installation](#installation)
  31. - [Upgrading](#upgrading)
  32. - [Configuration](#configuration)
  33. - [Running](#running)
  34. - [Cloud Deployment](#cloud-deployment)
  35. - [API Reference](#api-reference)
  36. - [Testing](#testing)
  37. - [Project Structure](#project-structure)
  38. - [Development](#development)
  39. - [Troubleshooting](#troubleshooting)
  40. - [Contributing](#contributing)
  41. ---
  42. ### 📌 Quick Links
  43. | Resource | Description |
  44. |----------|-------------|
  45. | **[5-Minute Setup](https://github.com/IBM/mcp-context-forge/issues/2503)** | Get started fast — uvx, Docker, Compose, or local dev |
  46. | **[Getting Help](https://github.com/IBM/mcp-context-forge/issues/2504)** | Support options, FAQ, community channels |
  47. | **[Issue Guide](https://github.com/IBM/mcp-context-forge/issues/2502)** | How to file bugs, request features, contribute |
  48. | **[Full Documentation](https://ibm.github.io/mcp-context-forge/)** | Complete guides, tutorials, API reference |
  49. | **[Deprecations](https://ibm.github.io/mcp-context-forge/deprecations/)** | Deprecated runtime paths and migration guidance |
  50. ---
  51. ## Overview & Goals
  52. **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.
  53. It currently supports:
  54. * Federation across multiple MCP and REST services
  55. * **A2A (Agent-to-Agent) integration** for external AI agents (OpenAI, Anthropic, custom)
  56. * **gRPC-to-MCP translation** via automatic reflection-based service discovery
  57. * Virtualization of legacy APIs as MCP-compliant tools and servers
  58. * Transport over HTTP, JSON-RPC, WebSocket, SSE (with configurable keepalive), and Streamable HTTP; stdio transport available for server-side use
  59. * An Admin UI for real-time management, configuration, and log monitoring (with airgapped deployment support)
  60. * A redesigned, more user-friendly [Web UI](#optional-web-ui) that runs in a separate container
  61. * Built-in auth, retries, and rate-limiting with user-scoped OAuth tokens and unconditional X-Upstream-Authorization header support
  62. * **OpenTelemetry observability** with Phoenix, Jaeger, Zipkin, and other OTLP backends
  63. * Scalable deployments via Docker or PyPI, Redis-backed caching, and multi-cluster federation
  64. ![ContextForge Architecture](https://ibm.github.io/mcp-context-forge/images/mcpgateway.svg)
  65. For a list of upcoming features, check out the [ContextForge Roadmap](https://ibm.github.io/mcp-context-forge/architecture/roadmap/)
  66. ---
  67. <details>
  68. <summary><strong>🔌 Gateway Layer with Protocol Flexibility</strong></summary>
  69. * Federates any MCP server or REST API
  70. * Lets you choose your MCP protocol version (e.g., `2025-11-25`)
  71. * Exposes a single, unified interface for diverse backends
  72. </details>
  73. <details>
  74. <summary><strong>🧩 Virtualization of REST/gRPC Services</strong></summary>
  75. * Wraps non-MCP services as virtual MCP servers
  76. * Registers tools, prompts, and resources with minimal configuration
  77. * **gRPC-to-MCP translation** via server reflection protocol
  78. * Automatic service discovery and method introspection
  79. </details>
  80. <details>
  81. <summary><strong>🔁 REST-to-MCP Tool Adapter</strong></summary>
  82. * Adapts REST APIs into tools with:
  83. * Automatic JSON Schema extraction
  84. * Support for headers, tokens, and custom auth
  85. * Retry, timeout, and rate-limit policies
  86. </details>
  87. <details>
  88. <summary><strong>🧠 Unified Registries</strong></summary>
  89. * **Prompts**: Jinja2 templates, multimodal support, rollback/versioning
  90. * **Resources**: URI-based access, MIME detection, caching, SSE updates
  91. * **Tools**: Native or adapted, with input validation and concurrency controls
  92. </details>
  93. <details>
  94. <summary><strong>📈 Admin UI, Observability & Dev Experience</strong></summary>
  95. * Admin UI built with HTMX 2.0.3 (bundled) + Alpine.js
  96. * Real-time log viewer with filtering, search, and export capabilities
  97. * Auth: Basic, JWT, or custom schemes
  98. * Structured logs, health endpoints, metrics
  99. * 7,000+ tests, Makefile targets, live reload, pre-commit hooks
  100. </details>
  101. <details>
  102. <summary><strong>🔍 OpenTelemetry Observability</strong></summary>
  103. * **Vendor-agnostic tracing** with OpenTelemetry (OTLP) protocol support
  104. * **Multiple backend support**: Phoenix (LLM-focused), Jaeger, Zipkin, Tempo, DataDog, New Relic
  105. * **Distributed tracing** across federated gateways and services
  106. * **Automatic instrumentation** of tools, prompts, resources, and gateway operations
  107. * **LLM-specific metrics**: Token usage, costs, model performance
  108. * **Zero-overhead when disabled** with graceful degradation
  109. See **[Observability Documentation](https://ibm.github.io/mcp-context-forge/manage/observability/)** for setup guides with Phoenix, Jaeger, and other backends.
  110. </details>
  111. ---
  112. ## Quick Start - PyPI
  113. ContextForge is published on [PyPI](https://pypi.org/project/mcp-contextforge-gateway/) as `mcp-contextforge-gateway`.
  114. ---
  115. > ⚠️ **`JWT_SECRET_KEY` and `AUTH_ENCRYPTION_SECRET` are required in every environment — including local development.** The gateway will not start without them. Generate real secrets with `python3 -m mcpgateway.scripts.init_secrets` before first run.
  116. **TLDR** — single command using [uv](https://docs.astral.sh/uv/):
  117. ```bash
  118. # 1️⃣ Generate secure secrets (creates .env.secrets)
  119. python3 -m mcpgateway.scripts.init_secrets
  120. # 2️⃣ Export the generated values
  121. export JWT_SECRET_KEY="$(grep '^JWT_SECRET_KEY=' .env.secrets | cut -d= -f2)"
  122. export AUTH_ENCRYPTION_SECRET="$(grep '^AUTH_ENCRYPTION_SECRET=' .env.secrets | cut -d= -f2)"
  123. # 3️⃣ Start the gateway
  124. JWT_SECRET_KEY="$JWT_SECRET_KEY" \
  125. AUTH_ENCRYPTION_SECRET="$AUTH_ENCRYPTION_SECRET" \
  126. MCPGATEWAY_UI_ENABLED=true \
  127. MCPGATEWAY_ADMIN_API_ENABLED=true \
  128. PLATFORM_ADMIN_EMAIL=admin@example.com \
  129. uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444
  130. ```
  131. <details>
  132. <summary><strong>📋 Prerequisites</strong></summary>
  133. * **Python ≥ 3.11**
  134. * **curl + jq** - only for the last smoke-test step
  135. </details>
  136. ### 1 - Install & run (copy-paste friendly)
  137. ```bash
  138. # 1️⃣ Create an isolated env and install from PyPI
  139. mkdir mcpgateway && cd mcpgateway
  140. python3 -m venv .venv && source .venv/bin/activate
  141. pip install --upgrade pip
  142. pip install mcp-contextforge-gateway
  143. # 2️⃣ Download .env.example and generate real secrets
  144. curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
  145. cp .env.example .env
  146. # Generate cryptographically secure secrets into .env.secrets
  147. python3 -m mcpgateway.scripts.init_secrets
  148. # Patch the generated secrets into .env (replaces __REPLACE_ME__ placeholders)
  149. python3 -m mcpgateway.scripts.init_secrets --patch-env .env
  150. # 3️⃣ Start the gateway
  151. mcpgateway --host 0.0.0.0 --port 4444 &
  152. # 4️⃣ Generate a bearer token and smoke-test
  153. export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)
  154. export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
  155. --username admin@example.com --exp 10080 --secret "$JWT_SECRET_KEY")
  156. curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  157. http://127.0.0.1:4444/version | jq
  158. ```
  159. <details>
  160. <summary><strong>Windows (PowerShell) quick-start</strong></summary>
  161. ```powershell
  162. # 1️⃣ Isolated env + install from PyPI
  163. mkdir mcpgateway ; cd mcpgateway
  164. python3 -m venv .venv ; .\.venv\Scripts\Activate.ps1
  165. pip install --upgrade pip
  166. pip install mcp-contextforge-gateway
  167. # 2️⃣ Download .env.example and generate real secrets
  168. Invoke-WebRequest -Uri "https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example" -OutFile ".env.example"
  169. Copy-Item .env.example .env
  170. # Generate cryptographically secure secrets into .env.secrets
  171. python3 -m mcpgateway.scripts.init_secrets
  172. # Patch the generated secrets into .env (replaces __REPLACE_ME__ placeholders)
  173. python3 -m mcpgateway.scripts.init_secrets --patch-env .env
  174. # 3️⃣ Launch the gateway
  175. mcpgateway.exe --host 0.0.0.0 --port 4444
  176. # 4️⃣ Bearer token and smoke-test
  177. $Env:JWT_SECRET_KEY = (Get-Content .env | Select-String '^JWT_SECRET_KEY=').ToString().Split('=')[1]
  178. $Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token `
  179. --username admin@example.com --exp 10080 --secret $Env:JWT_SECRET_KEY
  180. curl -s -H "Authorization: Bearer $Env:MCPGATEWAY_BEARER_TOKEN" `
  181. http://127.0.0.1:4444/version | jq
  182. ```
  183. <details>
  184. <summary><strong>⚡ Alternative: uv (faster)</strong></summary>
  185. ```powershell
  186. # 1️⃣ Isolated env + install from PyPI using uv
  187. mkdir mcpgateway ; cd mcpgateway
  188. uv venv
  189. .\.venv\Scripts\activate
  190. uv pip install mcp-contextforge-gateway
  191. # Continue with steps 2️⃣-4️⃣ above...
  192. ```
  193. </details>
  194. </details>
  195. <details>
  196. <summary><strong>More configuration</strong></summary>
  197. Copy [.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).
  198. </details>
  199. <details>
  200. <summary><strong>🚀 End-to-end demo (register a local MCP server)</strong></summary>
  201. ```bash
  202. # 1️⃣ Spin up the sample MCP time server using mcpgateway.translate & docker (replace docker with podman if needed)
  203. python3 -m mcpgateway.translate \
  204. --stdio "docker run --rm -i ghcr.io/ibm/fast-time-server:latest -transport=stdio" \
  205. --expose-sse \
  206. --port 8003
  207. # Or using the official mcp-server-git using uvx:
  208. pip install uv # to install uvx, if not already installed
  209. python3 -m mcpgateway.translate --stdio "uvx mcp-server-git" --expose-sse --port 9000
  210. # NEW: Expose via multiple protocols simultaneously!
  211. python3 -m mcpgateway.translate \
  212. --stdio "uvx mcp-server-git" \
  213. --expose-sse \
  214. --expose-streamable-http \
  215. --port 9000
  216. # Now accessible via both /sse (SSE) and /mcp (streamable HTTP) endpoints
  217. # 2️⃣ Register it with the gateway
  218. curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  219. -H "Content-Type: application/json" \
  220. -d '{"name":"fast_time","url":"http://localhost:8003/sse"}' \
  221. http://localhost:4444/gateways
  222. # 3️⃣ Verify tool catalog
  223. curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools | jq
  224. # 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.
  225. curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  226. -H "Content-Type: application/json" \
  227. -d '{"server":{"name":"time_server","description":"Fast time tools","associated_tools":[<ID_OF_TOOLS>]}}' \
  228. http://localhost:4444/servers | jq
  229. # Example curl
  230. curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  231. -H "Content-Type: application/json" \
  232. -d '{"server":{"name":"time_server","description":"Fast time tools","associated_tools":["6018ca46d32a4ac6b4c054c13a1726a2"]}}' \
  233. http://localhost:4444/servers | jq
  234. # 5️⃣ List servers (should now include the UUID of the newly created virtual server)
  235. curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/servers | jq
  236. # 6️⃣ Client HTTP endpoint. Inspect it interactively with the MCP Inspector CLI (or use any MCP client)
  237. npx -y @modelcontextprotocol/inspector
  238. # Transport Type: Streamable HTTP, URL: http://localhost:4444/servers/UUID_OF_SERVER_1/mcp, Header Name: "Authorization", Bearer Token
  239. ```
  240. </details>
  241. ---
  242. ## Quick Start - Containers
  243. Use the official OCI image from GHCR with **Docker** *or* **Podman**.
  244. Please 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.
  245. ### 🚀 Quick Start - Docker Compose
  246. > **Important:** `docker compose up -d` does **not** build the gateway image locally by default — it uses the pre-built image from GHCR. The compose file includes a `build:` block as a fallback, but local builds require a hermetic wheel closure that is only produced by the CI pipeline. If you see a `cryptography` or dependency resolution error during build, you are hitting this — just pull the image instead (step 2 below handles this automatically).
  247. >
  248. > You also **must** have a `.env` file with real secrets before running `docker compose up -d`. The gateway will not start with placeholder values.
  249. Get a full stack running with PostgreSQL and Redis:
  250. ```bash
  251. # 1️⃣ Clone the repository
  252. git clone https://github.com/IBM/mcp-context-forge.git
  253. cd mcp-context-forge
  254. # 2️⃣ Set up .env with real secrets AND pull the pre-built images
  255. cp .env.example .env
  256. python3 -m mcpgateway.scripts.init_secrets --patch-env .env
  257. # .env now has strong JWT_SECRET_KEY and AUTH_ENCRYPTION_SECRET
  258. # Pull pre-built images from GHCR (avoids local build entirely)
  259. docker pull ghcr.io/ibm/mcp-context-forge:latest
  260. echo 'IMAGE_LOCAL=ghcr.io/ibm/mcp-context-forge:latest' >> .env
  261. # Build only the nginx image (small, local-only, builds in seconds)
  262. docker compose build nginx
  263. # 3️⃣ Start the full stack
  264. docker compose up -d
  265. # 4️⃣ Check status
  266. docker compose ps
  267. # 5️⃣ View logs
  268. docker compose logs -f gateway
  269. # 6️⃣ Access Admin UI: http://localhost:8080/admin
  270. # Login: PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD (from .env)
  271. # 7️⃣ Generate an API token
  272. export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)
  273. docker compose exec gateway python3 -m mcpgateway.utils.create_jwt_token \
  274. --username admin@example.com --exp 10080 --secret "$JWT_SECRET_KEY"
  275. ```
  276. **What you get:**
  277. - 🗄️ **PostgreSQL** - Production-ready database with 55+ tables
  278. - 🚀 **ContextForge** - Full-featured gateway with Admin UI
  279. - 📊 **Redis** - High-performance caching and session storage
  280. - 🔧 **Admin Tools** - pgAdmin, Redis Insight for database management
  281. - 🌐 **Nginx Proxy** - Caching reverse proxy on port 8080
  282. **Enable HTTPS (optional):**
  283. ```bash
  284. # Start with TLS enabled (auto-generates self-signed certs)
  285. make compose-tls
  286. # Access via HTTPS: https://localhost:8443/admin
  287. # Or bring your own certificates:
  288. # Unencrypted key:
  289. mkdir -p certs
  290. cp your-cert.pem certs/cert.pem && cp your-key.pem certs/key.pem
  291. make compose-tls
  292. # Passphrase-protected key:
  293. mkdir -p certs
  294. cp your-cert.pem certs/cert.pem && cp your-encrypted-key.pem certs/key-encrypted.pem
  295. echo "KEY_FILE_PASSWORD=your-passphrase" >> .env
  296. make compose-tls
  297. ```
  298. #### Optional Web UI
  299. The **ContextForge Web UI v0.2.4** provides a redesigned, more user-friendly interface, separate from the built-in Admin UI.
  300. It runs in its own container and connects to the gateway API.
  301. After the Docker Compose setup above, start the Web UI with these commands from the gateway checkout:
  302. ```bash
  303. make compose-pull PROFILE="--profile ui"
  304. make compose-up PROFILE="--profile ui"
  305. ```
  306. Open [http://localhost:3001](http://localhost:3001) and sign in with your gateway account.
  307. Set `WEB_UI_PORT` in `.env` to change the port.
  308. The `ui` profile starts the Web UI and its dedicated Redis session store alongside the gateway.
  309. `PROFILE` replaces the Makefile's default profiles.
  310. On `linux/amd64`, use `PROFILE="--profile with-fast-time --profile ui"` in both commands to retain the default fast-time service.
  311. For separate npm development setup, see the [Web UI setup guide](https://github.com/contextforge-org/contextforge-web-ui/blob/v0.2.4/README.md#getting-started).
  312. ### ☸️ Quick Start - Helm (Kubernetes)
  313. Deploy to Kubernetes with enterprise-grade features:
  314. ```bash
  315. # Add Helm repository (when available)
  316. # helm repo add mcp-context-forge https://ibm.github.io/mcp-context-forge
  317. # helm repo update
  318. # For now, use local chart
  319. git clone https://github.com/IBM/mcp-context-forge.git
  320. cd mcp-context-forge/charts/mcp-stack
  321. # Generate secrets first
  322. python3 -m mcpgateway.scripts.init_secrets
  323. JWT_SECRET=$(grep '^JWT_SECRET_KEY=' .env.secrets | cut -d= -f2)
  324. ENC_SECRET=$(grep '^AUTH_ENCRYPTION_SECRET=' .env.secrets | cut -d= -f2)
  325. # Install with PostgreSQL (default)
  326. # IMPORTANT: replace <strong-password> with a real password — do not use 'changeme' in production
  327. helm install mcp-gateway . \
  328. --set mcpContextForge.secret.PLATFORM_ADMIN_EMAIL=admin@yourcompany.com \
  329. --set mcpContextForge.secret.PLATFORM_ADMIN_PASSWORD=<strong-password> \
  330. --set mcpContextForge.secret.BASIC_AUTH_PASSWORD=<strong-password> \
  331. --set "mcpContextForge.secret.JWT_SECRET_KEY=${JWT_SECRET}" \
  332. --set "mcpContextForge.secret.AUTH_ENCRYPTION_SECRET=${ENC_SECRET}"
  333. # Check deployment status
  334. kubectl get pods -l app.kubernetes.io/name=mcp-context-forge
  335. # Port forward to access Admin UI
  336. kubectl port-forward svc/mcp-gateway-mcp-context-forge 4444:80
  337. # Access: http://localhost:4444/admin
  338. # Generate API token (reads JWT_SECRET_KEY from the pod's environment)
  339. kubectl exec deployment/mcp-gateway-mcp-context-forge -- \
  340. python3 -m mcpgateway.utils.create_jwt_token \
  341. --username admin@yourcompany.com --exp 10080 --secret "${JWT_SECRET}"
  342. ```
  343. > SSRF note: Helm defaults to strict SSRF settings (`SSRF_ALLOW_PRIVATE_NETWORKS=false`).
  344. > If you register in-cluster tool URLs, allow only your cluster CIDRs via
  345. > `mcpContextForge.config.SSRF_ALLOWED_NETWORKS` or, for local-only benchmark
  346. > setups, temporarily set `SSRF_ALLOW_PRIVATE_NETWORKS=true`.
  347. > See `docs/docs/manage/configuration.md#ssrf-protection` and `docs/docs/deployment/helm.md`.
  348. **Enterprise Features:**
  349. - 🔄 **Auto-scaling** - HPA with CPU/memory targets
  350. - 🗄️ **Database Choice** - PostgreSQL (prod), SQLite (dev)
  351. - 📊 **Observability** - Prometheus metrics, OpenTelemetry tracing
  352. - 🔒 **Security** - RBAC, network policies, secret management
  353. - 🚀 **High Availability** - Multi-replica deployments with Redis clustering
  354. - 📈 **Monitoring** - Built-in Grafana dashboards and alerting
  355. ---
  356. ### 🐳 Docker (Single Container)
  357. ```bash
  358. # Generate secrets first (creates .env.secrets)
  359. python3 -m mcpgateway.scripts.init_secrets
  360. export JWT_SECRET_KEY="$(grep '^JWT_SECRET_KEY=' .env.secrets | cut -d= -f2)"
  361. export AUTH_ENCRYPTION_SECRET="$(grep '^AUTH_ENCRYPTION_SECRET=' .env.secrets | cut -d= -f2)"
  362. docker run -d --name mcpgateway \
  363. -p 4444:4444 \
  364. -e MCPGATEWAY_UI_ENABLED=true \
  365. -e MCPGATEWAY_ADMIN_API_ENABLED=true \
  366. -e HOST=0.0.0.0 \
  367. -e JWT_SECRET_KEY="${JWT_SECRET_KEY}" \
  368. -e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \
  369. -e AUTH_REQUIRED=true \
  370. -e PLATFORM_ADMIN_EMAIL=admin@example.com \
  371. -e PLATFORM_ADMIN_PASSWORD=<strong-password> \
  372. -e PLATFORM_ADMIN_FULL_NAME="Platform Administrator" \
  373. -e DATABASE_URL=sqlite:///./mcp.db \
  374. -e SECURE_COOKIES=false \
  375. ghcr.io/ibm/mcp-context-forge:latest
  376. # Tail logs
  377. docker logs -f mcpgateway
  378. # Generate API token (using the same secret)
  379. docker run --rm -it \
  380. -e JWT_SECRET_KEY="${JWT_SECRET_KEY}" \
  381. ghcr.io/ibm/mcp-context-forge:latest \
  382. python3 -m mcpgateway.utils.create_jwt_token \
  383. --username admin@example.com --exp 10080 --secret "${JWT_SECRET_KEY}"
  384. ```
  385. Browse to **[http://localhost:4444/admin](http://localhost:4444/admin)** and login with `PLATFORM_ADMIN_EMAIL` / `PLATFORM_ADMIN_PASSWORD`.
  386. <details>
  387. <summary><strong>Advanced: Persistent storage, host networking, airgapped</strong></summary>
  388. **Persist SQLite database:**
  389. ```bash
  390. mkdir -p $(pwd)/data && touch $(pwd)/data/mcp.db && chmod 777 $(pwd)/data
  391. docker run -d --name mcpgateway --restart unless-stopped \
  392. -p 4444:4444 -v $(pwd)/data:/data \
  393. -e DATABASE_URL=sqlite:////data/mcp.db \
  394. -e MCPGATEWAY_UI_ENABLED=true -e MCPGATEWAY_ADMIN_API_ENABLED=true \
  395. -e HOST=0.0.0.0 -e JWT_SECRET_KEY="${JWT_SECRET_KEY}" \
  396. -e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \
  397. -e PLATFORM_ADMIN_EMAIL=admin@example.com -e PLATFORM_ADMIN_PASSWORD=<strong-password> \
  398. ghcr.io/ibm/mcp-context-forge:latest
  399. ```
  400. **Host networking** (access local MCP servers):
  401. ```bash
  402. docker run -d --name mcpgateway --network=host \
  403. -v $(pwd)/data:/data -e DATABASE_URL=sqlite:////data/mcp.db \
  404. -e MCPGATEWAY_UI_ENABLED=true -e HOST=0.0.0.0 -e PORT=4444 \
  405. -e JWT_SECRET_KEY="${JWT_SECRET_KEY}" -e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \
  406. ghcr.io/ibm/mcp-context-forge:latest
  407. ```
  408. **Airgapped deployment** (no internet):
  409. ```bash
  410. docker build -f Containerfile -t mcpgateway:airgapped .
  411. docker run -d --name mcpgateway -p 4444:4444 \
  412. -e MCPGATEWAY_UI_AIRGAPPED=true -e MCPGATEWAY_UI_ENABLED=true \
  413. -e HOST=0.0.0.0 -e JWT_SECRET_KEY="${JWT_SECRET_KEY}" \
  414. -e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \
  415. mcpgateway:airgapped
  416. ```
  417. </details>
  418. ---
  419. ### 🦭 Podman (rootless-friendly)
  420. ```bash
  421. podman run -d --name mcpgateway \
  422. -p 4444:4444 -e HOST=0.0.0.0 -e DATABASE_URL=sqlite:///./mcp.db \
  423. ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3
  424. ```
  425. <details>
  426. <summary><strong>Advanced: Persistent storage, host networking</strong></summary>
  427. **Persist SQLite:**
  428. ```bash
  429. mkdir -p $(pwd)/data && chmod 777 $(pwd)/data
  430. podman run -d --name mcpgateway --restart=on-failure \
  431. -p 4444:4444 -v $(pwd)/data:/data \
  432. -e DATABASE_URL=sqlite:////data/mcp.db \
  433. ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3
  434. ```
  435. **Host networking:**
  436. ```bash
  437. podman run -d --name mcpgateway --network=host \
  438. -v $(pwd)/data:/data -e DATABASE_URL=sqlite:////data/mcp.db \
  439. ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3
  440. ```
  441. </details>
  442. ---
  443. <details>
  444. <summary><strong>✏️ Docker/Podman tips</strong></summary>
  445. * **.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.
  446. * **Pinned tags** - Use an explicit version (e.g. `1.0.0-RC-3`) instead of `latest` for reproducible builds.
  447. * **JWT tokens** - Generate one in the running container (reads the secret from the container environment):
  448. ```bash
  449. docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token \
  450. --username admin@example.com --exp 10080 --secret "${JWT_SECRET_KEY}"
  451. ```
  452. * **Upgrades** - Stop, remove, and rerun with the same `-v $(pwd)/data:/data` mount; your DB and config stay intact.
  453. </details>
  454. ---
  455. <details>
  456. <summary><strong>🚑 Smoke-test the running container</strong></summary>
  457. ```bash
  458. curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  459. http://localhost:4444/health | jq
  460. curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  461. http://localhost:4444/tools | jq
  462. curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
  463. http://localhost:4444/version | jq
  464. ```
  465. </details>
  466. ---
  467. ## Quick Start: VS Code Dev Container
  468. Clone 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.
  469. For detailed setup, workflows, and GitHub Codespaces instructions, see **[Developer Onboarding](https://ibm.github.io/mcp-context-forge/development/developer-onboarding/)**.
  470. ---
  471. ## Installation
  472. ```bash
  473. make venv install-dev # create .venv + install deps + build Admin UI
  474. make serve # gunicorn on :4444
  475. ```
  476. <details>
  477. <summary><strong>Alternative: UV or pip</strong></summary>
  478. ```bash
  479. # UV (faster)
  480. uv venv && source .venv/bin/activate
  481. uv pip install -e '.[dev]'
  482. # pip
  483. python3 -m venv .venv && source .venv/bin/activate
  484. pip install -e ".[dev]"
  485. ```
  486. </details>
  487. <details>
  488. <summary><strong>PostgreSQL adapter setup</strong></summary>
  489. Install the `psycopg` driver for PostgreSQL:
  490. ```bash
  491. # Install system dependencies first
  492. # Debian/Ubuntu: sudo apt-get install libpq-dev
  493. # macOS: brew install libpq
  494. uv pip install 'psycopg[binary]' # dev (pre-built wheels)
  495. # or: uv pip install 'psycopg[c]' # production (requires compiler)
  496. ```
  497. Connection URL format:
  498. ```bash
  499. DATABASE_URL=postgresql+psycopg://user:password@localhost:5432/mcp
  500. ```
  501. Quick Postgres container:
  502. ```bash
  503. docker run --name mcp-postgres \
  504. -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=mysecretpassword \
  505. -e POSTGRES_DB=mcp -p 5432:5432 -d postgres
  506. ```
  507. </details>
  508. ---
  509. ## Upgrading
  510. For upgrade instructions, migration guides, and rollback procedures, see:
  511. - **[Upgrade Guide](https://ibm.github.io/mcp-context-forge/manage/upgrade/)** — General upgrade procedures
  512. - **[MIGRATION.md](./MIGRATION.md)** — Breaking changes and step-by-step upgrade instructions
  513. - **[CHANGELOG.md](./CHANGELOG.md)** — Version history and breaking changes
  514. ---
  515. ## Configuration
  516. > ⚠️ If any required `.env` variable is missing or invalid, the gateway will fail fast at startup with a validation error via Pydantic.
  517. Copy the provided [.env.example](https://github.com/IBM/mcp-context-forge/blob/main/.env.example) to `.env` and update the security-sensitive values below.
  518. ### 🔐 Required: Set Before Starting
  519. These variables **must be set** before the gateway will start. There are no usable defaults — the application fails at startup if these are missing or placeholder values:
  520. | Variable | Description | How to generate |
  521. |----------|-------------|-----------------|
  522. | `JWT_SECRET_KEY` | HMAC secret for signing JWTs (32+ chars) | `python3 -m mcpgateway.scripts.init_secrets` |
  523. | `AUTH_ENCRYPTION_SECRET` | Passphrase for encrypting stored credentials | `python3 -m mcpgateway.scripts.init_secrets` |
  524. These variables have insecure defaults and **should be changed** before production use:
  525. | Variable | Description | Default |
  526. |----------|-------------|---------|
  527. | `BASIC_AUTH_USER` | Username for HTTP Basic auth | `admin` |
  528. | `BASIC_AUTH_PASSWORD` | Password for HTTP Basic auth | **required — no default; set via `make init-secrets-patch-env`** |
  529. | `PLATFORM_ADMIN_EMAIL` | Email for bootstrap admin user | `admin@example.com` |
  530. | `PLATFORM_ADMIN_PASSWORD` | Password for bootstrap admin user | **required — set a strong value before first run** |
  531. | `PLATFORM_ADMIN_FULL_NAME` | Display name for bootstrap admin | `Admin User` |
  532. ### 🔒 Security Defaults (Secure by Default)
  533. These settings are enabled by default for security—only disable for backward compatibility:
  534. | Variable | Description | Default |
  535. |----------|-------------|---------|
  536. | `REQUIRE_JTI` | Require JTI claim in tokens for revocation support | `true` |
  537. | `REQUIRE_TOKEN_EXPIRATION` | Require exp claim in tokens | `true` |
  538. | `PUBLIC_REGISTRATION_ENABLED` | Allow public user self-registration | `false` |
  539. ### 🛡️ Content Security
  540. Content size limits prevent DoS attacks and ensure system stability:
  541. | Variable | Description | Default |
  542. |----------|-------------|---------|
  543. | `CONTENT_MAX_RESOURCE_SIZE` | Maximum resource content size (bytes) | `102400` (100KB) |
  544. | `CONTENT_MAX_PROMPT_SIZE` | Maximum prompt template size (bytes) | `10240` (10KB) |
  545. **Note:** Size limits apply only to new create/update operations. Existing content is not retroactively validated.
  546. ### 🌐 UAID Cross-Gateway Routing Security
  547. #### UAID Security Configuration
  548. **Production Requirements:**
  549. Cross-gateway UAID routing requires explicit security configuration:
  550. 1. **Configure Domain Allowlist:**
  551. ```bash
  552. UAID_ALLOWED_DOMAINS=["gateway1.example.com", "gateway2.example.com"]
  553. ```
  554. 2. **Ensure JWT Trust:**
  555. - Both gateways must trust the same JWT issuer
  556. - Option A: Shared secret (same `JWT_SECRET_KEY` on all gateways)
  557. - Option B: Federated SSO (Google, GitHub, Entra ID)
  558. 3. **Enable Authentication:**
  559. ```bash
  560. AUTH_REQUIRED=true
  561. UAID_FORWARD_AUTH=true
  562. ```
  563. **Authentication Flow:**
  564. Cross-gateway calls forward the user's bearer token via the `Authorization` header.
  565. Remote gateways validate tokens through existing auth middleware, preserving RBAC context.
  566. **Security Features:**
  567. - ✅ Fail-closed default: Empty allowlist blocks all cross-gateway routing
  568. - ✅ Bearer token forwarding: User authentication preserved across hops
  569. - ✅ Audit trail: Source gateway and user tracked in headers
  570. - ✅ Clear error messages: Misconfigurations caught at startup and runtime
  571. **Troubleshooting:**
  572. - **"UAID_ALLOWED_DOMAINS not configured" error:** Add trusted domains to allowlist in .env
  573. - **401/403 from remote gateway:** Verify both gateways trust same JWT issuer
  574. - **"proceeding without authentication token" warning:** Check auth middleware extracts token to `request.state.bearer_token`
  575. For detailed security architecture, see `docs/security/uaid-cross-gateway-auth.md`.
  576. ### ⚙️ Project Defaults (Dev Setup)
  577. These values differ from code defaults to provide a working local/dev setup:
  578. | Variable | Description | Default |
  579. |----------|-------------|---------|
  580. | `HOST` | Bind address | `0.0.0.0` |
  581. | `MCPGATEWAY_UI_ENABLED` | Enable Admin UI dashboard | `true` |
  582. | `MCPGATEWAY_ADMIN_API_ENABLED` | Enable Admin API endpoints | `true` |
  583. | `DATABASE_URL` | SQLAlchemy connection URL | `sqlite:///./mcp.db` |
  584. | `SECURE_COOKIES` | Set `false` for HTTP (non-HTTPS) dev | `false` |
  585. ### 📚 Full Configuration Reference
  586. For 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/)**.
  587. ---
  588. ## Running
  589. ### Quick Reference
  590. | Command | Server | Port | Database | Use Case |
  591. |---------|--------|------|----------|----------|
  592. | `make dev` | Uvicorn | **8000** | SQLite | Development (single instance, auto-reload) |
  593. | `make serve` | Gunicorn | **4444** | SQLite | Production single-node (multi-worker) |
  594. | `make serve-ssl` | Gunicorn | **4444** | SQLite | Production single-node with HTTPS |
  595. | `make compose-up` | Docker Compose + Nginx | **8080** | PostgreSQL + Redis | Full stack (3 replicas, load-balanced) |
  596. | `make compose-sso` | Docker Compose + Keycloak | **8080 / 8180** | PostgreSQL + Redis | Local SSO testing (Keycloak profile) |
  597. | `make testing-up` | Docker Compose + Nginx | **8080** | PostgreSQL + Redis | Testing environment |
  598. ### Development Server (Uvicorn)
  599. ```bash
  600. make dev # Uvicorn on :8000 with auto-reload and SQLite
  601. # or
  602. ./run.sh --reload --log debug --workers 2
  603. ```
  604. > `run.sh` is a wrapper around `uvicorn` that loads `.env`, supports reload, and passes arguments to the server.
  605. Key flags:
  606. | Flag | Purpose | Example |
  607. | ---------------- | ---------------- | ------------------ |
  608. | `-e, --env FILE` | load env-file | `--env prod.env` |
  609. | `-H, --host` | bind address | `--host 127.0.0.1` |
  610. | `-p, --port` | listen port | `--port 8080` |
  611. | `-w, --workers` | gunicorn workers | `--workers 4` |
  612. | `-r, --reload` | auto-reload | `--reload` |
  613. ### Production Server (Gunicorn)
  614. ```bash
  615. make serve # Gunicorn on :4444 with multiple workers
  616. make serve-ssl # Gunicorn behind HTTPS on :4444 (uses ./certs)
  617. ```
  618. ### Docker Compose (Full Stack)
  619. ```bash
  620. make compose-up # Start full stack: PostgreSQL, Redis, 3 gateway replicas, Nginx on :8080
  621. make compose-sso # Start SSO stack with Keycloak on :8180
  622. make sso-test-login # Run SSO smoke checks (providers + login URL + test users)
  623. make compose-logs # Tail logs from all services
  624. make compose-down # Stop the stack
  625. ```
  626. ### Manual (Uvicorn)
  627. ```bash
  628. uvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444 --workers 4
  629. ```
  630. ---
  631. ## Cloud Deployment
  632. ContextForge can be deployed to any major cloud platform:
  633. | Platform | Guide |
  634. |----------|-------|
  635. | **AWS** | [ECS/EKS Deployment](https://ibm.github.io/mcp-context-forge/deployment/aws/) |
  636. | **Azure** | [AKS Deployment](https://ibm.github.io/mcp-context-forge/deployment/azure/) |
  637. | **Google Cloud** | [Cloud Run](https://ibm.github.io/mcp-context-forge/deployment/google-cloud-run/) |
  638. | **IBM Cloud** | [Code Engine](https://ibm.github.io/mcp-context-forge/deployment/ibm-code-engine/) |
  639. | **Kubernetes** | [Helm Charts](https://ibm.github.io/mcp-context-forge/deployment/minikube/) |
  640. | **OpenShift** | [OpenShift Deployment](https://ibm.github.io/mcp-context-forge/deployment/openshift/) |
  641. For comprehensive deployment guides, see **[Deployment Documentation](https://ibm.github.io/mcp-context-forge/deployment/)**.
  642. ---
  643. ## API Reference
  644. Interactive API documentation is available when the server is running:
  645. - **[Swagger UI](http://localhost:4444/docs)** — Try API calls directly in your browser
  646. - **[ReDoc](http://localhost:4444/redoc)** — Browse the complete endpoint reference
  647. **Quick Authentication:**
  648. ```bash
  649. # Read JWT_SECRET_KEY from your .env (it must already contain a real secret)
  650. export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)
  651. # Generate a JWT token
  652. export TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
  653. --username admin@example.com --exp 10080 --secret "$JWT_SECRET_KEY")
  654. # Test API access
  655. curl -H "Authorization: Bearer $TOKEN" http://localhost:4444/health
  656. ```
  657. For comprehensive curl examples covering all endpoints, see the **[API Usage Guide](https://ibm.github.io/mcp-context-forge/manage/api-usage/)**.
  658. ---
  659. ## Testing
  660. ```bash
  661. make test # Run unit tests
  662. make lint # Run all linters
  663. make doctest # Run doctests
  664. make coverage # Generate coverage report
  665. ```
  666. See [Doctest Coverage Guide](https://ibm.github.io/mcp-context-forge/development/doctest-coverage/) for documentation testing details.
  667. ---
  668. ## Project Structure
  669. ```
  670. mcpgateway/ # Core FastAPI application
  671. ├── main.py # Entry point
  672. ├── config.py # Pydantic Settings configuration
  673. ├── db.py # SQLAlchemy ORM models
  674. ├── schemas.py # Pydantic validation schemas
  675. ├── services/ # Business logic layer (50+ services)
  676. ├── routers/ # HTTP endpoint definitions
  677. ├── middleware/ # Cross-cutting concerns
  678. └── transports/ # SSE, WebSocket, stdio, streamable HTTP
  679. tests/ # Test suite (7,000+ tests)
  680. docs/docs/ # Full documentation (MkDocs)
  681. charts/ # Kubernetes/Helm charts
  682. plugins/ # Plugin framework and implementations
  683. ```
  684. > **Security:** Never run untrusted MCP servers directly on your local filesystem.
  685. > Always use a sandbox, container, or microVM (e.g. gVisor, Firecracker) with
  686. > restricted capabilities. Exercise caution when registering any remote MCP server,
  687. > including servers from public catalogs — perform your own security evaluation
  688. > before granting access to your gateway.
  689. For complete structure, see [CONTRIBUTING.md](./CONTRIBUTING.md) or run `tree -L 2`.
  690. ---
  691. ## Development
  692. ```bash
  693. make dev # Dev server with auto-reload (:8000)
  694. make test # Run test suite
  695. make lint # Run all linters
  696. make coverage # Generate coverage report
  697. ```
  698. Run `make` to see all available targets.
  699. For development workflows, see:
  700. - **[Developer Workstation Setup](https://ibm.github.io/mcp-context-forge/development/developer-workstation/)**
  701. - **[Building & Packaging](https://ibm.github.io/mcp-context-forge/development/building/)**
  702. ---
  703. ## Troubleshooting
  704. Common issues and solutions:
  705. | Issue | Quick Fix |
  706. |-------|-----------|
  707. | `docker compose up` fails with `cryptography` or dependency resolution error | The local build requires a CI-produced wheel closure. Run `docker pull ghcr.io/ibm/mcp-context-forge:latest && echo 'IMAGE_LOCAL=ghcr.io/ibm/mcp-context-forge:latest' >> .env` then retry |
  708. | `docker compose up` fails with `SecurityConfigurationError: jwt_secret_key` | `.env` is missing or has `__REPLACE_ME__` placeholders. Run `cp .env.example .env && python3 -m mcpgateway.scripts.init_secrets --patch-env .env` |
  709. | `docker compose up` fails — `mcpgateway/nginx-cache` pull access denied | nginx image must be built locally: `docker compose build nginx` |
  710. | `make dev` — nothing on port 8000 | Check terminal for `SecurityConfigurationError` — run `make ensure-secrets` then retry. On WSL2 use `http://127.0.0.1:8000` not `localhost` |
  711. | SQLite "disk I/O error" on macOS | Avoid iCloud-synced directories; use `~/mcp-context-forge/data` |
  712. | Port 4444 not accessible on WSL2 | Configure WSL integration in Docker Desktop |
  713. | Gateway exits immediately | Run `cp .env.example .env && python3 -m mcpgateway.scripts.init_secrets --patch-env .env` |
  714. | `ModuleNotFoundError` | Run `make install-dev` |
  715. For detailed troubleshooting guides, see **[Troubleshooting Documentation](https://ibm.github.io/mcp-context-forge/manage/troubleshooting/)**.
  716. ---
  717. ## Contributing
  718. 1. Fork the repo, create a feature branch.
  719. 2. Run `make lint` and fix any issues.
  720. 3. Keep `make test` green.
  721. 4. Open a PR with signed commits (`git commit -s`).
  722. See **[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.
  723. ---
  724. ## Changelog
  725. A complete changelog can be found here: [CHANGELOG.md](./CHANGELOG.md)
  726. ## License
  727. Licensed under the **Apache License 2.0** - see [LICENSE](./LICENSE)
  728. ## Star History and Project Activity
  729. [![Star History Chart](https://api.star-history.com/svg?repos=ibm/mcp-context-forge&type=Date)](https://www.star-history.com/#ibm/mcp-context-forge&Date)
  730. <!-- === Usage Stats === -->
  731. [![PyPi Downloads](https://static.pepy.tech/badge/mcp-contextforge-gateway/month)](https://pepy.tech/project/mcp-contextforge-gateway)&nbsp;
  732. [![Stars](https://img.shields.io/github/stars/ibm/mcp-context-forge?style=social)](https://github.com/ibm/mcp-context-forge/stargazers)&nbsp;
  733. [![Forks](https://img.shields.io/github/forks/ibm/mcp-context-forge?style=social)](https://github.com/ibm/mcp-context-forge/network/members)&nbsp;
  734. [![Contributors](https://img.shields.io/github/contributors/ibm/mcp-context-forge)](https://github.com/ibm/mcp-context-forge/graphs/contributors)&nbsp;
  735. [![Last Commit](https://img.shields.io/github/last-commit/ibm/mcp-context-forge)](https://github.com/ibm/mcp-context-forge/commits)&nbsp;
  736. [![Open Issues](https://img.shields.io/github/issues/ibm/mcp-context-forge)](https://github.com/ibm/mcp-context-forge/issues)&nbsp;

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.