### Complete Project Setup

Source: https://github.com/ibm/mcp-context-forge/blob/main/CLAUDE.md

Use this command to copy the example environment file and install development dependencies.

```bash
cp .env.example .env && make install-dev check-env
```

--------------------------------

### ContextForge Setup Script Options

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/deployment/compose.md

Examples of using the contextforge-setup.sh script with various options for non-interactive installation, skipping service startup, and providing Docker credentials.

```bash
# Non-interactive install without starting services
./scripts/contextforge-setup.sh -y --skip-start

# Automated install with Docker Hub credentials
DOCKER_USERNAME=myuser DOCKER_PASSWORD=mypass ./scripts/contextforge-setup.sh -y

# Install to custom directory
./scripts/contextforge-setup.sh ~/my-contextforge
```

--------------------------------

### Complete Project Setup

Source: https://github.com/ibm/mcp-context-forge/blob/main/AGENTS.md

Use this command for a full setup, including environment file creation and development dependency installation.

```bash
cp .env.example .env && make install-dev check-env    # Complete setup
```

--------------------------------

### Install uv and Setup Development Environment

Source: https://github.com/ibm/mcp-context-forge/blob/main/DEVELOPING.md

Install the 'uv' package manager and then use 'make' commands to create a virtual environment and install development dependencies.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh

make venv install-dev
```

--------------------------------

### Install and Start Grafana Tempo Backend

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/manage/observability/observability.md

Installs the OTLP exporter backend and starts the Grafana Tempo service using Docker. Tempo utilizes OTLP for trace collection.

```bash
# Install OTLP exporter backend (Tempo uses OTLP)
pip install opentelemetry-exporter-otlp-proto-grpc

# Start Tempo
docker run -d \
  --name tempo \
  -p 4317:4317 \
  -p 3200:3200 \
  grafana/tempo:latest

# Configure environment (uses OTLP)
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_SERVICE_NAME=mcp-gateway
```

--------------------------------

### Project Setup

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/testing/entra-id-e2e.md

Clone the repository and set up the development environment, including creating a virtual environment and installing dependencies.

```bash
git clone <repository-url>
cd mcp-context-forge
make venv install-dev
```

--------------------------------

### Install PyPI Packages with All Plugins

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/architecture/adr/020-multi-format-packaging-strategy.md

Install the ContextForge gateway along with all available plugins using the meta-package. This is useful for comprehensive local setups.

```bash
pip install mcp-contextforge-gateway mcp-contextforge-plugins-all
```

--------------------------------

### Complete Configuration for Production

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/manage/logging-examples.md

Copy .env.example to .env and configure all settings including multitenancy. This example shows the initial setup for a production deployment.

```bash
cp .env.example .env
# Edit .env to set PLATFORM_ADMIN_EMAIL, PLATFORM_ADMIN_PASSWORD, etc.
mcpgateway --host 0.0.0.0 --port 4444
```

--------------------------------

### Install and Start Phoenix Backend

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/manage/observability/observability.md

Installs the Phoenix exporter backend and starts the Phoenix service using Docker. Configure environment variables to point to the Phoenix endpoint.

```bash
# Install Phoenix exporter backend
pip install opentelemetry-exporter-otlp-proto-grpc

# Start Phoenix
docker run -d \
  --name phoenix \
  -p 6006:6006 \
  -p 4317:4317 \
  arizephoenix/phoenix:latest

# Configure environment
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_SERVICE_NAME=mcp-gateway

# View UI at http://localhost:6006
```

--------------------------------

### Install ContextForge Gateway

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/clients/mcp-cli.md

Clone the ContextForge repository and install its dependencies, then start the gateway. The gateway will be accessible at the default address http://localhost:4444.

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

# Install and start the gateway
make venv install serve
# Gateway will be available at http://localhost:4444
```

--------------------------------

### Initial Development Environment Setup

Source: https://github.com/ibm/mcp-context-forge/blob/main/TESTING.md

Sets up the development environment using uv for dependency management and installs development dependencies.

```bash
# Setup with uv (recommended)
make venv install-dev

# Alternative: traditional pip
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,test]"
```

--------------------------------

### Integration with ContextForge: Start server and expose SSE

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/servers/go/fast-time-server.md

This example demonstrates starting the Fast Time Server with the translate module enabled and exposing SSE, then running a Python script for integration.

```bash
#!/bin/bash
# Complete ContextForge integration example

# 1. Start fast-time-server with translate
echo "Starting fast-time-server with translate module..."
python3 -m mcpgateway.translate \
  --stdio "docker run --rm -i ghcr.io/ibm/fast-time-server:0.8.0 -transport=stdio" \
  --expose-sse \
  --port 8003 &
TRANSLATE_PID=$!
sleep 3
```

--------------------------------

### Install and Start Zipkin Backend

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/manage/observability/observability.md

Installs the Zipkin exporter backend and starts the Zipkin service using Docker. Configure environment variables to point to the Zipkin endpoint.

