MCP Gateway

ContextForge

Um registro e proxy de código aberto que federa MCP, A2A e APIs REST/gRPC com governança centralizada, descoberta e observabilidade. Otimiza chamadas de Agentes e Ferramentas, e suporta plugins.

ContextForge é um registro e proxy de código aberto que federa ferramentas, agentes e APIs em um único endpoint limpo para seus clientes de IA. Ele fornece governança centralizada, descoberta e observabilidade em toda a sua infraestrutura de IA:

• Gateway de Ferramentas — MCP, REST, tradução gRPC-para-MCP e compressão TOON
• Gateway de Agentes — protocolo A2A, roteamento de agentes compatível com OpenAI e Anthropic
• Gateway de API — Limitação de taxa, autenticação, tentativas e proxy reverso para serviços REST
• Extensibilidade por Plugins — Mais de 40 plugins para transportes, protocolos e integrações adicionais
• Observabilidade — Rastreamento OpenTelemetry com Phoenix, Jaeger, Zipkin e outros backends OTLP

Ele é executado como um servidor MCP totalmente compatível, implantável via PyPI ou Docker, e escala para ambientes multi-cluster em Kubernetes com federação e cache apoiados por Redis.

Sumário

• Visão Geral e Objetivos
• Início Rápido - PyPI
• Início Rápido - Contêineres
• Contêiner de Desenvolvimento VS Code
• Instalação
• Atualização
• Configuração
• Execução
• Implantação em Nuvem
• Referência da API
• Testes
• Estrutura do Projeto
• Desenvolvimento
• Solução de Problemas
• Contribuição

📌 Links Rápidos

Visão Geral e Objetivos

ContextForge é um registro e proxy de código aberto que federa qualquer servidor Model Context Protocol (MCP), servidor A2A ou API REST/gRPC, fornecendo governança centralizada, descoberta e observabilidade. Ele otimiza chamadas de agentes e ferramentas, e suporta plugins. Consulte o roteiro do projeto para mais detalhes.

Atualmente suporta:

• Federação entre múltiplos serviços MCP e REST
• Integração A2A (Agente-para-Agente) para agentes de IA externos (OpenAI, Anthropic, personalizados)
• Tradução gRPC-para-MCP via descoberta automática de serviços baseada em reflexão
• Virtualização de APIs legadas como ferramentas e servidores compatíveis com MCP
• Transporte via HTTP, JSON-RPC, WebSocket, SSE (com keepalive configurável) e HTTP Streamable; transporte stdio disponível para uso no lado do servidor
• Uma Interface de Administração para gerenciamento em tempo real, configuração e monitoramento de logs (com suporte a implantação isolada)
• Autenticação integrada, tentativas e limitação de taxa com tokens OAuth por usuário e suporte incondicional ao cabeçalho X-Upstream-Authorization
• Observabilidade OpenTelemetry com Phoenix, Jaeger, Zipkin e outros backends OTLP
• Implantações escaláveis via Docker ou PyPI, cache apoiado por Redis e federação multi-cluster

Para uma lista de recursos futuros, confira o Roteiro do ContextForge

Início Rápido - PyPI

ContextForge é publicado no PyPI como mcp-contextforge-gateway.

⚠️ JWT_SECRET_KEY e AUTH_ENCRYPTION_SECRET são obrigatórios em todos os ambientes — incluindo desenvolvimento local. O gateway não iniciará sem eles. Gere segredos reais com python3 -m mcpgateway.scripts.init_secrets antes da primeira execução.

Resumo — comando único usando uv:

# 1️⃣  Generate secure secrets (creates .env.secrets)
python3 -m mcpgateway.scripts.init_secrets

# 2️⃣  Export the generated values
export JWT_SECRET_KEY="$(grep '^JWT_SECRET_KEY=' .env.secrets | cut -d= -f2)"
export AUTH_ENCRYPTION_SECRET="$(grep '^AUTH_ENCRYPTION_SECRET=' .env.secrets | cut -d= -f2)"

