Configuration Reference

Configuration Reference

This guide provides comprehensive configuration options for ContextForge, including database setup, environment variables, and deployment-specific settings.

🔐 Required: Change Before Use

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

Copy .env.example to .env and update these values.

!!! warning "Startup Validation" If any required .env variable is missing or invalid, the gateway will fail fast at startup with a validation error via Pydantic.

🔒 Security Defaults (Secure by Default)

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

⚙️ Project Defaults (Dev Setup)

These values in .env.example differ from code defaults to provide a working local/dev setup:

🗄️ Database Configuration

ContextForge supports multiple database backends with full feature parity across all supported systems.

Supported Databases

PostgreSQL System Dependencies

!!! warning "Required: libpq Development Headers" The PostgreSQL adapter (psycopg[c]) requires the libpq development headers to compile. Install them before running pip install .[postgres]:

=== "Debian/Ubuntu"
    ```bash
    sudo apt-get install libpq-dev
    ```

=== "RHEL/CentOS/Fedora"
    ```bash
    sudo dnf install postgresql-devel
    ```

=== "macOS (Homebrew)"
    ```bash
    brew install libpq
    ```

After installing the system dependencies, install the Python package:
```bash
pip install .[postgres]
```

MariaDB/MySQL Setup Details

!!! success "MariaDB & MySQL Full Support" MariaDB and MySQL are fully supported alongside SQLite and PostgreSQL:

- **36+ database tables** work perfectly with MariaDB 10.6+ and MySQL 8.0+
- All **VARCHAR length issues** have been resolved for MariaDB/MySQL compatibility
- Complete feature parity with SQLite and PostgreSQL
- Supports all ContextForge features including federation, caching, and A2A agents

Connection String Format

DATABASE_URL=mysql+pymysql://[username]:[password]@[host]:[port]/[database]

Local MariaDB/MySQL Installation

=== "Ubuntu/Debian (MariaDB)" ```bash # Install MariaDB server sudo apt update && sudo apt install mariadb-server

# Secure installation (optional)
sudo mariadb-secure-installation

# Create database and user
sudo mariadb -e "CREATE DATABASE mcp;"
sudo mariadb -e "CREATE USER 'mysql'@'localhost' IDENTIFIED BY 'changeme';"
sudo mariadb -e "GRANT ALL PRIVILEGES ON mcp.* TO 'mysql'@'localhost';"
sudo mariadb -e "FLUSH PRIVILEGES;"
```

=== "Ubuntu/Debian (MySQL)" ```bash # Install MySQL server sudo apt update && sudo apt install mysql-server

# Secure installation (optional)
sudo mysql_secure_installation

# Create database and user
sudo mysql -e "CREATE DATABASE mcp;"
sudo mysql -e "CREATE USER 'mysql'@'localhost' IDENTIFIED BY 'changeme';"
sudo mysql -e "GRANT ALL PRIVILEGES ON mcp.* TO 'mysql'@'localhost';"
sudo mysql -e "FLUSH PRIVILEGES;"
```

=== "macOS (Homebrew - MariaDB)" ```bash # Install MariaDB brew install mariadb brew services start mariadb

# Create database and user
mariadb -u root -e "CREATE DATABASE mcp;"
mariadb -u root -e "CREATE USER 'mysql'@'localhost' IDENTIFIED BY 'changeme';"
mariadb -u root -e "GRANT ALL PRIVILEGES ON mcp.* TO 'mysql'@'localhost';"
mariadb -u root -e "FLUSH PRIVILEGES;"
```

Docker MariaDB/MySQL Setup

# Start MariaDB container (recommended)
docker run -d --name mariadb-mcp \
  -e MYSQL_ROOT_PASSWORD=mysecretpassword \
  -e MYSQL_DATABASE=mcp \
  -e MYSQL_USER=mysql \
  -e MYSQL_PASSWORD=changeme \
  -p 3306:3306 \
  registry.redhat.io/rhel9/mariadb-106:12.0.2-ubi10

# Or start MySQL container
docker run -d --name mysql-mcp \
  -e MYSQL_ROOT_PASSWORD=mysecretpassword \
  -e MYSQL_DATABASE=mcp \
  -e MYSQL_USER=mysql \
  -e MYSQL_PASSWORD=changeme \
  -p 3306:3306 \
  mysql:8

# Connection string for ContextForge (same for both)
DATABASE_URL=mysql+pymysql://mysql:changeme@localhost:3306/mcp

🔧 Environment Variables Reference

Basic Settings

!!! tip "Subpath Deployment" Use APP_ROOT_PATH=/foo if reverse-proxying under a subpath like https://host.com/foo/.

Authentication

!!! warning "Query Parameter Authentication (INSECURE)" The INSECURE_ALLOW_QUERYPARAM_AUTH setting enables API key authentication via URL query parameters. This is inherently insecure (CWE-598) as API keys may appear in proxy logs, browser history, and server access logs. Only enable this when the upstream MCP server (e.g., Tavily) requires this authentication method. Always configure INSECURE_QUERYPARAM_AUTH_ALLOWED_HOSTS to restrict which hosts can use this feature.