```bash
# Install Zipkin exporter backend
pip install opentelemetry-exporter-zipkin

# Start Zipkin
docker run -d \
  --name zipkin \
  -p 9411:9411 \
  openzipkin/zipkin

# Configure environment
export OTEL_TRACES_EXPORTER=zipkin
export OTEL_EXPORTER_ZIPKIN_ENDPOINT=http://localhost:9411/api/v2/spans
export OTEL_SERVICE_NAME=mcp-gateway

# View UI at http://localhost:9411
```

--------------------------------

### Start the Gateway

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/testing/basic.md

Start the ContextForge gateway using either Podman or a virtual environment. Ensure you have the necessary dependencies installed.

```bash
make podman podman-run-ssl
# or
make venv install serve-ssl
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/ibm/mcp-context-forge/blob/main/README.md

Use these make commands to create a virtual environment, install development dependencies, and build the Admin UI. Then, use 'make serve' to start the Gunicorn server.

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

--------------------------------

### PostgreSQL Adapter Setup

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/index.md

Instructions for installing the 'psycopg' driver for PostgreSQL and the format for the DATABASE_URL connection string.

```bash
# 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)
```

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

--------------------------------

### Copy Example Environment File

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/development/index.md

Copy the example environment file to .env to start configuring the project. This provides a template for setting environment variables.

```bash
cp .env.example .env
```

--------------------------------

### Clone, Install, and Serve

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/best-practices/mcp-best-practices.md

Standard commands to get an MCP repository running locally. Ensure you have a Python virtual environment set up.

```bash
git clone <repository-url>
cd <repository-name>
make venv install serve
```

--------------------------------

### Quick Start with Environment Variables using uvx

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/overview/quick_start.md

Install and run the ContextForge gateway quickly using environment variables and uvx. Ensure JWT_SECRET_KEY is longer than 32 bytes for security.

```bash
JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \
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" \
 הראשונה --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444
```

```bash
curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
cp .env.example .env
# Edit .env to customize your settings
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444
```

--------------------------------

### One-Liner Setup for Development Environment

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/development/building.md

Use this command to create a virtual environment, install development dependencies, and run the gateway using Gunicorn. Recommended for most users.

```bash
make venv install-dev serve
```

--------------------------------

### Complete Example: Virtual Server Creation with Multiple Tools

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/manage/api-usage.md

This example demonstrates a complete workflow for creating a virtual server. It first fetches tool IDs and then uses them to create a server with multiple associated tools.

```bash
# 1. Get tools IDs to associate
TOOLS=$(curl -s -H "Authorization: Bearer $TOKEN" $BASE_URL/tools)
export TOOL1_ID=$(echo $TOOLS | jq -r '.[0].id')
export TOOL2_ID=$(echo $TOOLS | jq -r '.[1].id')

# 2. Create virtual server with multiple gateways
SERVER_RESPONSE=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "server": {
    "name": "my-virtual-server",
    "description": "Composed server with multiple tools",
    "associated_tools": ["'$TOOL1_ID'", "'$TOOL2_ID'"]
    }
  }' \
  $BASE_URL/servers)

export SERVER_ID=$(echo $SERVER_RESPONSE | jq -r '.id')
echo "Server ID: $SERVER_ID"
```

--------------------------------

### Automated Setup Script for Linux

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/deployment/compose.md

This script automates Docker installation, user configuration, and starting the Compose stack on supported Linux distributions. It can be run non-interactively for CI/automation.

```bash
# 1. Create a dedicated user (as root)
useradd -m contextforge && passwd contextforge
usermod -aG wheel contextforge   # RHEL-family
usermod -aG sudo contextforge    # Debian-family

# 2. Switch to the new user
su - contextforge

# 3. Clone the repository and run the setup script
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge
./scripts/contextforge-setup.sh
```

--------------------------------

### One-Liner Setup for Local Deployment

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/deployment/local.md

Use this command to quickly set up a virtual environment, install dependencies, and start the server in development mode. It launches Gunicorn on http://localhost:4444.

```bash
make venv install-dev serve
```

--------------------------------

### Quick Start: Get current time in New York using Docker

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/servers/go/fast-time-server.md

This example shows how to run the Fast Time Server in Docker and retrieve the current time for a specific timezone.

```bash
# 1. Get current time in New York (using Docker)
docker run --rm -p 8080:8080 -d --name time-demo \
  ghcr.io/ibm/fast-time-server:0.8.0 -transport=rest

curl "http://localhost:8080/api/v1/time?timezone=America/New_York"
```

--------------------------------

### Multi-Tenant GitHub Enterprise Setup

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/mcpgateway-translate.md

Starts the mcpgateway translate server with dynamic environment injection for multi-tenant GitHub Enterprise, enabling per-user token authentication. Includes example curl requests for two different users.

```bash
python3 -m mcpgateway.translate \
  --stdio "uvx mcp-server-github" \
  --expose-sse \
  --port 9000 \
  --enable-dynamic-env \
  --header-to-env "Authorization=GITHUB_TOKEN" \
  --header-to-env "X-GitHub-Enterprise-Host=GITHUB_HOST"
