[QUICK-START]: 5-Minute Setup & First Steps

[crivetimihai]

Get MCP Context Forge running and make your first API call. Choose your path below.

---

Prerequisites

Requirement	Version	Check	Notes
Python	3.10+ (3.12 recommended)	python3 --version	Required for all paths
uv	Latest	uv --version	Path 1 (uvx) or local dev
Docker	20.10+	docker --version	Paths 2-3
make	Any	make --version	Path 5 (local dev)
git	Any	git --version	Paths 3, 5
curl + jq	Any	curl --version && jq --version	API testing

Platform Notes: See Platform-Specific Considerations for Windows, macOS, and architecture details.

---

Path 1: uvx One-Liner (Fastest)

No installation required - runs directly from PyPI using uv:

# Single command - starts gateway on port 4444
BASIC_AUTH_PASSWORD=changeme \
JWT_SECRET_KEY=your-secret-key-at-least-32-characters \
MCPGATEWAY_UI_ENABLED=true \
MCPGATEWAY_ADMIN_API_ENABLED=true \
PLATFORM_ADMIN_EMAIL=admin@example.com \
PLATFORM_ADMIN_PASSWORD=SecurePass123 \
PLATFORM_ADMIN_FULL_NAME="Admin User" \
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

Access:

• Admin UI: http://localhost:4444/admin (login: admin@example.com / SecurePass123)
• API Docs: http://localhost:4444/docs (requires JWT token)

---

Path 2: Docker (Single Container)

docker run -d --name mcpgateway \
  -p 4444:4444 \
  -e HOST=0.0.0.0 \
  -e MCPGATEWAY_UI_ENABLED=true \
  -e MCPGATEWAY_ADMIN_API_ENABLED=true \
  -e BASIC_AUTH_USER=admin \
  -e BASIC_AUTH_PASSWORD=changeme \
  -e JWT_SECRET_KEY=your-secret-key-at-least-32-characters \
  -e PLATFORM_ADMIN_EMAIL=admin@example.com \
  -e PLATFORM_ADMIN_PASSWORD=SecurePass123 \
  -e PLATFORM_ADMIN_FULL_NAME="Admin User" \
  -e SECURE_COOKIES=false \
  ghcr.io/ibm/mcp-context-forge:1.0.0-BETA-2

# View logs
docker logs -f mcpgateway

Note: Use SECURE_COOKIES=false when not using HTTPS.

---

Path 3: Docker Compose (Recommended for Production)

Get gateway + MariaDB + Redis + Nginx proxy in one command:

git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge
docker compose up -d

# Check status
docker compose ps

# View logs
docker compose logs -f gateway

# Generate API token
docker compose exec gateway python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@example.com --exp 10080 --secret my-test-key

Access via Nginx proxy:

• Admin UI: http://localhost:8080/admin (login: admin@example.com / changeme)
• API: http://localhost:8080

Note: Docker Compose routes through Nginx on port 8080. For direct gateway access, uncomment the ports section in docker-compose.yml.

---

Path 4: Helm (Recommended for Production)

For Kubernetes deployments with HA, auto-scaling, and enterprise features, see charts/README.md.

---

Path 5: Local Development (Makefile)

For contributors and developers working with the source code:

# Clone the repository
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge

# Setup environment (creates venv, installs deps, validates .env)
cp .env.example .env
make venv install-dev check-env

# Start dev server with auto-reload on port 8000
make dev

# Or start production server on port 4444
make serve

Key Makefile Targets:

Target	Description
make help	Show all 400+ available targets
make venv	Create virtual environment with uv
make install-dev	Install with development dependencies
make dev	Dev server with auto-reload (port 8000)
make serve	Production Gunicorn server (port 4444)
make test	Run unit tests with pytest
make coverage	Run tests with coverage report
make lint	Run full linting suite
make compose-up	Start Docker Compose stack
make compose-down	Stop Docker Compose stack
make docker	Build Docker image
make docker-run	Run Docker container
make smoketest	Build, deploy, and test endpoints

Code Quality Workflow:

# After writing code - auto-format
make autoflake isort black pre-commit

# Before committing - validate
make flake8 bandit pylint verify

---

Your First API Call

Step 1: Get an API Token

Option A: Login endpoint (production)

# Login and get token
TOKEN=$(curl -s -X POST http://localhost:4444/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "SecurePass123"}' \
  | jq -r '.access_token')

echo "Token: ${TOKEN:0:50}..."

Option B: CLI tool (development only)

# Generate token directly (use your JWT_SECRET_KEY)
TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@example.com \
  --exp 10080 \
  --secret your-secret-key-at-least-32-characters)

# For Docker:
TOKEN=$(docker exec mcpgateway python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@example.com \
  --exp 10080 \
  --secret your-secret-key-at-least-32-characters)

Step 2: Test the API

