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️⃣ Isolated env + 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 GO 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

cd mcp-servers/go/fast-time-server; make build

🚀 Quick Start - Docker Compose

Get a full stack running with PostgreSQL and Redis in under 30 seconds:

```bash

Install with PostgreSQL (default)

helm install mcp-gateway . \ --set mcpContextForge.secret.PLATFORM_ADMIN_EMAIL=admin@yourcompany.com \ --set mcpContextForge.secret.PLATFORM_ADMIN_PASSWORD=changeme \ --set mcpContextForge.secret.JWT_SECRET_KEY=your-secret-key

Check deployment status

kubectl get pods -l app.kubernetes.io/name=mcp-context-forge

🐳 Docker (Single Container)

```bash 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=my-test-key-but-now-longer-than-32-bytes \ -e AUTH_REQUIRED=true \ -e PLATFORM_ADMIN_EMAIL=admin@example.com \ -e PLATFORM_ADMIN_PASSWORD=changeme \ -e PLATFORM_ADMIN_FULL_NAME="Platform Administrator" \ -e DATABASE_URL=sqlite:///./mcp.db \ -e SECURE_COOKIES=false \ ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3

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. - Rust sample servers under mcp-servers/rust/ are usually managed separately; workspace-owned ones are listed explicitly in the root Cargo.toml. - 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.

---

TLDR;: (single command using uv)

```bash

Quick start with environment variables

BASIC_AUTH_PASSWORD=pass \ MCPGATEWAY_UI_ENABLED=true \ MCPGATEWAY_ADMIN_API_ENABLED=true \ PLATFORM_ADMIN_EMAIL=admin@example.com \ PLATFORM_ADMIN_PASSWORD=changeme \ PLATFORM_ADMIN_FULL_NAME="Platform Administrator" \ uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

Or better: use the provided .env.example

cp .env.example .env

Download the example environment file

curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example cp .env.example .env

Download the example environment file

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

Edit .env to customize your settings

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>

2️⃣ Copy and customize the configuration

Edit .env to customize your settings (especially passwords!)

Or set environment variables directly:

export MCPGATEWAY_UI_ENABLED=true export MCPGATEWAY_ADMIN_API_ENABLED=true export PLATFORM_ADMIN_EMAIL=admin@example.com export PLATFORM_ADMIN_PASSWORD=changeme export PLATFORM_ADMIN_FULL_NAME="Platform Administrator"

BASIC_AUTH_PASSWORD=pass JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \ mcpgateway --host 0.0.0.0 --port 4444 & # admin/pass

2️⃣ Copy and customize the configuration

Edit .env to customize your settings

Or set environment variables (session-only)

$Env:MCPGATEWAY_UI_ENABLED = "true" $Env:MCPGATEWAY_ADMIN_API_ENABLED = "true"

Optional: background it

Set environment variables

export 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) 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:1.0.0-RC-3 \ python3 -m mcpgateway.wrapper ```

</details>

---

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.

---

3️⃣ Generate a bearer token & smoke-test the API

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

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>

Note: Basic auth for API is disabled by default (API_ALLOW_BASIC_AUTH=false)

$Env:JWT_SECRET_KEY = "my-test-key-but-now-longer-than-32-bytes" $Env:PLATFORM_ADMIN_EMAIL = "admin@example.com" $Env:PLATFORM_ADMIN_PASSWORD = "changeme" $Env:PLATFORM_ADMIN_FULL_NAME = "Platform Administrator"

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

Generate API token

docker compose exec gateway python3 -m mcpgateway.utils.create_jwt_token \ --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes

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

kubectl exec deployment/mcp-gateway-mcp-context-forge -- \ python3 -m mcpgateway.utils.create_jwt_token \ --username admin@yourcompany.com --exp 10080 --secret your-secret-key ```

SSRF note: Helm defaults to strict SSRF settings (SSRF_ALLOW_PRIVATE_NETWORKS=false). If you register in-cluster tool URLs (for example fast-time or fast-test services), 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

---

Tail logs and generate API key

docker logs -f mcpgateway docker run --rm -it ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3 \ python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key-but-now-longer-than-32-bytes

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.

---

Alternative: running the local binary

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.

---