```

```bash
curl -X POST http://localhost:9000/message \
  -H "Authorization: Bearer ghp_userA_token123" \
  -H "X-GitHub-Enterprise-Host: github.company.com" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_repositories"}}'
```

```bash
curl -X POST http://localhost:9000/message \
  -H "Authorization: Bearer ghp_userB_token456" \
  -H "X-GitHub-Enterprise-Host: github.company.com" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_repositories"}}'
```

--------------------------------

### Clone and Setup ContextForge

Source: https://github.com/ibm/mcp-context-forge/blob/main/DEVELOPING.md

Clone the repository, navigate into the directory, and set up the development environment using 'uv' and 'make'. This includes copying the environment file, installing dependencies, and checking the environment.

```bash
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge

cp .env.example .env && make venv install-dev check-env

make dev
```

--------------------------------

### Local Development Setup for MCP CLI

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/clients/mcp-cli.md

Configuration steps for setting up mcp-cli to connect to a locally running ContextForge Gateway. Includes starting the gateway and configuring the mcp-cli settings.

```bash
cd mcp-context-forge
make serve  # Starts on http://localhost:4444
```

```json
{
  "mcpServers": {
    "mcpgateway-wrapper": {
      "command": "/path/to/mcp-context-forge/.venv/bin/python",
      "args": ["-m", "mcpgateway.wrapper"],
      "env": {
        "MCP_AUTH": "Bearer <your-jwt-token>",
        "MCP_SERVER_URL": "http://localhost:4444"
      }
    }
  }
}
```

```bash
mcp-cli ping --server mcpgateway-wrapper
```

--------------------------------

### Set Up Development Environment

Source: https://github.com/ibm/mcp-context-forge/blob/main/plugins/toon_encoder/README.md

Clones the ContextForge repository and installs development dependencies using make and uv (or pip).

```bash
# Clone the repo (if not already)
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge

# Create virtual environment and install dependencies
make venv install-dev

# Copy environment template
cp .env.example .env
```

--------------------------------

### Install and Start Jaeger Backend

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/manage/observability/observability.md

Installs the Jaeger exporter backend and starts the Jaeger all-in-one service using Docker. Configure environment variables to point to the Jaeger endpoint.

```bash
# Install Jaeger exporter backend
pip install opentelemetry-exporter-jaeger

# Start Jaeger
docker run -d \
  --name jaeger \
  -p 16686:16686 \
  -p 14268:14268 \
  jaegertracing/all-in-one

# Configure environment
export OTEL_TRACES_EXPORTER=jaeger
export OTEL_EXPORTER_JAEGER_ENDPOINT=http://localhost:14268/api/traces
export OTEL_SERVICE_NAME=mcp-gateway

# View UI at http://localhost:16686
```

--------------------------------

### Set up Development Environment and Run Quality Checks

Source: https://github.com/ibm/mcp-context-forge/blob/main/DEVELOPING.md

Follow these steps to set up the development environment, including creating a virtual environment and installing development dependencies. Run `make verify` to perform quality checks.

```bash
# Set up environment
make venv install-dev

# Run quality checks
make verify
```

--------------------------------

### Install Playwright Browsers

Source: https://github.com/ibm/mcp-context-forge/blob/main/tests/playwright/README.md

Installs the necessary Playwright browsers for testing. Run this command once after initial setup.

```bash
make playwright-install
# OR
make playwright-install-all
```

--------------------------------

### Connect to Monday.com via ContextForge (Python)

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/servers/external/monday/monday-mcp.md

Python example demonstrating how to initialize the MCPGatewayClient and connect to the monday.com server registered in ContextForge. It also shows how to list available tools.

```python
# Python example: Connect to monday.com via ContextForge
import asyncio
from mcp_gateway_client import MCPGatewayClient

async def connect_monday():
    # Initialize gateway client
    gateway = MCPGatewayClient(
        base_url="http://localhost:4444",
        bearer_token=os.getenv("MCPGATEWAY_BEARER_TOKEN")
    )

    # Connect to monday.com server
    await gateway.connect_server("monday-official")

    # List available tools
    tools = await gateway.list_tools("monday-official")
    print(f"Available monday.com tools: {len(tools)}")

    return gateway

# Run connection
gateway = asyncio.run(connect_monday())
```

--------------------------------

### Quick Start with Environment Variables

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/index.md

This snippet shows how to quickly start ContextForge using environment variables for configuration. It's recommended to use a .env file for better management.

```bash
JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes \
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
# Edit .env to customize your settings
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444
```

--------------------------------

### Starting the gRPC Plugin Server

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/plugins/grpc-transport.md

Command to start the plugin server using Python, installing necessary dependencies and setting the configuration path. The `.[grpc]` part in pip install ensures gRPC related extras are included.

```bash
cd plugin-server
pip install -e ".[grpc]"
PLUGINS_CONFIG_PATH=./resources/plugins/config.yaml \
  python -m mcpgateway.plugins.framework.external.grpc.server.runtime
