IBM MCP Context Forge: The Complete Guide to MCP Gateway & Registry for AI Agent Infrastructure

Introduction

IBM MCP Context Forge is a powerful Model Context Protocol (MCP) Gateway & Registry that serves as a central management point for tools, resources, and prompts accessible by MCP-compatible LLM applications. Developed by IBM and open-sourced under the Apache 2.0 license, it transforms how developers build and deploy AI agent infrastructures by providing federation, virtualization, security, and observability in one unified platform.

Table of Contents

• Key Features
• Installation & Setup
• Configuration
• Usage Examples
• Advanced Features
• Production Deployment
• Conclusion

Key Features

• MCP Gateway & Registry: Central management point for tools, resources, and prompts
• Federation: Auto-discovers and merges peer gateways with Redis-backed syncing
• REST-to-MCP Conversion: Virtualizes legacy APIs as MCP-compliant tools and servers
• Multi-Transport Support: HTTP, JSON-RPC, WebSocket, SSE, stdio, and streamable-HTTP
• A2A Integration: Agent-to-Agent integration for external AI agents (OpenAI, Anthropic, custom)
• Admin UI: Real-time management, configuration, and log monitoring with HTMX + Alpine.js
• Authentication & Security: Basic Auth, JWT, OAuth, and encrypted credential storage
• OpenTelemetry Observability: Distributed tracing with Phoenix, Jaeger, Zipkin support
• Scalable Deployment: Docker/PyPI deployment with Kubernetes and Redis federation

Installation & Setup

PyPI Installation (Recommended)

Quick Start (Single Command):

BASIC_AUTH_PASSWORD=pass \
MCPGATEWAY_UI_ENABLED=true \
MCPGATEWAY_ADMIN_API_ENABLED=true \
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

Manual Installation:

# Create isolated environment
mkdir mcpgateway && cd mcpgateway
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install mcp-contextforge-gateway

# Configure environment
export MCPGATEWAY_UI_ENABLED=true
export MCPGATEWAY_ADMIN_API_ENABLED=true

# Launch gateway
BASIC_AUTH_PASSWORD=pass JWT_SECRET_KEY=my-test-key \
  mcpgateway --host 0.0.0.0 --port 4444 &

Docker Installation

Basic Docker Run:

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 \
  -e BASIC_AUTH_USER=admin \
  -e BASIC_AUTH_PASSWORD=changeme \
  -e AUTH_REQUIRED=true \
  -e DATABASE_URL=sqlite:///./mcp.db \
  ghcr.io/ibm/mcp-context-forge:0.6.0

Persistent Storage:

mkdir -p $(pwd)/data
touch $(pwd)/data/mcp.db
sudo chown -R :docker $(pwd)/data
chmod 777 $(pwd)/data

docker run -d --name mcpgateway \
  --restart unless-stopped \
  -p 4444:4444 \
  -v $(pwd)/data:/data \
  -e DATABASE_URL=sqlite:////data/mcp.db \
  -e HOST=0.0.0.0 \
  -e JWT_SECRET_KEY=my-test-key \
  -e BASIC_AUTH_USER=admin \
  -e BASIC_AUTH_PASSWORD=changeme \
  ghcr.io/ibm/mcp-context-forge:0.6.0

Podman Installation (RHEL/Fedora)

podman run -d --name mcpgateway \
  -p 4444:4444 \
  -e HOST=0.0.0.0 \
  -e DATABASE_URL=sqlite:///./mcp.db \
  ghcr.io/ibm/mcp-context-forge:0.6.0

Configuration

Environment Variables

Create a .env file with your configuration:

# Basic Configuration
APP_NAME=MCP Gateway
HOST=127.0.0.1
PORT=4444
DATABASE_URL=sqlite:///./mcp.db

# Authentication
BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=changeme
AUTH_REQUIRED=true
JWT_SECRET_KEY=my-test-key
JWT_ALGORITHM=HS256
TOKEN_EXPIRY=10080
AUTH_ENCRYPTION_SECRET=my-test-salt

# UI Features
MCPGATEWAY_UI_ENABLED=true
MCPGATEWAY_ADMIN_API_ENABLED=true
MCPGATEWAY_BULK_IMPORT_ENABLED=true

# A2A (Agent-to-Agent) Features
MCPGATEWAY_A2A_ENABLED=true
MCPGATEWAY_A2A_MAX_AGENTS=100
MCPGATEWAY_A2A_DEFAULT_TIMEOUT=30
MCPGATEWAY_A2A_MAX_RETRIES=3

# Security
SKIP_SSL_VERIFY=false
ENVIRONMENT=development
CORS_ENABLED=true
SECURITY_HEADERS_ENABLED=true

OpenTelemetry Observability

# Enable observability with Phoenix
export OTEL_ENABLE_OBSERVABILITY=true
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_SERVICE_NAME=mcp-gateway
export OTEL_DEPLOYMENT_ENVIRONMENT=development

# Start Phoenix for LLM observability
docker run -p 6006:6006 -p 4317:4317 arizephoenix/phoenix:latest

Usage Examples

Authentication Setup

# Generate JWT Bearer Token
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
    --username admin --exp 10080 --secret my-test-key)