# Check version
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:4444/version | jq

# List registered tools
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:4444/tools | jq

# List virtual servers
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:4444/servers | jq

---

Connect Claude Desktop

Add to your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "contextforge": {
      "command": "python3",
      "args": ["-m", "mcpgateway.wrapper"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:4444/servers/YOUR_SERVER_UUID",
        "MCP_AUTH": "Bearer YOUR_TOKEN_HERE",
        "MCP_TOOL_CALL_TIMEOUT": "120"
      }
    }
  }
}

Steps:

1. Create a virtual server in Admin UI or via API
2. Copy the server UUID from the servers list
3. Generate a long-lived token (e.g., --exp 0 for no expiry)
4. Replace YOUR_SERVER_UUID and YOUR_TOKEN_HERE
5. Restart Claude Desktop

---

Essential Environment Variables

Variable	Required	Description	Example
BASIC_AUTH_PASSWORD	Yes	API docs password (when enabled)	changeme
JWT_SECRET_KEY	Yes	Token signing key (32+ chars)	your-secret-key...
MCPGATEWAY_UI_ENABLED	Yes	Enable Admin UI	true
MCPGATEWAY_ADMIN_API_ENABLED	Yes	Enable Admin API	true
PLATFORM_ADMIN_EMAIL	Yes	Bootstrap admin email	admin@example.com
PLATFORM_ADMIN_PASSWORD	Yes	Bootstrap admin password	SecurePass123
PLATFORM_ADMIN_FULL_NAME	Yes	Bootstrap admin name	Admin User
DATABASE_URL	No	Database connection	sqlite:///./mcp.db
SECURE_COOKIES	No	Set false for HTTP	true

For all 300+ options, see .env.example.

---

Common Issues & Quick Fixes

macOS: SQLite "disk I/O error"

Cause: iCloud sync or cloud-synced folders interfere with SQLite locking.

Fix:

# Use a local path outside iCloud
mkdir -p "$HOME/mcp-context-forge/data"
export DATABASE_URL="sqlite:////Users/$USER/mcp-context-forge/data/mcp.db"

WSL2: Can't access from Windows browser

Cause: WSL2 NAT layer doesn't forward IPv4 properly.

Fix: Use the WSL IP instead of localhost:

# Get WSL IP
ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}'
# Use that IP in browser: http://172.x.x.x:4444/admin

"Not authenticated" errors

Cause: Token expired or wrong secret key.

Fix:

1. Regenerate token with correct --secret matching JWT_SECRET_KEY
2. For API calls, use Bearer token (not Basic Auth)
3. Admin UI uses email/password login (PLATFORM_ADMIN_EMAIL/PASSWORD)

Gateway exits immediately

Cause: Missing required environment variables.

Fix:

# Copy and edit the example env file
cp .env.example .env
# Edit .env with your values

---

Platform-Specific Considerations

Supported Architectures

Architecture	Container	Local Dev	Notes
amd64 (x86_64)	✅	✅	Full support
arm64 (aarch64)	✅	✅	Apple Silicon, AWS Graviton
s390x	✅	⚠️	IBM Z mainframe (container only recommended)
ppc64le	✅	⚠️	IBM POWER (container only recommended)

Multi-arch builds: Use make container-build-multi to build for all platforms.

macOS

Apple Silicon (M1/M2/M3):

• Local development works natively with ARM64
• Docker Desktop uses Rosetta for x86_64 images (slower)
• Use make podman or make docker for native ARM64 container builds
• The production UBI9 image runs under emulation on Apple Silicon

SQLite Issues:

• Avoid cloud-synced folders (iCloud, Dropbox) for database files
• Use DATABASE_URL=sqlite:////Users/$USER/local-folder/mcp.db
• Consider brew install sqlite3 && brew link --force sqlite3 if version conflicts occur

Homebrew Setup:

brew install python@3.12 uv git make curl jq

Windows

Native Windows (PowerShell):

# Install with winget or chocolatey
winget install Python.Python.3.12
winget install astral-sh.uv
winget install Docker.DockerDesktop

# Set environment variables
$env:JWT_SECRET_KEY = "your-secret-key-at-least-32-characters"
$env:PLATFORM_ADMIN_EMAIL = "admin@example.com"
$env:PLATFORM_ADMIN_PASSWORD = "SecurePass123"

# Run with uvx
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

WSL2 (Recommended for full Makefile support):

# Inside WSL2 Ubuntu
sudo apt update && sudo apt install -y python3.12 python3.12-venv make git curl jq

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Docker (or use Docker Desktop with WSL2 backend)
# See: scripts/ubuntu-contextforge-setup-script.sh

# Access from Windows browser using WSL IP
ip addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}'
# Use http://<WSL_IP>:4444/admin

WSL2 Tip: The Makefile and shell scripts work best in WSL2. Native Windows lacks make by default.