# 3️⃣  Start the gateway
JWT_SECRET_KEY="$JWT_SECRET_KEY" \
AUTH_ENCRYPTION_SECRET="$AUTH_ENCRYPTION_SECRET" \
MCPGATEWAY_UI_ENABLED=true \
MCPGATEWAY_ADMIN_API_ENABLED=true \
PLATFORM_ADMIN_EMAIL=admin@example.com \
uvx --from mcp-contextforge-gateway mcpgateway --host 0.0.0.0 --port 4444

1 - Instalar e executar (pronto para copiar e colar)

# 1️⃣  Create an isolated env and install from PyPI
mkdir mcpgateway && cd mcpgateway
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install mcp-contextforge-gateway

# 2️⃣  Download .env.example and generate real secrets
curl -O https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example
cp .env.example .env

# Generate cryptographically secure secrets into .env.secrets
python3 -m mcpgateway.scripts.init_secrets

# Patch the generated secrets into .env (replaces __REPLACE_ME__ placeholders)
python3 -m mcpgateway.scripts.init_secrets --patch-env .env

# 3️⃣  Start the gateway
mcpgateway --host 0.0.0.0 --port 4444 &

# 4️⃣  Generate a bearer token and smoke-test
export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
    --username admin@example.com --exp 10080 --secret "$JWT_SECRET_KEY")

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

# 1️⃣  Isolated env + install from PyPI
mkdir mcpgateway ; cd mcpgateway
python3 -m venv .venv ; .\.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install mcp-contextforge-gateway

# 2️⃣  Download .env.example and generate real secrets
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/IBM/mcp-context-forge/main/.env.example" -OutFile ".env.example"
Copy-Item .env.example .env

# Generate cryptographically secure secrets into .env.secrets
python3 -m mcpgateway.scripts.init_secrets

# Patch the generated secrets into .env (replaces __REPLACE_ME__ placeholders)
python3 -m mcpgateway.scripts.init_secrets --patch-env .env

# 3️⃣  Launch the gateway
mcpgateway.exe --host 0.0.0.0 --port 4444

# 4️⃣  Bearer token and smoke-test
$Env:JWT_SECRET_KEY = (Get-Content .env | Select-String '^JWT_SECRET_KEY=').ToString().Split('=')[1]
$Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token `
    --username admin@example.com --exp 10080 --secret $Env:JWT_SECRET_KEY

curl -s -H "Authorization: Bearer $Env:MCPGATEWAY_BEARER_TOKEN" `
     http://127.0.0.1:4444/version | jq

# 1️⃣  Isolated env + install from PyPI using uv
mkdir mcpgateway ; cd mcpgateway
uv venv
.\.venv\Scripts\activate
uv pip install mcp-contextforge-gateway

# Continue with steps 2️⃣-4️⃣ above...

# 1️⃣  Spin up the sample MCP time server using mcpgateway.translate & docker (replace docker with podman if needed)
python3 -m mcpgateway.translate \
     --stdio "docker run --rm -i ghcr.io/ibm/fast-time-server:latest -transport=stdio" \
     --expose-sse \
     --port 8003

# Or using the official mcp-server-git using uvx:
pip install uv # to install uvx, if not already installed
python3 -m mcpgateway.translate --stdio "uvx mcp-server-git" --expose-sse --port 9000

# NEW: Expose via multiple protocols simultaneously!
python3 -m mcpgateway.translate \
     --stdio "uvx mcp-server-git" \
     --expose-sse \
     --expose-streamable-http \
     --port 9000
# Now accessible via both /sse (SSE) and /mcp (streamable HTTP) endpoints

# 2️⃣  Register it with the gateway
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"fast_time","url":"http://localhost:8003/sse"}' \
     http://localhost:4444/gateways

# 3️⃣  Verify tool catalog
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/tools | jq

# 4️⃣  Create a *virtual server* bundling those tools. Use the ID of tools from the tool catalog (Step #3) and pass them in the associatedTools list.
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"server":{"name":"time_server","description":"Fast time tools","associated_tools":[<ID_OF_TOOLS>]}}' \
     http://localhost:4444/servers | jq