!!! info "Basic Authentication" Basic Authentication is DISABLED by default for security. BASIC_AUTH_USER/PASSWORD are only used when Basic auth is explicitly enabled:

- `API_ALLOW_BASIC_AUTH=true` - Enable for API endpoints (e.g., `/api/metrics/*`)
- `DOCS_ALLOW_BASIC_AUTH=true` - Enable for docs endpoints (`/docs`, `/redoc`)

**Recommended:** Use JWT tokens instead of Basic auth:
```bash
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token ...)
curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/api/...
```

!!! tip "JWT Token Generation" JWT_SECRET_KEY is used to sign JSON Web Tokens. Generate tokens via: bash export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin@example.com --exp 10080 --secret my-test-key)

UI Features

For detailed guidance on embedding and section customization, see Admin UI Customization.

!!! note "Per-Request UI Hiding" For embedded contexts, you can also hide UI sections per-request by adding ?ui_hide=... to the Admin UI URL.

Example:
```text
/admin/?ui_hide=prompts,resources,teams
```

The query value is stored in an HttpOnly cookie with a 30-day lifetime. Clear it by visiting:
```text
/admin/?ui_hide=
```

!!! tip "Production Settings" Set both UI and Admin API to false to disable management UI and APIs in production.

A2A (Agent-to-Agent) Features

Configuration Effects:

• MCPGATEWAY_A2A_ENABLED=false: Completely disables A2A features (API endpoints return 404, admin tab hidden)
• MCPGATEWAY_A2A_METRICS_ENABLED=false: Disables metrics collection while keeping functionality

Direct Proxy Mode

Configuration Effects:

• MCPGATEWAY_DIRECT_PROXY_ENABLED=false (default): Gateways cannot use gateway_mode=direct_proxy; existing ones fall back to cache mode
• MCPGATEWAY_DIRECT_PROXY_ENABLED=true: Enables pass-through MCP operations bypassing the caching layer

Usage: Register a gateway with "gateway_mode": "direct_proxy", then send requests with the X-Context-Forge-Gateway-Id header set to the gateway's ID. All MCP operations (tools/list, tools/call, resources/list, resources/read) will be proxied directly to the remote server.

ToolOps

ToolOps streamlines the entire workflow by enabling seamless tool enrichment, automated test case generation, and comprehensive tool validation.

LLM Chat MCP Client

The LLM Chat MCP Client allows you to interact with MCP servers using conversational AI from multiple LLM providers.

Azure OpenAI Configuration:

OpenAI Configuration:

Anthropic Claude Configuration:

AWS Bedrock Configuration:

IBM WatsonX AI Configuration:

Ollama Configuration:

Provider Requirements:

• Azure OpenAI: Requires AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, and AZURE_OPENAI_DEPLOYMENT
• OpenAI: Requires OPENAI_API_KEY
• Anthropic: Requires ANTHROPIC_API_KEY and pip install langchain-anthropic
• AWS Bedrock: Requires AWS_BEDROCK_MODEL_ID and pip install langchain-aws boto3. Uses AWS credential chain if explicit credentials not provided.
• IBM WatsonX AI: Requires WATSONX_URL, WATSONX_APIKEY, WATSONX_PROJECT_ID, WATSONX_MODEL_ID and pip install langchain-ibm
• Ollama: Requires local Ollama instance running (default: http://localhost:11434)

Redis Configurations for Chat Sessions:

LLM Settings (Internal API)

The LLM Settings feature enables ContextForge to act as a unified LLM provider with an OpenAI-compatible API.

Gateway Provider Settings:

API Endpoints:

# List available models
curl -H "Authorization: Bearer $TOKEN" http://localhost:4444/v1/models

# Chat completion
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}' \
  http://localhost:4444/v1/chat/completions

Email-Based Authentication & User Management

When PASSWORD_RESET_ENABLED=false, self-service forgot/reset endpoints are disabled (403 on API and disabled/redirected UI flows). When SMTP_ENABLED=false, reset requests are accepted but no email is delivered.

MCP Client Authentication

!!! warning "MCP Access Control Dependencies" Full MCP access control (visibility + team scoping + membership validation) requires MCP_CLIENT_AUTH_ENABLED=true with valid JWT tokens containing team claims. When MCP_CLIENT_AUTH_ENABLED=false, access control relies on MCP_REQUIRE_AUTH plus tool/resource visibility only—team membership validation is skipped since there's no JWT to extract teams from.

SSO (Single Sign-On) Configuration

GitHub OAuth:

Google OAuth:

IBM Security Verify OIDC:

Keycloak OIDC:

Microsoft Entra ID OIDC:

Generic OIDC Provider (Auth0, Authentik, etc.):

…(truncated)