mcp-context-forge

Quick Start - PyPI

ContextForge is published on PyPI 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:

---

### 1 - Install & run (copy-paste friendly)

```bash

---

# 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

---

# 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

---

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

---

# 1️⃣  Spin up the sample MCP time server using mcpgateway.translate & docker (replace docker with podman if needed)
python3 -m mcpgateway.translate \
     --stdio "docker run --rm -i ghcr.io/ibm/fast-time-server:latest -transport=stdio" \
     --expose-sse \
     --port 8003

---

## Quick Start - Containers

Use the official OCI image from GHCR with **Docker** *or* **Podman**.
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.

---

### 🚀 Quick Start - Docker Compose

> **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).
>
> You also **must** have a `.env` file with real secrets before running `docker compose up -d`. The gateway will not start with placeholder values.

Get a full stack running with PostgreSQL and Redis:

```bash

---

### ☸️ Quick Start - Helm (Kubernetes)

Deploy to Kubernetes with enterprise-grade features:

```bash

---

# Check deployment status
kubectl get pods -l app.kubernetes.io/name=mcp-context-forge

---

### 🐳 Docker (Single Container)

```bash

---

# JWT_SECRET_KEY must be set — see "Docker (Single Container)" for how to generate it
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@example.com --exp 10080 --secret "${JWT_SECRET_KEY}")
export MCP_AUTH="Bearer ${MCPGATEWAY_BEARER_TOKEN}"
export MCP_SERVER_URL='http://localhost:4444/servers/UUID_OF_SERVER_1/mcp'
export MCP_TOOL_CALL_TIMEOUT=120
export MCP_WRAPPER_LOG_LEVEL=DEBUG  # or OFF to disable logging

docker run --rm -i \
  -e MCP_AUTH="${MCP_AUTH}" \
  -e MCP_SERVER_URL=http://host.docker.internal:4444/servers/UUID_OF_SERVER_1/mcp \
  -e MCP_TOOL_CALL_TIMEOUT=120 \
  -e MCP_WRAPPER_LOG_LEVEL=DEBUG \
  ghcr.io/ibm/mcp-context-forge:latest \
  python3 -m mcpgateway.wrapper

Quick Start: VS Code Dev Container

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.

For detailed setup, workflows, and GitHub Codespaces instructions, see Developer Onboarding.

Installation

make venv install-dev      # create .venv + install deps + build Admin UI
make serve                 # gunicorn on :4444

Rust workspace note