# Example curl
curl -s -X POST -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"server":{"name":"time_server","description":"Fast time tools","associated_tools":["6018ca46d32a4ac6b4c054c13a1726a2"]}}' \
     http://localhost:4444/servers | jq

# 5️⃣  List servers (should now include the UUID of the newly created virtual server)
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" http://localhost:4444/servers | jq

# 6️⃣  Client HTTP endpoint. Inspect it interactively with the MCP Inspector CLI (or use any MCP client)
npx -y @modelcontextprotocol/inspector
# Transport Type: Streamable HTTP, URL: http://localhost:4444/servers/UUID_OF_SERVER_1/mcp,  Header Name: "Authorization", Bearer Token

Início Rápido - Contêineres

Use a imagem OCI oficial do GHCR com Docker ou Podman. Observe: Atualmente, arm64 não é suportado em produção. Se você estiver, por exemplo, executando no MacOS com chips Apple Silicon (M1, M2, etc.), você pode executar os contêineres usando Rosetta ou instalar via PyPI.

🚀 Início Rápido - Docker Compose

Importante: docker compose up -d não constrói a imagem do gateway localmente por padrão — ele usa a imagem pré-construída do GHCR. O arquivo compose inclui um bloco build: como fallback, mas construções locais exigem um fechamento hermético de wheel que só é produzido pelo pipeline de CI. Se você vir um erro de cryptography ou de resolução de dependências durante a construção, você está enfrentando isso — basta puxar a imagem (o passo 2 abaixo lida com isso automaticamente).

Você também deve ter um arquivo .env com segredos reais antes de executar docker compose up -d. O gateway não iniciará com valores de espaço reservado.

Obtenha uma pilha completa em execução com PostgreSQL e Redis:

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

# 2️⃣  Set up .env with real secrets AND pull the pre-built images
cp .env.example .env
python3 -m mcpgateway.scripts.init_secrets --patch-env .env
# .env now has strong JWT_SECRET_KEY and AUTH_ENCRYPTION_SECRET

# Pull pre-built images from GHCR (avoids local build entirely)
docker pull ghcr.io/ibm/mcp-context-forge:latest
echo 'IMAGE_LOCAL=ghcr.io/ibm/mcp-context-forge:latest' >> .env

# Build only the nginx image (small, local-only, builds in seconds)
docker compose build nginx

# 3️⃣  Start the full stack
docker compose up -d

# 4️⃣  Check status
docker compose ps

# 5️⃣  View logs
docker compose logs -f gateway

# 6️⃣  Access Admin UI: http://localhost:8080/admin
#     Login: PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD (from .env)

# 7️⃣  Generate an API token
export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)
docker compose exec gateway python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@example.com --exp 10080 --secret "$JWT_SECRET_KEY"

O que você obtém:

• 🗄️ PostgreSQL - Banco de dados pronto para produção com mais de 55 tabelas
• 🚀 ContextForge - Gateway completo com Interface de Administração
• 📊 Redis - Cache de alto desempenho e armazenamento de sessão
• 🔧 Ferramentas de Administração - pgAdmin, Redis Insight para gerenciamento de banco de dados
• 🌐 Proxy Nginx - Proxy reverso com cache na porta 8080

Habilitar HTTPS (opcional):

# Start with TLS enabled (auto-generates self-signed certs)
make compose-tls

# Access via HTTPS: https://localhost:8443/admin

# Or bring your own certificates:
# Unencrypted key:
mkdir -p certs
cp your-cert.pem certs/cert.pem && cp your-key.pem certs/key.pem
make compose-tls

# Passphrase-protected key:
mkdir -p certs
cp your-cert.pem certs/cert.pem && cp your-encrypted-key.pem certs/key-encrypted.pem
echo "KEY_FILE_PASSWORD=your-passphrase" >> .env
make compose-tls

☸️ Início Rápido - Helm (Kubernetes)

