gpu-broker-mcp

Ein zustandsloser MCP-Server, der GPU-Compute-Zugriff für KI-Agenten vermittelt. Agenten entdecken Knoten, reservieren Kapazität, senden Inferenzaufträge und rufen Ergebnisse über vier MCP-Tools ab – ohne SSH-Schlüssel, Knoten-IPs oder Provider-APIs direkt zu verwalten.

SDK: mcp==2.0.0 (Python SDK v2, mcp.server.MCPServer) Ziel-Spezifikation: MCP-Spezifikation Revision 2026-07-28 Transport: Streamable HTTP, zustandsloser Modus (stateless_http=True, json_response=True). Keine Sitzungen, kein Mcp-Session-Id, kein Sticky-Routing.

Architektur

┌─────────────────────────────────────────────────────────────┐
│  Agent (MCP client)                                         │
│  Calls: list_nodes → reserve_node → dispatch_inference      │
│         → get_result (poll)                                 │
└────────────────────────┬────────────────────────────────────┘
                         │ JSON-RPC over Streamable HTTP
                         │ (stateless, any replica)
┌────────────────────────▼────────────────────────────────────┐
│  gpu-broker-mcp server                                      │
│                                                             │
│  ┌──────────────────┐  ┌──────────────────┐                 │
│  │ HMAC-SHA256       │  │ NodePool ABC     │                 │
│  │ Handle signing    │  │  ├ FakeNodePool   │                │
│  │ & validation      │  │  └ VastNodePool   │                │
│  └──────────────────┘  └──────────────────┘                 │
│                                                             │
│  ┌──────────────────┐  ┌──────────────────┐                 │
│  │ Error taxonomy    │  │ JobStore ABC     │                 │
│  │ (single enum,     │  │  └ InMemoryStore  │                │
│  │  structured JSON) │  │    (per-replica)  │                │
│  └──────────────────┘  └──────────────────┘                 │
└────────────────────────┬────────────────────────────────────┘
                         │ SSH (VastNodePool only)
┌────────────────────────▼────────────────────────────────────┐
│  GPU node (e.g. Vast.ai RTX 3090)                           │
│  Runs inference workload, returns stdout                    │
└─────────────────────────────────────────────────────────────┘

Der Broker läuft lokal. Er ist ein Client der GPU-Knoten, nicht auf ihnen resident – er führt CPU-gebundenes HMAC-Signieren und JSON-Serialisierung aus, nichts, was von einer GPU profitiert.

Related MCP server: clausius

Warum signierte Handles statt Sitzungen

Der Reservierungszustand steckt im Handle selbst: ein base64-kodiertes JSON-Payload (Knoten-ID, Ablaufzeit, Gültigkeitsbereich), verkettet mit seiner HMAC-SHA256-Signatur. Das Geheimnis stammt aus GPU_BROKER_SECRET, und der Server weigert sich zu starten, wenn es nicht gesetzt ist.

Das bedeutet, dass jede Replik, die das Geheimnis teilt, ein Handle validieren kann, das sie nie ausgestellt hat. Es gibt keine Sitzungstabelle, keinen Mcp-Session-Id-Header und keine Sticky-Routing-Anforderung. Ein Load Balancer kann jede Anfrage an jede Replik weiterleiten. Handles sind bereichsgebunden (reserve vs. task), sodass ein Reservierungs-Handle nicht als Task-ID wiederverwendet werden kann oder umgekehrt – Missbrauch führt zu HANDLE_SCOPE_INVALID.

Was der In-Memory-JobStore über Repliken hinweg verliert, ist die Job-Statusabfrage: Replik B kann dir nicht den Status eines Jobs mitteilen, der an Replik A gesendet wurde. Dies ist eine Anforderung an ein gemeinsames Backend (Redis, Postgres) und kein Fehler im zustandslosen Design. Die Signaturvalidierung – der sicherheitskritische Teil – ist vollständig portabel.

Tools

Tool-Signaturen sind über Backends hinweg stabil – der Austausch von FakeNodePool gegen VastNodePool ändert keine client-sichtbare Schnittstelle.

Hinweis zum Caching

