mcp-context-forge MCP工具

Install system dependencies first

or: uv pip install 'psycopg[c]' # production (requires compiler)

Connection URL format:

Quick Postgres container:

</details>

---

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 - 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

Pull pre-built images from GHCR (avoids local build entirely)

docker pull ghcr.io/ibm/mcp-context-forge:latest echo 'IMAGE_LOCAL=ghcr.io/ibm/mcp-context-forge:latest' >> .env

Build only the nginx image (small, local-only, builds in seconds)

docker compose build nginx

Install with PostgreSQL (default)

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 ```

</details>

---

Installation

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

Rust workspace note: - Workspace-owned Rust crates live under crates/ and are picked up by the root Cargo.toml via crates/*. - Run cargo build, cargo test, and cargo check from the repo root to cover the shared workspace. - make venv install-dev creates the root .venv, which is also reused by the workspace's PyO3/maturin builds.

<details> <summary><strong>Alternative: UV or pip</strong></summary>

```bash

Debian/Ubuntu: sudo apt-get install libpq-dev

macOS: brew install libpq

uv pip install 'psycopg[binary]' # dev (pre-built wheels)

⚙️ Project Defaults (Dev Setup)

These values differ from code defaults to provide a working local/dev setup:

Docker Compose (Full Stack)

make compose-up          # Start full stack: PostgreSQL, Redis, 3 gateway replicas, Nginx on :8080
make compose-sso         # Start SSO stack with Keycloak on :8180
make sso-test-login      # Run SSO smoke checks (providers + login URL + test users)
make compose-logs        # Tail logs from all services
make compose-down        # Stop the stack

Cloud Deployment

ContextForge can be deployed to any major cloud platform:

For comprehensive deployment guides, see Deployment Documentation.

---

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:

```bash

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

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

Example curl

curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \ -H "Content-Type: application/json" \ -d '{"server":{"name":"time_server","description":"Fast time tools","associated_tools":["6018ca46d32a4ac6b4c054c13a1726a2"]}}' \ http://localhost:4444/servers | jq

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 - Helm (Kubernetes)

Deploy to Kubernetes with enterprise-grade features:

```bash

1️⃣ Generate secure secrets (creates .env.secrets)

python3 -m mcpgateway.scripts.init_secrets

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

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

2️⃣ Set up .env with real secrets AND pull the pre-built images

cp .env.example .env python3 -m mcpgateway.scripts.init_secrets --patch-env .env

.env now has strong JWT_SECRET_KEY and AUTH_ENCRYPTION_SECRET

Login: PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD (from .env)

Generate API token (reads JWT_SECRET_KEY from the pod's environment)

kubectl exec deployment/mcp-gateway-mcp-context-forge -- \ python3 -m mcpgateway.utils.create_jwt_token \ --username admin@yourcompany.com --exp 10080 --secret "${JWT_SECRET}" ```

SSRF note: Helm defaults to strict SSRF settings (SSRF_ALLOW_PRIVATE_NETWORKS=false). If you register in-cluster tool URLs, allow only your cluster CIDRs via mcpContextForge.config.SSRF_ALLOWED_NETWORKS or, for local-only benchmark setups, temporarily set SSRF_ALLOW_PRIVATE_NETWORKS=true. See docs/docs/manage/configuration.md#ssrf-protection and docs/docs/deployment/helm.md.

Enterprise Features: - 🔄 Auto-scaling - HPA with CPU/memory targets - 🗄️ Database Choice - PostgreSQL (prod), SQLite (dev) - 📊 Observability - Prometheus metrics, OpenTelemetry tracing - 🔒 Security - RBAC, network policies, secret management - 🚀 High Availability - Multi-replica deployments with Redis clustering - 📈 Monitoring - Built-in Grafana dashboards and alerting

---

Generate secrets first (creates .env.secrets)

python3 -m mcpgateway.scripts.init_secrets 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)"

docker run -d --name mcpgateway \ -p 4444:4444 \ -e MCPGATEWAY_UI_ENABLED=true \ -e MCPGATEWAY_ADMIN_API_ENABLED=true \ -e HOST=0.0.0.0 \ -e JWT_SECRET_KEY="${JWT_SECRET_KEY}" \ -e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \ -e AUTH_REQUIRED=true \ -e PLATFORM_ADMIN_EMAIL=admin@example.com \ -e PLATFORM_ADMIN_PASSWORD=<strong-password> \ -e PLATFORM_ADMIN_FULL_NAME="Platform Administrator" \ -e DATABASE_URL=sqlite:///./mcp.db \ -e SECURE_COOKIES=false \ ghcr.io/ibm/mcp-context-forge:latest

Configuration

⚠️ If any required .env variable is missing or invalid, the gateway will fail fast at startup with a validation error via Pydantic.

Copy the provided .env.example to .env and update the security-sensitive values below.

📚 Full Configuration Reference

For the complete list of 300+ environment variables organized by category (authentication, caching, SSO, observability, etc.), see the Configuration Reference.

---

Read JWT_SECRET_KEY from your .env (it must already contain a real secret)

export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)

Now accessible via both /sse (SSE) and /mcp (streamable HTTP) endpoints

6️⃣ Client HTTP endpoint. Inspect it interactively with the MCP Inspector CLI (or use any MCP client)

npx -y @modelcontextprotocol/inspector

7️⃣ Generate an API token

export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2) docker compose exec gateway python3 -m mcpgateway.utils.create_jwt_token \ --username admin@example.com --exp 10080 --secret "$JWT_SECRET_KEY"

**What you get:**
- 🗄️ **PostgreSQL** - Production-ready database with 55+ tables
- 🚀 **ContextForge** - Full-featured gateway with Admin UI
- 📊 **Redis** - High-performance caching and session storage
- 🔧 **Admin Tools** - pgAdmin, Redis Insight for database management
- 🌐 **Nginx Proxy** - Caching reverse proxy on port 8080

**Enable HTTPS (optional):**

Generate API token (using the same secret)

docker run --rm -it \ -e JWT_SECRET_KEY="${JWT_SECRET_KEY}" \ ghcr.io/ibm/mcp-context-forge:latest \ python3 -m mcpgateway.utils.create_jwt_token \ --username admin@example.com --exp 10080 --secret "${JWT_SECRET_KEY}"

Browse to **[http://localhost:4444/admin](http://localhost:4444/admin)** and login with `PLATFORM_ADMIN_EMAIL` / `PLATFORM_ADMIN_PASSWORD`.

<details>
<summary><strong>Advanced: Persistent storage, host networking, airgapped</strong></summary>

**Persist SQLite database:**

**Host networking** (access local MCP servers):

**Airgapped deployment** (no internet):

</details>

---

Quick Reference

API Reference

Interactive API documentation is available when the server is running:

• Swagger UI — Try API calls directly in your browser
• ReDoc — Browse the complete endpoint reference

Quick Authentication: ```bash

Test API access

curl -H "Authorization: Bearer $TOKEN" http://localhost:4444/health ```

For comprehensive curl examples covering all endpoints, see the API Usage Guide.

---

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.

---

Troubleshooting

Common issues and solutions:

For detailed troubleshooting guides, see Troubleshooting Documentation.

---