Implante no Kubernetes com recursos de nível empresarial:

# Add Helm repository (when available)
# helm repo add mcp-context-forge https://ibm.github.io/mcp-context-forge
# helm repo update

# For now, use local chart
git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge/charts/mcp-stack

# Generate secrets first
python3 -m mcpgateway.scripts.init_secrets
JWT_SECRET=$(grep '^JWT_SECRET_KEY=' .env.secrets | cut -d= -f2)
ENC_SECRET=$(grep '^AUTH_ENCRYPTION_SECRET=' .env.secrets | cut -d= -f2)

# Install with PostgreSQL (default)
# IMPORTANT: replace <strong-password> with a real password — do not use 'changeme' in production
helm install mcp-gateway . \
  --set mcpContextForge.secret.PLATFORM_ADMIN_EMAIL=admin@yourcompany.com \
  --set mcpContextForge.secret.PLATFORM_ADMIN_PASSWORD=<strong-password> \
  --set mcpContextForge.secret.BASIC_AUTH_PASSWORD=<strong-password> \
  --set "mcpContextForge.secret.JWT_SECRET_KEY=${JWT_SECRET}" \
  --set "mcpContextForge.secret.AUTH_ENCRYPTION_SECRET=${ENC_SECRET}"

# Check deployment status
kubectl get pods -l app.kubernetes.io/name=mcp-context-forge

# Port forward to access Admin UI
kubectl port-forward svc/mcp-gateway-mcp-context-forge 4444:80
# Access: http://localhost:4444/admin

# Generate API token (reads JWT_SECRET_KEY from the pod's environment)
kubectl exec deployment/mcp-gateway-mcp-context-forge -- \
  python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@yourcompany.com --exp 10080 --secret "${JWT_SECRET}"

Nota sobre SSRF: O Helm usa configurações SSRF estritas por padrão (SSRF_ALLOW_PRIVATE_NETWORKS=false). Se você registrar URLs de ferramentas dentro do cluster, permita apenas os CIDRs do seu cluster via mcpContextForge.config.SSRF_ALLOWED_NETWORKS ou, para configurações de benchmark apenas locais, defina temporariamente SSRF_ALLOW_PRIVATE_NETWORKS=true. Consulte docs/docs/manage/configuration.md#ssrf-protection e docs/docs/deployment/helm.md.

Recursos Empresariais:

• 🔄 Auto-escala - HPA com alvos de CPU/memória
• 🗄️ Escolha de Banco de Dados - PostgreSQL (produção), SQLite (desenvolvimento)
• 📊 Observabilidade - Métricas Prometheus, rastreamento OpenTelemetry
• 🔒 Segurança - RBAC, políticas de rede, gerenciamento de segredos
• 🚀 Alta Disponibilidade - Implantações multi-réplica com clustering Redis
• 📈 Monitoramento - Painéis Grafana integrados e alertas

🐳 Docker (Contêiner Único)

# Generate secrets first (creates .env.secrets)
python3 -m mcpgateway.scripts.init_secrets
export JWT_SECRET_KEY="$(grep '^JWT_SECRET_KEY=' .env.secrets | cut -d= -f2)"
export AUTH_ENCRYPTION_SECRET="$(grep '^AUTH_ENCRYPTION_SECRET=' .env.secrets | cut -d= -f2)"

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="${JWT_SECRET_KEY}" \
  -e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \
  -e AUTH_REQUIRED=true \
  -e PLATFORM_ADMIN_EMAIL=admin@example.com \
  -e PLATFORM_ADMIN_PASSWORD=<strong-password> \
  -e PLATFORM_ADMIN_FULL_NAME="Platform Administrator" \
  -e DATABASE_URL=sqlite:///./mcp.db \
  -e SECURE_COOKIES=false \
  ghcr.io/ibm/mcp-context-forge:latest

# Tail logs
docker logs -f mcpgateway