# Test authentication
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     http://127.0.0.1:4444/version | jq

Tool Registration

# Register a new tool
curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "name":"clock_tool",
           "url":"http://localhost:9000/rpc",
           "description":"Returns current time",
           "input_schema":{
             "type":"object",
             "properties":{"timezone":{"type":"string"}},
             "required":[]
           }
         }' \
     http://localhost:4444/tools

# List all tools
curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     http://localhost:4444/tools | jq

MCP Server Translation

# Translate stdio MCP server to SSE
python3 -m mcpgateway.translate \
     --stdio "uvx mcp-server-git" \
     --expose-sse \
     --port 9000

# Register translated server
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"git_server","url":"http://localhost:9000/sse"}' \
     http://localhost:4444/gateways

Virtual Server Creation

# Create virtual server bundling tools
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "name":"development_tools",
           "description":"Development and Git tools",
           "associatedTools":["tool-id-1", "tool-id-2"]
         }' \
     http://localhost:4444/servers | jq

Advanced Features

A2A Agent Integration

# Register external AI agent
curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "name":"openai_assistant",
           "endpoint_url":"https://api.openai.com/v1/",
           "agent_type":"openai",
           "description":"OpenAI GPT-4 assistant",
           "auth_type":"api_key",
           "auth_value":"your-openai-api-key",
           "tags":["ai", "openai", "gpt-4"]
         }' \
     http://localhost:4444/a2a

# Test agent functionality
curl -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "parameters": {
             "method": "chat/completions",
             "params": {
               "model": "gpt-4",
               "messages": [{"role": "user", "content": "Hello!"}]
             }
           },
           "interaction_type": "test"
         }' \
     http://localhost:4444/a2a/openai_assistant/invoke

Federation Setup

# Configure federation in .env
FEDERATION_ENABLED=true
FEDERATION_DISCOVERY=true
FEDERATION_PEERS=["http://peer1:4444", "http://peer2:4444"]
FEDERATION_TIMEOUT=30
FEDERATION_SYNC_INTERVAL=300

# Redis-backed federation
CACHE_TYPE=redis
REDIS_URL=redis://localhost:6379/0
CACHE_PREFIX=mcpgw:

MCP Client Integration

Claude Desktop Configuration:

{
  "mcpServers": {
    "mcpgateway-wrapper": {
      "command": "python3",
      "args": ["-m", "mcpgateway.wrapper"],
      "env": {
        "MCP_AUTH": "your-bearer-token",
        "MCP_SERVER_URL": "http://localhost:4444/servers/server-uuid/mcp",
        "MCP_TOOL_CALL_TIMEOUT": "120"
      }
    }
  }
}

Direct SSE Connection:

{
  "mcpServers": {
    "MetaMCP": {
      "url": "http://localhost:4444/servers/server-uuid/sse"
    }
  }
}

Production Deployment

PostgreSQL Backend

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

# Configure gateway
export DATABASE_URL=postgresql://postgres:mysecretpassword@localhost:5432/mcp

# Install PostgreSQL adapter
pip install psycopg2-binary

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-gateway
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-gateway
  template:
    metadata:
      labels:
        app: mcp-gateway
    spec:
      containers:
      - name: mcp-gateway
        image: ghcr.io/ibm/mcp-context-forge:0.6.0
        ports:
        - containerPort: 4444
        env:
        - name: DATABASE_URL
          value: "postgresql://postgres:password@postgres:5432/mcp"
        - name: REDIS_URL
          value: "redis://redis:6379/0"
        - name: CACHE_TYPE
          value: "redis"
        - name: FEDERATION_ENABLED
          value: "true"
---
apiVersion: v1
kind: Service
metadata:
  name: mcp-gateway-service
spec:
  selector:
    app: mcp-gateway
  ports:
  - protocol: TCP
    port: 80
    targetPort: 4444
  type: LoadBalancer

Security Configuration

# Production security settings
ENVIRONMENT=production
AUTH_REQUIRED=true
SECURE_COOKIES=true
COOKIE_SAMESITE=strict
SECURITY_HEADERS_ENABLED=true
HSTS_ENABLED=true
HSTS_MAX_AGE=31536000
X_FRAME_OPTIONS=DENY
REMOVE_SERVER_HEADERS=true

# Strong authentication
JWT_SECRET_KEY=$(openssl rand -base64 32)
AUTH_ENCRYPTION_SECRET=$(openssl rand -base64 32)
BASIC_AUTH_PASSWORD=$(openssl rand -base64 16)

Conclusion

IBM MCP Context Forge represents a significant advancement in AI agent infrastructure, providing a comprehensive gateway and registry solution for Model Context Protocol applications. With its powerful federation capabilities, REST-to-MCP virtualization, A2A agent integration, and enterprise-grade security features, it enables developers to build scalable, secure, and maintainable AI agent ecosystems.

Whether you're building simple tool integrations or complex multi-agent systems, MCP Context Forge provides the foundation for reliable, observable, and secure AI agent deployments with comprehensive observability and management capabilities.

For more expert insights and tutorials on AI and automation, visit us at decisioncrafters.com.