PicX MCP Server

Ein FastMCP 4 Server, der PicX Studio Bild- und Videogenerierung jedem MCP-Client über sitzungsloses Streamable HTTP bereitstellt.

Gehosteter Endpunkt: https://mcp.picxstudio.com/mcp ⚠️ Noch nicht bereitgestellt. Der Dienst läuft derzeit lokal; der Produktionsbetrieb ist geplant (siehe PLAN-MCP Phase 6).

Warum FastMCP 4

Das Thema von FastMCP 4 ist „zustandsloser Transport ohne zustandslosen Anwendungscode“. Die von FastMCP 4 anvisierte Protokollrevision — 2026-07-28 — entfernt die Sitzungsaffinität vollständig. Jede Replik hinter einem gewöhnlichen Load Balancer kann jede Anfrage bedienen. Keine Sticky Sessions, keine Cookie-Weiterleitung, kein gemeinsamer In-Memory-Zustand zwischen Anfragen.

Das ist für uns nicht optional: MCP-Clients (Cursor, Claude Code) verwenden intern fetch() und leiten Set-Cookie-Header nicht weiter, daher kann Sticky-Session-Lastverteilung unabhängig von der LB-Konfiguration nicht funktionieren. Der stateless_http=True-Modus von FastMCP 4 ist der einzige gangbare Weg zur horizontalen Skalierung.

FastMCP 4 verhandelt außerdem beide Protokollzeitalter (Legacy-SSE und modernes Streamable HTTP) aus einer einzigen Bereitstellung, sodass ältere Clients nicht auf der Strecke bleiben.

Related MCP server: LLM Wiki Streamable HTTP MCP Server

Tool-Status

Bekannte Einschränkungen

• Videomodi: Es sind nur die Modi text, image und reference verfügbar. Die Modi frames, extend, lipsync und edit erfordern Felder, die das Parameterschema ohne dedizierte Validierung nicht sicher serialisieren kann – ihre Bereitstellung würde verwirrende 422-Fehler der API hervorrufen.

• picx_list_generations: Implementiert und bereit zur Aktivierung, aber blockiert, bis das Backend GET /v1/generations ausliefert.

• Tariflimits: Die Sichtbarkeit von Rate-Limits pro Tarif und Tageslimits ist möglicherweise nicht verfügbar, bis der Konto-Endpunkt sie bereitstellt.

• OAuth: Noch nicht angebunden (Phase 5). Die Authentifizierung per API-Schlüssel funktioniert heute.

Schnellstart

# Clone and install
git clone https://github.com/Type-Think-AI/picx-mcp.git
cd picx-mcp
uv sync

# Configure
cp .env.example .env
# Edit .env — set PICX_API_KEY to your key from https://ai.picxstudio.com/api

# Run
python -m picx_mcp

Der Server startet unter http://localhost:8000. Der MCP-Endpunkt befindet sich unter /mcp, der Health-Check unter /health.

Client-Konfiguration

Claude Desktop

{
  "mcpServers": {
    "picx": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer pxsk_your_api_key_here"
      }
    }
  }
}

Claude Code

{
  "mcpServers": {
    "picx": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer ${PICX_API_KEY}"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "picx": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer ${PICX_API_KEY}"
      }
    }
  }
}

VS Code (Copilot)

{
  "mcp": {
    "servers": {
      "picx": {
        "type": "http",
        "url": "http://localhost:8000/mcp",
        "headers": {
          "Authorization": "Bearer ${PICX_API_KEY}"
        }
      }
    }
  }
}

Ersetzen Sie localhost:8000 durch mcp.picxstudio.com, sobald der gehostete Dienst live ist.

Authentifizierung

Zwei Authentifizierungsebenen, ein Durchsetzungspunkt:

Beide Pfade münden in dieselbe /v1-Durchsetzung: Scopes, Rate Limits, tägliches Kreditlimit, Anfrageprotokollierung. Es gibt keinen schwächeren zweiten Pfad.

