mcp-context-forge

Supports Mcp

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.

# UV (faster)
uv venv && source .venv/bin/activate
uv pip install -e '.[dev]'

# pip
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Install the psycopg driver for PostgreSQL:

# Install system dependencies first
# Debian/Ubuntu: sudo apt-get install libpq-dev
# macOS: brew install libpq

uv pip install 'psycopg[binary]'   # dev (pre-built wheels)
# or: uv pip install 'psycopg[c]'  # production (requires compiler)

Connection URL format:

DATABASE_URL=postgresql+psycopg://user:password@localhost:5432/mcp

Quick Postgres container:

docker run --name mcp-postgres \
  -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_DB=mcp -p 5432:5432 -d postgres

⚠️ 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.

🔐 Required: Change Before Use

These variables have insecure defaults and must be changed before production deployment:

🔒 Security Defaults (Secure by Default)

These settings are enabled by default for security—only disable for backward compatibility:

🛡️ Content Security

Content size limits prevent DoS attacks and ensure system stability:

Note: Size limits apply only to new create/update operations. Existing content is not retroactively validated.

🌐 UAID Cross-Gateway Routing Security

UAID Security Configuration

Production Requirements:

Cross-gateway UAID routing requires explicit security configuration:

1. Configure Domain Allowlist:

   UAID_ALLOWED_DOMAINS=["gateway1.example.com", "gateway2.example.com"]
   

2. Ensure JWT Trust:

   • Both gateways must trust the same JWT issuer
   • Option A: Shared secret (same JWT_SECRET_KEY on all gateways)
   • Option B: Federated SSO (Google, GitHub, Entra ID)

3. Enable Authentication:

   AUTH_REQUIRED=true
   UAID_FORWARD_AUTH=true
   

Authentication Flow:

Cross-gateway calls forward the user's bearer token via the Authorization header. Remote gateways validate tokens through existing auth middleware, preserving RBAC context.

Security Features:

• ✅ Fail-closed default: Empty allowlist blocks all cross-gateway routing
• ✅ Bearer token forwarding: User authentication preserved across hops
• ✅ Audit trail: Source gateway and user tracked in headers
• ✅ Clear error messages: Misconfigurations caught at startup and runtime

Troubleshooting:

• "UAID_ALLOWED_DOMAINS not configured" error: Add trusted domains to allowlist in .env
• 401/403 from remote gateway: Verify both gateways trust same JWT issuer
• "proceeding without authentication token" warning: Check auth middleware extracts token to request.state.bearer_token

For detailed security architecture, see docs/security/uaid-cross-gateway-auth.md.

⚙️ Project Defaults (Dev Setup)

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

📚 Full Configuration Reference

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