# Generate API token (using the same secret)
docker run --rm -it \
  -e JWT_SECRET_KEY="${JWT_SECRET_KEY}" \
  ghcr.io/ibm/mcp-context-forge:latest \
  python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@example.com --exp 10080 --secret "${JWT_SECRET_KEY}"

Navegue para http://localhost:4444/admin e faça login com PLATFORM_ADMIN_EMAIL / PLATFORM_ADMIN_PASSWORD.

mkdir -p $(pwd)/data && touch $(pwd)/data/mcp.db && 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 MCPGATEWAY_UI_ENABLED=true -e MCPGATEWAY_ADMIN_API_ENABLED=true \
  -e HOST=0.0.0.0 -e JWT_SECRET_KEY="${JWT_SECRET_KEY}" \
  -e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \
  -e PLATFORM_ADMIN_EMAIL=admin@example.com -e PLATFORM_ADMIN_PASSWORD=<strong-password> \
  ghcr.io/ibm/mcp-context-forge:latest

docker run -d --name mcpgateway --network=host \
  -v $(pwd)/data:/data -e DATABASE_URL=sqlite:////data/mcp.db \
  -e MCPGATEWAY_UI_ENABLED=true -e HOST=0.0.0.0 -e PORT=4444 \
  -e JWT_SECRET_KEY="${JWT_SECRET_KEY}" -e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \
  ghcr.io/ibm/mcp-context-forge:latest

docker build -f Containerfile -t mcpgateway:airgapped .
docker run -d --name mcpgateway -p 4444:4444 \
  -e MCPGATEWAY_UI_AIRGAPPED=true -e MCPGATEWAY_UI_ENABLED=true \
  -e HOST=0.0.0.0 -e JWT_SECRET_KEY="${JWT_SECRET_KEY}" \
  -e AUTH_ENCRYPTION_SECRET="${AUTH_ENCRYPTION_SECRET}" \
  mcpgateway:airgapped

🦭 Podman (compatível com rootless)

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:1.0.0-RC-3

mkdir -p $(pwd)/data && chmod 777 $(pwd)/data
podman run -d --name mcpgateway --restart=on-failure \
  -p 4444:4444 -v $(pwd)/data:/data \
  -e DATABASE_URL=sqlite:////data/mcp.db \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3

podman run -d --name mcpgateway --network=host \
  -v $(pwd)/data:/data -e DATABASE_URL=sqlite:////data/mcp.db \
  ghcr.io/ibm/mcp-context-forge:1.0.0-RC-3

curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     http://localhost:4444/health | jq
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     http://localhost:4444/tools | jq
curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
     http://localhost:4444/version | jq

Início Rápido: Contêiner de Desenvolvimento VS Code

Clone o repositório e abra no VS Code—ele detectará .devcontainer e solicitará "Reabrir no Contêiner". O contêiner inclui Python 3.11, Docker CLI e todas as dependências do projeto. Para configuração detalhada, fluxos de trabalho e instruções do GitHub Codespaces, consulte Developer Onboarding.

Instalação

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

Nota sobre o workspace Rust:

