metrotel/mcp-prov repository overview

⁠mcp-prov

Proxy MCP local en Python que envuelve un servidor MCP existente en n8n (la instancia de aprovisionamiento de Metrotel). Agrega caché, logging, tool compuesta de diagnóstico y auth Bearer propio sin tocar el backend.

Imagen en Docker Hub: metrotel/mcp-prov⁠

• 🌐 Habla stdio (Claude Code / clients embed) o HTTP (Claude Desktop y otros)
• 🔐 Aísla el token upstream: nunca sale al cliente
• ⚡ Caché in-memory 60s para lecturas idempotentes (config vía env var)
• 📝 Log JSON-lines de cada tool call (tool, args, cached, duration_ms, error)
• 🛠 Expone las 32 tools upstream + una tool compuesta diagnostico_completo
• ♻️ Re-inicializa sesión si el upstream la cierra (bug conocido de n8n MCP)
• 🚀 Deploy: Docker / Docker Swarm / Kubernetes / systemd user unit / standalone Python
• 💾 Volumen /data para logs persistentes (y cache futura)

⁠Por qué existe

El server MCP embebido en el flujo de n8n de Metrotel cierra el long-poll SSE tras un tiempo de inactividad, y clientes como mcp-remote empiezan a hacer reintentos ruidosos. Además el token upstream vivía en JSONs de config en claro.

Este proxy:

• Elimina el long-poll: cada tool call abre su propia HTTP request al upstream y cierra al terminar.
• Aísla el token upstream (X-Prov-MCP-Key): vive solo en el env file del proxy, no en Claude Desktop / Claude Code configs.
• Agrega caché para las lecturas que se repiten (ej. mismo contexto_servicio varias veces en pocos minutos).
• Agrega una tool compuesta que encadena varias tools upstream y devuelve un resumen — evita que el modelo tenga que orquestar 3 llamadas cuando puede pedir una sola.

⁠Requisitos

• Python 3.10+
• uv⁠ (recomendado, o pip)
• Acceso de red al server MCP upstream y el header X-Prov-MCP-Key válido

⁠Quickstart

⁠Docker (recomendado, sin build local)

docker run -d --name prov-mcp -p 8767:8767 \
  -e PROV_MCP_KEY='pmcc_...' \
  -e PROV_MCP_AUTH_TOKEN='pmcp_...' \
  -v prov-data:/data \
  --restart unless-stopped \
  metrotel/mcp-prov:0.2.2

O con docker-compose.yml del repo:

git clone https://github.com/datacenter-metrotel/mcp-prov.git
cd mcp-prov
cp .env.example .env && chmod 600 .env    # editá .env
docker compose up -d

Log persistido en el volumen prov-data (montado a /data/logs):

docker exec prov-mcp tail -f /data/logs/calls.log

⁠Modo HTTP nativo (sin Docker)

git clone https://github.com/datacenter-metrotel/mcp-prov.git
cd mcp-prov

cp .env.example .env
chmod 600 .env
# editá .env con los valores reales

# Arrancar en foreground
uvx --from . prov-mcp-proxy
# server escuchando en http://0.0.0.0:8767/mcp

Verificar:

KEY=$(grep '^PROV_MCP_AUTH_TOKEN=' .env | cut -d= -f2)
curl -sS -L -X POST http://127.0.0.1:8767/mcp \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}'

⁠Modo stdio (para Claude Code / Cursor u otros clients que arrancan el proceso)

export PROV_MCP_KEY='pmcc_...'
export PROV_MCP_TRANSPORT=stdio
uvx --from . prov-mcp-proxy

Y en .mcp.json (Claude Code):

{
  "mcpServers": {
    "prov": {
      "command": "uvx",
      "args": ["--from", "/ruta/al/repo", "prov-mcp-proxy"],
      "env": { "PROV_MCP_KEY": "${PROV_MCP_KEY}" }
    }
  }
}

⁠Deploy en Kubernetes / Docker Swarm

• Kubernetes con envFrom.secretRef + PersistentVolumeClaim: ver k8s/README.md⁠.
• Docker Swarm con secrets encriptados en raft + volumen: ver swarm/README.md⁠.

⁠Deploy como systemd user unit

Template en systemd/prov-mcp-proxy.service.example:

mkdir -p ~/.config/systemd/user ~/.config/prov-mcp-proxy
cp systemd/prov-mcp-proxy.service.example ~/.config/systemd/user/prov-mcp-proxy.service
cp .env.example ~/.config/prov-mcp-proxy/env
chmod 600 ~/.config/prov-mcp-proxy/env
# editá ~/.config/prov-mcp-proxy/env con los valores reales

systemctl --user daemon-reload
systemctl --user enable --now prov-mcp-proxy.service
systemctl --user status prov-mcp-proxy.service

Para que sobreviva a reboots sin login: sudo loginctl enable-linger $USER.

⁠Uso desde Claude Desktop

Editar claude_desktop_config.json:

{
  "mcpServers": {
    "prov": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://<HOST_IP>:8767/mcp",
        "--allow-http",
        "--transport", "http-only",
        "--header", "Authorization:Bearer <PROV_MCP_AUTH_TOKEN>"
      ]
    }
  }
}

Rutas del config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux (community): ~/.config/Claude/claude_desktop_config.json

Ver ejemplo completo en examples/claude_desktop_config.example.json.

⁠Variables de entorno

⁠Tools expuestas

Todas las tools del upstream se re-exponen tal cual (32 al momento de escribir), más una compuesta:

• diagnostico_completo(service_number) — llama contexto_servicio → Topologia → (si el subproducto es ISI) ISI_Check_IP, y devuelve un resumen agrupado. Útil como "punto de entrada" para diagnóstico rápido de un servicio dado su número.

Ver el detalle de las tools upstream en la colección Postman en postman/⁠.

⁠Caché

Tools que nunca se cachean (efectos activos o datos volátiles):

• Ping_tool
• ATA_Test_1, ATA_Test_2, ATA_Test_3
• Gestion_ACS
• Obtener_backup_equipo

El resto entra a caché con TTL configurable (default 60s). El key incluye nombre de tool + hash SHA1 de los argumentos normalizados.

⁠Log

Cada tool call se registra en ~/.cache/prov_mcp_proxy/calls.log como una línea JSON con ts, tool, args, cached, duration_ms, error. Rotación automática 5 MB × 3.

⁠Seguridad

Ver SECURITY.md⁠. En resumen:

• Bearer obligatorio en modo HTTP (middleware Starlette).
• Token upstream nunca sale del proxy.
• Env file con creds va con chmod 600, fuera de git.
• .env en .gitignore.

⁠Licencia

MIT — ver LICENSE⁠.