```

--------------------------------

### Build and Serve Documentation

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/development/developer-workstation.md

Build the documentation using MkDocs and serve it locally with live reload. Run 'make venv' once to install dependencies.

```bash
cd docs
make venv          # first run only; installs MkDocs + plugins
make serve         # http://127.0.0.1:8000 with live reload
```

--------------------------------

### Time Operations Examples

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/clients/mcp-cli.md

Examples for getting the current system time and converting time zones using mcp-cli.

```bash
# Get current time
mcp-cli cmd --server mcpgateway-wrapper --tool time-server-get-system-time --raw
```

```bash
# Convert time zones
mcp-cli cmd --server mcpgateway-wrapper --tool time-server-convert-time \
  --tool-args '{"from_timezone":"UTC","to_timezone":"America/New_York","time":"2025-01-01T12:00:00Z"}' --raw
```

--------------------------------

### Launch Wrapper with uv/uvx

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/mcpgateway-wrapper.md

Set up a virtual environment using uv, install the gateway package, and then run the wrapper. This method is optimized for speed.

```bash
uv venv ~/.venv/mcpgw && source ~/.venv/mcpgw/bin/activate
uv pip install mcp-contextforge-gateway
uv python3 -m mcpgateway.wrapper
```

--------------------------------

### Download and Run Static Binary

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/architecture/adr/020-multi-format-packaging-strategy.md

Download a ContextForge static binary (Go server example) from GitHub Releases, make it executable, and run it. This is for edge or environments without a Python runtime.

```bash
curl -LO https://github.com/contextforge-org/mcp-servers-go/releases/download/v1.0.0/mcp-server-time-linux-amd64
chmod +x mcp-server-time-linux-amd64
./mcp-server-time-linux-amd64 --port 9000
```

--------------------------------

### Start Gateway for Development

Source: https://github.com/ibm/mcp-context-forge/blob/main/plugins/content_moderation/TESTING.md

Starts the development gateway with plugins enabled and authentication disabled. This is part of the setup for manual testing.

```bash
cd /Users/mg/mg-work/manav/work/ai-experiments/mcp-context-forge
export PLUGINS_ENABLED=true
export AUTH_REQUIRED=false
make dev
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/ibm/mcp-context-forge/blob/main/charts/mcp-stack/CONTRIBUTING.md

Steps to fork the repository, clone your fork, and navigate to the chart directory. This is the initial setup for development.

```bash
# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/mcp-context-forge.git
cd mcp-context-forge/charts/mcp-stack
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/index.md

Use 'make venv install' to create a virtual environment and install project dependencies. 'make serve' starts the Gunicorn server on port 4444.

```bash
make venv install          # create .venv + install deps
make serve                 # gunicorn on :4444
```

--------------------------------

### Install the output-schema-test-server

Source: https://github.com/ibm/mcp-context-forge/blob/main/mcp-servers/python/output_schema_test_server/TESTING.md

Navigate to the server directory and install the necessary dependencies.

```bash
cd mcp-servers/python/output_schema_test_server
make install
```

--------------------------------

### Install and Run Langflow Server

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/servers/third-party/langflow-server.md

Installs Langflow using pip and starts the server on the specified host and port. Recommended for most users.

```bash
pip install langflow

langflow run --host 0.0.0.0 --port 7860
```

--------------------------------

### Start ContextForge Development Environment

Source: https://github.com/ibm/mcp-context-forge/blob/main/plugins/webhook_notification/TESTING.md

Set environment variables for enabled plugins and configuration file, then start the development server.

```bash
export PLUGINS_ENABLED=true
export PLUGINS_CONFIG_FILE=plugins/config.yaml
make dev
```

--------------------------------

### Start SSO Profile with Keycloak

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/deployment/compose.md

Use this make target to start the gateway with the Keycloak SSO profile. This is the recommended setup for SSO.

```bash
make compose-sso
```

--------------------------------

### Cert-Manager Installation and Issuer Setup

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/deployment/cforge-gateway.md

Commands to install cert-manager and create a CA Issuer. This is a prerequisite for using cert-manager in Kubernetes deployments.

```bash
# Install cert-manager: 
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

# Create namespace first
kubectl create namespace mcp-gateway-test

# Apply CA Issuer
kubectl apply -f cert-manager-issuer.yaml
```

--------------------------------

### Server Configuration Example

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/servers/python/data-analysis-server.md

Example of a 'config.yaml' file for server settings, including dataset limits, cache, visualization defaults, and logging.

```yaml
server:
  max_datasets: 100
  max_memory_mb: 1024
  cache_ttl_seconds: 3600

visualization:
  plot_output_dir: "./plots"
  default_dpi: 100
  default_figsize: [10, 6]
  style: "seaborn"

analysis:
  max_query_results: 10000
  default_sample_size: 5000
  confidence_level: 0.95

logging:
  level: "INFO"
  format: "% (asctime)s - % (name)s - % (levelname)s - % (message)s"