Linux

Ubuntu/Debian:

sudo apt update && sudo apt install -y python3.12 python3.12-venv make git curl jq
curl -LsSf https://astral.sh/uv/install.sh | sh

RHEL/Fedora:

sudo dnf install -y python3.12 make git curl jq
curl -LsSf https://astral.sh/uv/install.sh | sh

Automated Ubuntu Setup:

# Full setup script (Docker, git, make, uv, clone, configure)
curl -sSL https://raw.githubusercontent.com/IBM/mcp-context-forge/main/scripts/ubuntu-contextforge-setup-script.sh | bash

---

Customize Your Catalog

Edit mcp-catalog.yml to define which MCP servers appear in your catalog:

catalog_servers:
  - id: my-server
    name: "My Custom Server"
    category: "Custom"
    url: "http://localhost:9000/sse"
    auth_type: "none"
    description: "My custom MCP server"
    tags: ["custom"]

The catalog includes 80+ pre-configured public MCP servers (Asana, Linear, Notion, GitHub, Slack, etc.) ready to add via the Admin UI.

---

Next Steps

Action	Link
Register an MCP Server	mcpgateway.translate Guide
Connect Clients	Client Integrations
Set up SSO	SSO Configuration
Configure RBAC	Access Control Guide
Deploy to Kubernetes	charts/README.md
Full Documentation	ibm.github.io/mcp-context-forge
FAQ	Frequently Asked Questions

---

Get Involved

Action	Link
File an Issue	[README-FIRST]: Project Backlog & Issue Guide #2502
Contribute Code	CONTRIBUTING.md
Ask Questions	GitHub Discussions
Join the Community	ContextForge Discord

---

Quick Reference

Gateway Startup

# uvx (no install) - add required env vars before command
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

# pip install
pip install mcp-contextforge-gateway
mcpgateway --host 0.0.0.0 --port 4444

# Docker single container
docker run -d --name mcpgateway -p 4444:4444 \
  -e MCPGATEWAY_UI_ENABLED=true -e MCPGATEWAY_ADMIN_API_ENABLED=true \
  -e BASIC_AUTH_PASSWORD=changeme -e JWT_SECRET_KEY=your-32-char-secret \
  -e PLATFORM_ADMIN_EMAIL=admin@example.com -e PLATFORM_ADMIN_PASSWORD=SecurePass123 \
  -e SECURE_COOKIES=false ghcr.io/ibm/mcp-context-forge:1.0.0-BETA-2

# Makefile (local dev)
make dev       # Dev server on :8000
make serve     # Production on :4444

API Commands

# Generate token
python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret YOUR_SECRET

# Test API
curl -H "Authorization: Bearer $TOKEN" http://localhost:4444/version

Makefile Essentials

# Setup
make venv install-dev check-env    # Full dev environment setup
make compose-up                    # Docker Compose stack

# Development
make dev                           # Auto-reload dev server
make test                          # Run pytest
make coverage                      # Tests with coverage report
make lint                          # Full linting suite

# Containers
make docker                        # Build image
make docker-prod                   # Build production image (not macOS)
make docker-run                    # Run container
make compose-up                    # Start full stack
make compose-down                  # Stop stack
make compose-logs                  # Tail logs

# Stacks
make testing-up                    # Start test server stack
make monitoring-up                 # Start Prometheus + Grafana

# Code Quality
make autoflake isort black         # Auto-format
make flake8 bandit pylint          # Validate
make verify                        # Full package verification

# Cleanup
make stop                          # Stop all servers
make clean                         # Remove caches, venv, build artifacts
docker stop mcpgateway && docker rm mcpgateway  # Stop container

Makefile Categories (400+ targets)

Run make help for the full list. Key categories:

Category	Examples
Serve	dev, serve, serve-ssl, stop
Testing	test, coverage, smoketest, test-ui, testing-up
Linting	lint, black, isort, mypy, bandit
Containers	docker, docker-prod, podman, compose-*, container-*
Stacks	compose-up, testing-up, monitoring-up, benchmark-up
Database	db-migrate, db-upgrade, db-reset
Security	security-scan, trivy, grype-scan, pip-audit
Docs	docs, images, scc-report
Helm	helm-lint, helm-package, helm-deploy
Load Test	load-test, load-test-ui, generate-*

---

Client Examples / Using ContextForge

In ContextForge, create a Virtual Server, and click on Export Config. Some clients include:

• https://modelcontextprotocol.io/docs/tools/inspector
• Visual Studio Code - Copilot

Last updated: January 2025 | Version: 1.0.0-BETA-2

[oaslananka]

I’ll take this issue and submit a PR.

[oaslananka]

PR opened: #2686. Adds docs/QUICKSTART.md and updates README 5-Minute Setup link. Checks (DCO) are green.