• As crates Rust pertencentes ao workspace ficam em crates/ e são detectadas pela raiz Cargo.toml via crates/*.
• Execute cargo build, cargo test e cargo check a partir da raiz do repositório para cobrir o workspace compartilhado.
• make venv install-dev cria a raiz .venv, que também é reutilizada pelos builds PyO3/maturin do workspace.

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

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

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

Atualização

Para instruções de atualização, guias de migração e procedimentos de rollback, consulte:

• Guia de Atualização — Procedimentos gerais de atualização
• MIGRATION.md — Mudanças que quebram compatibilidade e instruções passo a passo de atualização
• CHANGELOG.md — Histórico de versões e mudanças que quebram compatibilidade

Configuração

⚠️ Se qualquer variável .env obrigatória estiver ausente ou inválida, o gateway falhará rapidamente na inicialização com um erro de validação via Pydantic.

Copie o .env.example fornecido para .env e atualize os valores sensíveis de segurança abaixo.

🔐 Obrigatório: Definir Antes de Iniciar

Estas variáveis devem ser definidas antes que o gateway inicie. Não há padrões utilizáveis — a aplicação falha na inicialização se estiverem ausentes ou com valores de espaço reservado:

Estas variáveis têm padrões inseguros e devem ser alteradas antes do uso em produção:

🔒 Padrões de Segurança (Seguro por Padrão)

Estas configurações estão habilitadas por padrão por segurança — desative apenas para compatibilidade com versões anteriores:

🛡️ Segurança de Conteúdo

Os limites de tamanho de conteúdo previnem ataques DoS e garantem a estabilidade do sistema:

Nota: Os limites de tamanho se aplicam apenas a novas operações de criação/atualização. O conteúdo existente não é validado retroativamente.

🌐 Segurança de Roteamento Entre Gateways UAID

Configuração de Segurança UAID

Requisitos de Produção:

O roteamento UAID entre gateways exige configuração de segurança explícita:

1. Configure a Lista de Domínios Permitidos:

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

2. Garanta a Confiança do JWT:

   • Ambos os gateways devem confiar no mesmo emissor de JWT
   • Opção A: Segredo compartilhado (mesmo JWT_SECRET_KEY em todos os gateways)
   • Opção B: SSO federado (Google, GitHub, Entra ID)

3. Habilite a Autenticação:

   AUTH_REQUIRED=true
   UAID_FORWARD_AUTH=true
   

Fluxo de Autenticação:

Chamadas entre gateways encaminham o token de portador do usuário via cabeçalho Authorization. Os gateways remotos validam os tokens por meio do middleware de autenticação existente, preservando o contexto RBAC.

Recursos de Segurança:

• ✅ Padrão de falha fechada: Lista de domínios vazia bloqueia todo o roteamento entre gateways
• ✅ Encaminhamento de token de portador: Autenticação do usuário preservada entre saltos
• ✅ Trilha de auditoria: Gateway de origem e usuário rastreados em cabeçalhos
• ✅ Mensagens de erro claras: Configurações incorretas detectadas na inicialização e em tempo de execução

Solução de Problemas:

• Erro "UAID_ALLOWED_DOMAINS não configurado": Adicione domínios confiáveis à lista de permitidos no .env
• 401/403 do gateway remoto: Verifique se ambos os gateways confiam no mesmo emissor de JWT
• Aviso "prosseguindo sem token de autenticação": Verifique se o middleware de autenticação extrai o token para request.state.bearer_token

Para arquitetura de segurança detalhada, consulte docs/security/uaid-cross-gateway-auth.md.

⚙️ Padrões do Projeto (Configuração de Desenvolvimento)

Estes valores diferem dos padrões do código para fornecer uma configuração local/de desenvolvimento funcional:

📚 Referência Completa de Configuração

Para a lista completa de mais de 300 variáveis de ambiente organizadas por categoria (autenticação, cache, SSO, observabilidade, etc.), consulte a Referência de Configuração.

Execução

Referência Rápida

Servidor de Desenvolvimento (Uvicorn)

make dev                 # Uvicorn on :8000 with auto-reload and SQLite
# or
./run.sh --reload --log debug --workers 2

run.sh é um wrapper em torno de uvicorn que carrega .env, suporta recarga e passa argumentos para o servidor.

Flags principais:

Servidor de Produção (Gunicorn)

make serve               # Gunicorn on :4444 with multiple workers
make serve-ssl           # Gunicorn behind HTTPS on :4444 (uses ./certs)

Docker Compose (Stack Completo)

make compose-up          # Start full stack: PostgreSQL, Redis, 3 gateway replicas, Nginx on :8080
make compose-sso         # Start SSO stack with Keycloak on :8180
make sso-test-login      # Run SSO smoke checks (providers + login URL + test users)
make compose-logs        # Tail logs from all services
make compose-down        # Stop the stack

Manual (Uvicorn)

uvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444 --workers 4

Implantação em Nuvem

O ContextForge pode ser implantado em qualquer plataforma de nuvem importante:

Para guias de implantação abrangentes, consulte Documentação de Implantação.

Referência da API

A documentação interativa da API está disponível quando o servidor está em execução:

• Swagger UI — Experimente chamadas de API diretamente no seu navegador
• ReDoc — Navegue pela referência completa de endpoints

Autenticação Rápida:

# Read JWT_SECRET_KEY from your .env (it must already contain a real secret)
export JWT_SECRET_KEY=$(grep '^JWT_SECRET_KEY=' .env | cut -d= -f2)

# Generate a JWT token
export TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token \
  --username admin@example.com --exp 10080 --secret "$JWT_SECRET_KEY")

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

Para exemplos abrangentes de curl cobrindo todos os endpoints, consulte o Guia de Uso da API.

Testes

make test            # Run unit tests
make lint            # Run all linters
make doctest         # Run doctests
make coverage        # Generate coverage report

Consulte o Guia de Cobertura de Testes de Documentação para detalhes sobre testes de documentação.

Estrutura do Projeto

mcpgateway/          # Core FastAPI application
├── main.py          # Entry point
├── config.py        # Pydantic Settings configuration
├── db.py            # SQLAlchemy ORM models
├── schemas.py       # Pydantic validation schemas
├── services/        # Business logic layer (50+ services)
├── routers/         # HTTP endpoint definitions
├── middleware/      # Cross-cutting concerns
└── transports/      # SSE, WebSocket, stdio, streamable HTTP

tests/               # Test suite (7,000+ tests)
docs/docs/           # Full documentation (MkDocs)
charts/              # Kubernetes/Helm charts
plugins/             # Plugin framework and implementations
mcp-servers/         # Sample/test MCP servers (see note below)

Nota: O diretório mcp-servers/ contém servidores de exemplo e teste não suportados, a maioria originada de contribuições da comunidade, fornecidos apenas para fins de demonstração e testes de integração. Eles geralmente não possuem gerenciamento de sessão, estado persistente, multi-tenancy, autenticação e outras preocupações de produção. Eles não passam pelo mesmo rigor de revisão, teste e segurança que o código-fonte principal do ContextForge e não devem ser executados em produção.

Segurança: Nunca execute servidores MCP não confiáveis diretamente no seu sistema de arquivos local. Sempre use um sandbox, container ou microVM (por exemplo, gVisor, Firecracker) com capacidades restritas. Tenha cautela ao registrar qualquer servidor MCP remoto, incluindo servidores de catálogos públicos — faça sua própria avaliação de segurança antes de conceder acesso ao seu gateway.

Para a estrutura completa, consulte CONTRIBUTING.md ou execute tree -L 2.

Desenvolvimento

make dev             # Dev server with auto-reload (:8000)
make test            # Run test suite
make lint            # Run all linters
make coverage        # Generate coverage report

Execute make para ver todos os alvos disponíveis.

Para fluxos de trabalho de desenvolvimento, consulte:

• Configuração da Estação de Trabalho do Desenvolvedor
• Compilação e Empacotamento

Solução de Problemas

Problemas comuns e soluções:

Para guias detalhados de solução de problemas, consulte Documentação de Solução de Problemas.

Contribuindo

1. Faça um fork do repositório e crie um branch de funcionalidade.
2. Execute make lint e corrija quaisquer problemas.
3. Mantenha make test verde.
4. Abra um PR com commits assinados (git commit -s).

Consulte CONTRIBUTING.md para diretrizes completas e Guia de Problemas #2502 para saber como relatar bugs, solicitar recursos e encontrar problemas para trabalhar.

Changelog

Um changelog completo pode ser encontrado aqui: CHANGELOG.md

Licença

Licenciado sob a Apache License 2.0 — consulte LICENSE

Autores Principais e Mantenedores

• Mihai Criveti — Engenheiro Distinto, IA Agêntica

Agradecimentos especiais aos nossos contribuidores por nos ajudar a melhorar o ContextForge:

Histórico de Estrelas e Atividade do Projeto