```

--------------------------------

### REST API: Get Timezone Info Response

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/servers/go/fast-time-server.md

Example response for the Get Timezone Info API, providing comprehensive details about a timezone.

```json
{
  "name": "Asia/Tokyo",
  "offset": "+09:00",
  "current_time": "2025-01-10T19:00:00+09:00",
  "is_dst": false,
  "abbreviation": "JST"
}
```

--------------------------------

### Start Pandoc Server with ContextForge

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/servers/go/pandoc-server.md

Initiates the Pandoc server using ContextForge for HTTP and SSE access. Requires Python 3 and mcpgateway.

```bash
# Start pandoc server via ContextForge
python3 -m mcpgateway.translate --stdio "./dist/pandoc-server" --port 9000

# Register with ContextForge
curl -X POST http://localhost:8000/gateways \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pandoc-server",
    "url": "http://localhost:9000",
    "description": "Document conversion server using Pandoc"
  }'
```

--------------------------------

### Example Configuration for Multiple Native Plugins

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/plugins/index.md

An example `plugins/config.yaml` file demonstrating the configuration of PIIFilterPlugin, ReplaceBadWordsPlugin, DenyListPlugin, and ResourceFilterExample.

```yaml
# plugins/config.yaml
plugins:

  - name: "PIIFilterPlugin"
    kind: "cpex_pii_filter.PIIFilterPlugin"
    hooks: ["prompt_pre_fetch", "prompt_post_fetch", "tool_pre_invoke", "tool_post_invoke"]
    mode: "transform"
    priority: 50
    config:
      detect_ssn: true
      detect_email: true
      detect_credit_card: true
      default_mask_strategy: "partial"

  - name: "ReplaceBadWordsPlugin"
    kind: "plugins.regex_filter.search_replace.SearchReplacePlugin"
    hooks: ["prompt_pre_fetch", "prompt_post_fetch", "tool_pre_invoke", "tool_post_invoke"]
    mode: "sequential"
    priority: 150
    config:
      words:

        - { search: "crap", replace: "crud" }
        - { search: "crud", replace: "yikes" }

  - name: "DenyListPlugin"
    kind: "plugins.deny_filter.deny.DenyListPlugin"
    hooks: ["prompt_pre_fetch"]
    mode: "sequential"
    priority: 100
    config:
      words: ["innovative", "groundbreaking", "revolutionary"]

  - name: "ResourceFilterExample"
    kind: "plugins.resource_filter.resource_filter.ResourceFilterPlugin"
    hooks: ["resource_pre_fetch", "resource_post_fetch"]
    mode: "sequential"
    priority: 75
    config:
      max_content_size: 1048576
      allowed_protocols: ["http", "https"]
      blocked_domains: ["malicious.example.com"]
      content_filters:

        - { pattern: "password\\s*[:=]\\s*\\S+", replacement: "password: [REDACTED]" }

plugin_settings:
  parallel_execution_within_band: false
  plugin_timeout: 30
  fail_on_plugin_error: false
  enable_plugin_api: true
  plugin_health_check_interval: 60
```

--------------------------------

### Keycloak SSO Configuration Example

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/manage/sso-generic-oidc-tutorial.md

Example environment variables for configuring SSO with Keycloak. Ensure the URLs and realm match your Keycloak setup.

```bash
# Keycloak on keycloak.company.com with realm "master"
SSO_ENABLED=true
SSO_GENERIC_ENABLED=true
SSO_GENERIC_PROVIDER_ID=keycloak
SSO_GENERIC_DISPLAY_NAME=Company SSO
SSO_GENERIC_CLIENT_ID=mcp-gateway
SSO_GENERIC_CLIENT_SECRET=AbC123dEf456GhI789jKl012MnO345pQr678StU901vWx234YzA567
SSO_GENERIC_AUTHORIZATION_URL=https://keycloak.company.com/auth/realms/master/protocol/openid-connect/auth
SSO_GENERIC_TOKEN_URL=https://keycloak.company.com/auth/realms/master/protocol/openid-connect/token
SSO_GENERIC_USERINFO_URL=https://keycloak.company.com/auth/realms/master/protocol/openid-connect/userinfo
SSO_GENERIC_ISSUER=https://keycloak.company.com/auth/realms/master
SSO_AUTO_CREATE_USERS=true
SSO_TRUSTED_DOMAINS=["company.com"]
```

--------------------------------

### Build and Run ContextForge with Makefile (Podman/Docker)

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/faq/index.md

Demonstrates how to use the provided Makefile to build and run ContextForge using Podman or Docker. Includes options for SSL and host network configurations.

```bash
make podman # or make docker
make podman-run-ssl # or make docker-run-ssl
make podman-run-ssl-host # or make docker-run-ssl-host
```

--------------------------------

### Verify MCP Context Forge Installation

Source: https://github.com/ibm/mcp-context-forge/blob/main/DEVELOPING.md

Check environment setup with `make check-env`, verify installation by printing the version, and test configuration.

```bash
# Check environment
make check-env

# Verify installation
python3 -c "import mcpgateway; print(mcpgateway.__version__)"