Der MCP-Server speichert niemals eine Anmeldeinformation. Er leitet den API-Schlüssel des Aufrufers (oder den aufgelösten Sitzungsschlüssel) an /v1 weiter. Ein Schlüssel, den er nie speichert, ist ein Schlüssel, den er nicht preisgeben kann.

Architektur

MCP Client ──▶ PicX MCP Server ──▶ api.picxstudio.com/v1 ──▶ Provider + Storage
                 (this repo)         (owns everything below)

Dieser Server ist eine Übersetzungsschicht. Er wandelt MCP-Tool-Aufrufe in /v1-API-Aufrufe um und übersetzt Ergebnisse zurück in Ressourcenlinks. Er tut absichtlich NICHT:

• Einen Modellanbieter direkt aufrufen. /v1 besitzt die Anbieterintegration.

• Geld anfassen. /v1 verwaltet Kreditabzug, Preisgestaltung, Rabatte, Idempotenz und Erstattung bei Anbieterfehlern.

• Medien speichern. Ergebnisse sind dauerhafte CDN-URLs; nichts wird zwischengespeichert oder weitergeleitet.

• Sitzungszustand verwalten. stateless_http=True bedeutet, dass jede Anfrage in sich abgeschlossen ist.

Warum nicht Anbieter direkt aufrufen? /v1 führt bereits aus: Authentifizierung → Rate Limit → Tageslimit → Scope-Prüfung → Preis aus Konfiguration → Rabatt anwenden → Idempotenzprüfung → Kredite abziehen → Anbieter aufrufen → Erstattung bei Fehler → Anfrageprotokoll schreiben. Jede Nachimplementierung hiervon würde irgendwann abweichen, und eine Abweichung in der Geldlogik ist ein Abrechnungsfehler — still und dauerhaft vertrauenszerstörend.

Multi-Replica-Tests

Die gesamte These hinter der Wahl von FastMCP 4 ist, dass keine Sitzungsaffinität erforderlich ist. Um es lokal zu beweisen:

docker compose up --scale app=2

Dies startet zwei Server-Repliken hinter einem Round-Robin-Proxy sowie eine Valkey-Instanz. Der Test, der die Architektur validiert:

1. Starten Sie einen interaktiven Tool-Aufruf auf Replik A (löst InputRequiredResult aus)

2. Setzen Sie die Interaktion fort – die Anfrage landet auf Replik B

3. Sie ist erfolgreich, weil REQUEST_STATE_KEY gemeinsam genutzt wird

Wenn REQUEST_STATE_KEY nicht gesetzt ist (oder sich zwischen Repliken unterscheidet), schlagen interaktive Runden mit einem Zustandsvalidierungsfehler fehl. Das ist beabsichtigt – es macht Fehlkonfiguration laut statt subtil falsch.

Umgebungsvariablen

Ehrliche Grenzen

• Jede Generierung kostet Kredite. Dieser Server umgeht keine Preisgestaltung – genau das ist der Punkt.

• Obergrenze pro Sitzung (Standard: 2000 Kredite) begrenzt einen per Prompt injizierten Kreditabfluss. Dies ist unabhängig vom Tageslimit des Kontos (13.000/Tag).

• Bestätigungsaufforderung oberhalb des Schwellenwerts (Standard: 200 Kredite) vor der Ausgabe.

• Keine Offline-/lokale Generierung. Jede Generierung erreicht die PicX-API über das Netzwerk.

• Video ist asynchron. Selbst wenn task=True das Polling verbirgt, dauert die Generierung Minuten – ein Agent muss warten.

• Rate Limits gehören der API, nicht diesem Server: standardmäßig 60 Anfragen/Min., 10.000 Anfragen/Tag. Der MCP-Server fügt kein zusätzliches Limit hinzu.

• Der Server befindet sich in der Beta. FastMCP 4 ist 4.0.0b3. Rechnen Sie mit rauen Kanten.

Lizenz

MIT