list_nodes gibt meta.ttlMs und meta.cacheScope im Tool-Ergebnis zurück. Dies ist eine lokale Konvention – SEP-2549 regelt tools/list- und resources/list-Antworten, nicht einzelne tools/call-Ergebnisse. Clients, die das erkennen, können cachen; andere rufen einfach erneut auf.

Routing-Header

Der Server sendet Mcp-Method- und Mcp-Name-Header für das Gateway-Routing, erzwingt sie aber nicht serverseitig. Der Durchsetzungspunkt ist der Edge (API-Gateway, Reverse-Proxy), nicht der Broker selbst.

Fehler-Taxonomie

Jeder Tool-Fehler gibt strukturiertes JSON mit code, message, retryable und optional retry_after_seconds zurück. Agenten sollten auf code verzweigen, niemals auf message – Nachrichten sind menschenlesbare Diagnosen und können sich ändern.

Die Host-Ebenen-Fehler (NVML_VERSION_MISMATCH bis DOCKER_SOCKET_PERMISSION_DENIED) werden aus SSH-stderr-Zeichenketten in vast.py:_raise_from_stderr abgebildet. Die Muster basieren auf bekannten Fehlermodi von Vast.ai-GPU-Hosts, wurden aber noch nicht gegen erfasste Produktionszeichenketten validiert. Aufgabe 3 wird wörtliche Fehlerausgaben erfassen und die Abgleichsmuster verfeinern.

Schnellstart

Fake-Modus (keine GPU, kein API-Schlüssel)

export GPU_BROKER_SECRET="any-secret-string"
python src/gpu_broker/server.py
# Server at http://127.0.0.1:8000/mcp

Vast.ai-Modus (echte GPU)

export GPU_BROKER_SECRET="any-secret-string"
export VASTAI_API_KEY="your-vast-api-key"

# Find and rent a node
python vast_manage.py search --gpu "RTX 3090" --max-price 0.30
python vast_manage.py rent <offer_id>
python vast_manage.py wait <instance_id>

# Start the broker (auto-detects VASTAI_API_KEY)
python src/gpu_broker/server.py

# When done
python vast_manage.py destroy <instance_id>

Tests ausführen

uv run pytest tests/ -v

Die Tests umfassen:

• Handle-Roundtrip (reserve → dispatch → get_result)

• Ablehnung manipulierter Signaturen

• Ablehnung abgelaufener Handles

• Ablehnung von Bereichsfehlern

• JOB_NOT_FOUND für replikübergreifende Abfragen

• Subprozess-Zustandslosigkeitstest: startet drei echte HTTP-Server (A und B teilen ein Geheimnis, C hat ein anderes), sendet einen Task von A, bestätigt, dass A pending zurückgibt, B JOB_NOT_FOUND und C HANDLE_SIGNATURE_INVALID

• Startverweigerung bei nicht gesetztem Geheimnis

• Serialisierungs-Roundtrip für jede Fehlervariante

Aktueller Umfang und Einschränkungen

Dies ist ein funktionierender Prototyp, kein Produktionssystem.

• FakeNodePool gibt eine statische Liste von drei Knoten zurück und führt keine echte Inferenz aus. Nützlich zum Testen von Tool-Interaktionen und Handle-Mechanik.

• VastNodePool fragt die Vast.ai-API nach laufenden Instanzen ab und sendet Inferenz per SSH. Es leistet echte Arbeit, hat aber kein Verbindungspooling, keine Wiederholungslogik und keine SSH-Schlüsselverwaltung über die Systemstandardwerte hinaus.

• InMemoryJobStore verliert bei Neustart den gesamten Zustand und kann Job-Status nicht über Repliken teilen. Eine Produktionsbereitstellung benötigt ein gemeinsames Backend (Redis, Postgres).

• Die Fehler-Taxonomie-Muster für Host-Ebenen-Fehler sind fundierte Vermutungen basierend auf bekannten Fehlermodi. Sie müssen gegen echte erfasste stderr-Ausgaben von GPU-Hosts validiert werden.

• Keine Authentifizierung am MCP-Endpunkt selbst – jeder Client, der den HTTP-Port erreichen kann, kann Tools aufrufen. Produktion benötigt eine Auth-Schicht davor.

• Kein Rate-Limiting, keine Begrenzung der Anfragegröße, kein Audit-Logging.