# Test configuration
python3 -m mcpgateway.config
```

--------------------------------

### Configuration File Example (config.yaml)

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/servers/go/calculator-server.md

Example configuration file in YAML format for server, logging, and tool-specific settings like precision and statistics.

```yaml
server:
  transport: "http"
  http:
    host: "127.0.0.1"
    port: 8081
    session_timeout: "5m"
    cors:
      enabled: true
      origins: ["http://localhost:3000"]

logging:
  level: "info"
  format: "json"

tools:
  precision:
    max_decimal_places: 15
    default_decimal_places: 2
  statistics:
    max_data_points: 10000
```

--------------------------------

### Live Preview Commands

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/development/documentation.md

Use these commands to set up a virtual environment and serve the documentation locally with live reloading.

```bash
cd docs
make venv     # First-time only, installs dependencies into a venv under `~/.venv/mcpgateway-docs`
make serve    # http://localhost:8003 (auto-reload on save)
```

--------------------------------

### Quick Start with Environment Variables (uv)

Source: https://github.com/ibm/mcp-context-forge/blob/main/README.md

Use this command to quickly start the gateway with essential environment variables set. It's recommended to use a .env file for managing settings.

```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
# Edit .env to customize your settings
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444
```

--------------------------------

### Authentik SSO Configuration Example

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/manage/sso-generic-oidc-tutorial.md

Example environment variables for configuring SSO with Authentik. Ensure the URLs and application slug match your Authentik setup.

```bash
# Authentik configuration
SSO_ENABLED=true
SSO_GENERIC_ENABLED=true
SSO_GENERIC_PROVIDER_ID=authentik
SSO_GENERIC_DISPLAY_NAME=Authentik SSO
SSO_GENERIC_CLIENT_ID=your-client-id
SSO_GENERIC_CLIENT_SECRET=your-client-secret
SSO_GENERIC_AUTHORIZATION_URL=https://authentik.company.com/application/o/authorize/
SSO_GENERIC_TOKEN_URL=https://authentik.company.com/application/o/token/
SSO_GENERIC_USERINFO_URL=https://authentik.company.com/application/o/userinfo/
SSO_GENERIC_ISSUER=https://authentik.company.com/application/o/mcp-gateway/
SSO_AUTO_CREATE_USERS=true
SSO_TRUSTED_DOMAINS=["company.com"]
```

--------------------------------

### Async Function Doctest Example

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/development/doctest-coverage.md

Demonstrates how to write doctests for asynchronous functions using 'asyncio.run()'. This example shows testing a connection setup for a transport.

```python
async def connect(self) -> None:
    """Set up transport connection.

    Examples:
        >>> transport = MyTransport()
        >>> import asyncio
        >>> asyncio.run(transport.connect())
        >>> transport.is_connected()
        True
    """
```

--------------------------------

### Ansible Playbook Quick Start Commands

Source: https://github.com/ibm/mcp-context-forge/blob/main/ansible/ocp/README.md

Execute these commands sequentially to set up, deploy, configure, and run benchmarks for the ContextForge stack on OpenShift.

```bash
# 1. Set up namespace + PostgresCluster + schema privileges
ansible-playbook ansible/ocp/playbooks/setup.yml -i ansible/ocp/inventory/cluster.yml

# 2. Deploy the full stack
ansible-playbook ansible/ocp/playbooks/deploy.yml -i ansible/ocp/inventory/cluster.yml

# 3. Enable Locust and configure benchmark
ansible-playbook ansible/ocp/playbooks/benchmark-setup.yml -i ansible/ocp/inventory/cluster.yml

# 4. Run the benchmark
ansible-playbook ansible/ocp/playbooks/benchmark.yml -i ansible/ocp/inventory/cluster.yml

# 5. Uninstall (preserves Postgres + namespace)
ansible-playbook ansible/ocp/playbooks/uninstall.yml -i ansible/ocp/inventory/cluster.yml
```

--------------------------------

### GitHub Integration Examples

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/clients/mcp-cli.md

Examples for interacting with GitHub using mcp-cli, including getting profile info, listing notifications, searching issues, and creating issues.

```bash
# Get your GitHub profile
mcp-cli cmd --server mcpgateway-wrapper --tool github-server-get-me --raw
```

```bash
# List notifications
mcp-cli cmd --server mcpgateway-wrapper --tool github-server-list-notifications --raw
```

```bash
# Search for issues assigned to you
mcp-cli cmd --server mcpgateway-wrapper --tool github-server-search-issues \
  --tool-args '{"q":"assignee:@me is:open"}' --raw
```

```bash
# Create a new issue
mcp-cli cmd --server mcpgateway-wrapper --tool github-server-create-issue \
  --tool-args '{"owner":"username","repo":"repository","title":"New Issue","body":"Issue description"}' --raw
```

--------------------------------

### Get Document Information

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/servers/python/libreoffice-server.md

Example of requesting metadata and statistics for a given document.

```json
{
  "input_file": "./report.docx"
}
```

--------------------------------

### Initialize Connection and List Tools

Source: https://github.com/ibm/mcp-context-forge/blob/main/plugins/examples/simple_token_auth/README.md

Demonstrates how to initialize a connection to the protocol and list available tools using Python requests.

```python
response = requests.post(
    f"{BASE_URL}/protocol/initialize",
    headers=headers,
    json={
        "protocolVersion": "2024-11-05",
        "capabilities": {},
        "clientInfo": {"name": "python-client", "version": "1.0.0"}
    }
)

