mcp-prov

Lokaler MCP-Proxy in Python, der einen bestehenden MCP-Server in n8n umschließt (die Metrotel-Bereitstellungsinstanz). Er fügt Cache, Logging, zusammengesetztes Diagnose-Tool und eigenen Bearer-Auth hinzu, ohne das Backend anzufassen.

Docker-Hub-Image: metrotel/mcp-prov

• 🌐 Spricht stdio (Claude Code / eingebettete Clients) oder HTTP (Claude Desktop und andere)

• 🔐 Isoliert das Upstream-Token: Es verlässt den Client nie

• ⚡ In-Memory-Cache 60s für idempotente Lesevorgänge (Konfiguration über Umgebungsvariable)

• 📝 JSON-Lines-Log für jeden Tool-Aufruf (tool, args, cached, duration_ms, error)

• 🛠 Stellt die 32 Upstream-Tools plus ein zusammengesetztes Tool diagnostico_completo bereit

• ♻️ Initialisiert die Sitzung neu, wenn das Upstream sie schließt (bekannter n8n-MCP-Bug)

• 🚀 Deployment: Docker / Docker Swarm / Kubernetes / systemd-User-Unit / eigenständiges Python

• 💾 Volume /data für persistente Logs (und zukünftigen Cache)

Warum es existiert

Der in den n8n-Flow von Metrotel eingebettete MCP-Server schließt das Long-Poll-SSE nach einer Zeit der Inaktivität, und Clients wie mcp-remote beginnen mit lautstarken Wiederholungsversuchen. Außerdem lebte das Upstream-Token im Klartext in JSON-Konfigurationen.

Dieser Proxy:

• Beseitigt das Long-Poll: Jeder Tool-Aufruf öffnet seine eigene HTTP-Anfrage zum Upstream und schließt sie nach Abschluss.

• Isoliert das Upstream-Token (X-Prov-MCP-Key): Es lebt nur in der Env-Datei des Proxys, nicht in Claude-Desktop-/Claude-Code-Konfigurationen.

• Fügt Cache für sich wiederholende Lesevorgänge hinzu (z. B. dasselbe contexto_servicio mehrmals innerhalb weniger Minuten).

• Fügt ein zusammengesetztes Tool hinzu, das mehrere Upstream-Tools verkettet und eine Zusammenfassung zurückgibt – so muss das Modell nicht 3 Aufrufe orchestrieren, wenn es nur einen anfordern kann.

Related MCP server: @qelos/better-mcp

Voraussetzungen

• Python 3.10+

• uv (empfohlen, oder pip)

• Netzwerkzugriff auf den Upstream-MCP-Server und den gültigen Header X-Prov-MCP-Key

Schnellstart

Docker (empfohlen, ohne lokalen Build)

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

Oder mit docker-compose.yml aus dem Repository:

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 persistent im Volume prov-data (gemountet auf /data/logs):

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

Nativer HTTP-Modus (ohne 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

Überprüfen:

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"}}}'

Stdio-Modus (für Claude Code / Cursor oder andere Clients, die den Prozess starten)

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

Und in .mcp.json (Claude Code):

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

Deployment in Kubernetes / Docker Swarm

• Kubernetes mit envFrom.secretRef + PersistentVolumeClaim: siehe k8s/README.md.

• Docker Swarm mit in Raft verschlüsselten Secrets + Volume: siehe swarm/README.md.

Deployment als systemd-User-Unit

Vorlage in 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

Damit es Neustarts ohne Login überlebt: sudo loginctl enable-linger $USER.

Verwendung von Claude Desktop

claude_desktop_config.json bearbeiten:

{
  "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>"
      ]
    }
  }
}

Pfade der Konfiguration:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux (Community): ~/.config/Claude/claude_desktop_config.json

Vollständiges Beispiel in examples/claude_desktop_config.example.json.

Umgebungsvariablen

Bereitgestellte Tools

Alle Tools des Upstreams werden unverändert wieder bereitgestellt (zum Zeitpunkt des Schreibens 32), plus ein zusammengesetztes:

• diagnostico_completo(service_number) – ruft contexto_servicio → Topologia → (wenn das Unterprodukt ISI ist) ISI_Check_IP auf und gibt eine gruppierte Zusammenfassung zurück. Nützlich als „Einstiegspunkt“ für eine schnelle Diagnose eines Dienstes anhand seiner Nummer.

Details zu den Upstream-Tools finden Sie in der Postman-Sammlung in postman/.

Cache

Tools, die niemals gecacht werden (aktive Effekte oder volatile Daten):

• Ping_tool

• ATA_Test_1, ATA_Test_2, ATA_Test_3

• Gestion_ACS

• Obtener_backup_equipo

Der Rest wird mit konfigurierbarem TTL (Standard 60s) in den Cache aufgenommen. Der Schlüssel enthält Tool-Name + SHA1-Hash der normalisierten Argumente.

Log

Jeder Tool-Aufruf wird in ~/.cache/prov_mcp_proxy/calls.log als eine JSON-Zeile mit ts, tool, args, cached, duration_ms, error registriert. Automatische Rotation 5 MB × 3.

Sicherheit

Siehe SECURITY.md. Zusammenfassung:

• Bearer im HTTP-Modus obligatorisch (Starlette-Middleware).

• Upstream-Token verlässt den Proxy nie.

• Env-Datei mit Zugangsdaten mit chmod 600, außerhalb von Git.

• .env in .gitignore.

Lizenz

MIT – siehe LICENSE.