print(response.json())

# List tools
tools = requests.get(f"{BASE_URL}/protocol/tools/list", headers=headers)
print(tools.json())
```

--------------------------------

### Start Server with Custom Config

Source: https://github.com/ibm/mcp-context-forge/blob/main/mcp-servers/python/mcp_eval_server/CONFIGURATION_GUIDE.md

Run the server using your custom configuration. Ensure you have validated the configuration first.

```bash
python -m mcp_eval_server.server
```

--------------------------------

### Install and Run Langflow for Development

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/servers/third-party/langflow-server.md

Clones the Langflow repository, installs development dependencies, and starts the server in development mode. Suitable for contributing to Langflow or advanced customization.

```bash
git clone https://github.com/logspace-ai/langflow.git
cd langflow

pip install -e ".[dev]"

langflow run --dev
```

--------------------------------

### Start ContextForge Server

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/manage/api-usage.md

Use `make dev` for a development server with auto-reloading on port 8000, or `make serve` for a production server on port 4444.

```bash
# Development server (port 8000, auto-reload)
make dev
```

```bash
# Production server (port 4444)
make serve
```

--------------------------------

### Start MCP Time Server

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/overview/quick_start.md

Sets the base URL and starts a sample MCP time server using uv and mcpgateway.translate. Ensure you have the necessary Python packages installed.

```bash
# Set the gateway base URL
export BASE_URL="http://localhost:4444"
# If you're running docker-compose with nginx:
# export BASE_URL="http://localhost:8080"

# Spin up a sample MCP time server (SSE, port 8002)
pip install uv
python3 -m mcpgateway.translate \
  --stdio "uvx mcp_server_time -- --local-timezone=Europe/Dublin" \
  --expose-sse \
  --port 8002 &
```

--------------------------------

### REST API: Get System Time Response

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/servers/go/fast-time-server.md

Example response structure for the Get System Time API endpoint, including time, timezone, Unix timestamp, and UTC.

```json
{
  "time": "2025-01-10T11:30:00-05:00",
  "timezone": "America/New_York",
  "unix": 1736522400,
  "utc": "2025-01-10T16:30:00Z"
}
```

--------------------------------

### Start and Register URL-to-Markdown Server with ContextForge

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/servers/python/url-to-markdown-server.md

Start the URL-to-markdown server using make serve-http-fastmcp. Then, register it with ContextForge using a curl command, providing its name, URL, and a description.

```bash
# Start the URL-to-markdown server via HTTP
make serve-http-fastmcp

# Register with ContextForge
curl -X POST http://localhost:8000/gateways \
  -H "Content-Type: application/json" \
  -d '{
    "name": "url-to-markdown",
    "url": "http://localhost:9000",
    "description": "Universal content to markdown conversion server"
  }'
```

--------------------------------

### Start Colima with Specific Resources

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/testing/LocalTest.md

Use this command to start Colima with 10 CPU cores and 18GB of memory. This is a prerequisite for running the lite load testing setup on macOS.

```bash
colima start --cpu 10 --memory 18
```

--------------------------------

### Build and Start Services with Make

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/deployment/tls-configuration.md

Use make commands to build the production container image and start all services defined in the docker-compose.yml file.

```bash
# Build production container image
make docker-prod

# Start all services (validates compose file and starts stack)
make compose-up

# Check service status
docker compose ps
```

--------------------------------

### Install and Configure MCPO

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/tutorials/openwebui-tutorial.md

Installs MCPO using pip or UV and creates a configuration file for managing MCP servers. This setup is essential for exposing MCP servers as OpenAPI endpoints.

```bash
# Install MCPO using UV (recommended)
pip install uv
uvx mcpo --version

# Or install with pip
pip install mcpo

# Create MCPO configuration
cat > mcpo_config.json <<EOF
{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}
EOF
```

--------------------------------

### Build fast-time-server from source

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/using/servers/go/fast-time-server.md

Clone the repository, navigate to the server directory, and build the executable using make.

```bash
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-servers/go/fast-time-server
make build
```

--------------------------------

### Start Performance Testing

Source: https://github.com/ibm/mcp-context-forge/blob/main/tests/performance/README.md

Initiate the standard performance test suite or view all available commands. Use `make test` for a quick run or `make help` for a full command list.

```bash
make test                     # Standard test
make help                     # Show all commands
```

--------------------------------

### Python Gateway Example

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/AGENTS.md

A basic Python snippet demonstrating the initialization and start of a Gateway object.

```python
from mcpgateway import Gateway

gateway = Gateway()
gateway.start()
```

--------------------------------

### Python Tooling Setup

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/development/developer-onboarding.md

Commands to upgrade pip and install uv/uvx for Python environment management.

```bash
pip install --upgrade pip
uv and uvx installed - [install uv](https://github.com/astral-sh/uv)
.venv recreated with make install-dev (installs runtime + dev extras)
```

--------------------------------

### Cache/Data Structure with Mocked Time Doctest Example

Source: https://github.com/ibm/mcp-context-forge/blob/main/llms/prompts/improve-doctest-coverage.md

Shows doctest examples for a cache mechanism, including setting and getting values, and testing Time-To-Live (TTL) expiration using mocked time.

```python
def get(self, key):
    """Get cached value.

    Examples:
        >>> from unittest.mock import patch
        >>> cache = ResourceCache(max_size=2, ttl=1)
        >>> cache.set('a', 1)
        >>> cache.get('a')
        1

        Test TTL expiration:
        >>> with patch("time.time") as mock_time:
        ...     mock_time.return_value = 1000
        ...     cache2 = ResourceCache(max_size=2, ttl=1)
        ...     cache2.set('x', 100)
        ...     mock_time.return_value = 1002
        ...     cache2.get('x') is None
        True
    """
```

--------------------------------

### Start SonarQube Docker Container and Configure Settings

Source: https://github.com/ibm/mcp-context-forge/blob/main/crates/mcp_runtime/RELEASE-CHECKLIST.md

Starts the SonarQube Docker container and adjusts cluster settings for disk watermarks and read-only blocks. This is part of the SonarQube static analysis setup.

```bash
# Start SonarQube and fix ES disk watermarks
make sonar-up-docker
docker exec mcp-context-forge-sonarqube-1 bash -c \
  'wget -q -O- --method=PUT \
    --body-data="{"persistent":{"cluster.routing.allocation.disk.watermark.flood_stage":"99%","cluster.routing.allocation.disk.watermark.high":"98%","cluster.routing.allocation.disk.watermark.low":"97%"}}" \
    --header="Content-Type: application/json" "http://localhost:9001/_cluster/settings"'
docker exec mcp-context-forge-sonarqube-1 bash -c \
  'wget -q -O- --method=PUT \
    --body-data="{"index.blocks.read_only_allow_delete": null}" \
    --header="Content-Type: application/json" "http://localhost:9001/_all/_settings"'
```

--------------------------------

### Complete Example: Tool Invocation

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/manage/api-usage.md

A comprehensive example demonstrating how to list tools, view a tool's input schema, and then invoke the tool. This requires the TOKEN and BASE_URL environment variables to be set.

```bash
# 1. List tools and find one to test
TOOLS=$(curl -s -H "Authorization: Bearer $TOKEN" $BASE_URL/tools)
export TOOL_ID=$(echo $TOOLS | jq -r '.[0].id')
export TOOL_NAME=$(echo $TOOLS | jq -r '.[0].name')

echo "Testing tool: $TOOL_NAME (ID: $TOOL_ID)"

# 2. View the tool's input schema
echo "Input schema:"
curl -s -H "Authorization: Bearer $TOKEN" $BASE_URL/tools/$TOOL_ID | jq '.inputSchema'

# 3. Invoke the tool
jq -n --arg name "$TOOL_NAME" --argjson args '{"param1":"test_value"}' \
  '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":$name,"arguments":$args}}' |
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @- "$BASE_URL/rpc" | jq '.result.content[0].text'
```

--------------------------------

### Minimal .env Setup for ContextForge

Source: https://github.com/ibm/mcp-context-forge/blob/main/docs/docs/faq/index.md

Provides the minimal environment variable setup required for ContextForge, including JWT secret key and admin login credentials. Copy the example file and edit as needed.

```bash
cp .env.example .env
```

```env
# JWT authentication (required)
JWT_SECRET_KEY=my-test-key-but-now-longer-than-32-bytes

# Admin UI login credentials
PLATFORM_ADMIN_EMAIL=admin@example.com
PLATFORM_ADMIN_PASSWORD=changeme
```

--------------------------------

### Get HTTP Bridge Connection Information

Source: https://github.com/ibm/mcp-context-forge/blob/main/mcp-servers/python/mcp_eval_server/README.md

Display the complete guide and connection details for the HTTP bridge.

```bash
make http-info
```

--------------------------------

### Build and Start LLMGuard Plugin Server

Source: https://github.com/ibm/mcp-context-forge/blob/main/plugins/external/llmguard/README.md

Commands to build the project and start the LLMGuard plugin server. These are necessary steps before integrating the plugin with ContextForge.

```bash
make build
make start
```

--------------------------------

### Development Setup Commands

Source: https://github.com/ibm/mcp-context-forge/blob/main/mcp-servers/python/mcp_eval_server/README.md

Commands for setting up the development environment, running the server, tests, and code quality checks.

```bash
# Install development dependencies
make dev-install
```

```bash
# Run development server
make dev
```

```bash
# Run tests
make test
```

```bash
# Check code quality
make lint
```

--------------------------------

### Get REST API Connection Information

Source: https://github.com/ibm/mcp-context-forge/blob/main/mcp-servers/python/mcp_eval_server/README.md

Display the complete guide and connection details for the REST API.

```bash
make rest-info
```