Entwickler-Referenz

V8Chat MCP Schnittstelle

Technischer Vertrag für die Anbindung MCP-kompatibler Clients und Agenten an V8Chat. Persönliche Self-Service-Schlüssel sind an einen Arbeitsbereich gebunden; Partner-Service-Tokens können – sofern erlaubt – Organisationen routen.

MCP-Übersicht Nutzer-Dokumentation Server-Metadaten

Kurzüberblick

Endpunkt: https://api.v8chat.com/mcp
Transport: streamable-http
Metadaten: https://api.v8chat.com/.well-known/mcp/server.json
Authentifizierung: Authorization: Bearer <token>
Aktuelles Protokoll: 2026-07-28
Fallback für ältere Clients: 2025-11-25

Authentifizierung

Self-Service-Nutzer erzeugen im Member-Bereich unter „KI-Verbindungen (MCP)“ einen persönlichen Zugangsschlüssel. Er wird als Bearer-Token gesendet. Der vollständige Schlüssel wird nur einmal angezeigt; V8Chat speichert ausschließlich seinen SHA-256-Hash. Partner-Service-Tokens nutzen denselben Bearer-Header; bestehende X-Partner-*-Header bleiben für Partnerintegrationen unterstützt.

Präfix persönlicher Zugangsschlüsselv8m_…

Unterstützte Protokollgenerationen

Aktuell: 2026-07-28

server/discover wird für die Discovery verwendet. Bei aktuellen Requests prüft V8Chat MCP-Protocol-Version und verlangt Mcp-Method; bei tools/call muss zusätzlich Mcp-Name zum JSON-RPC-Body passen.

Legacy-Fallback: 2025-11-25

initialize bleibt für ältere Clients verfügbar. Die Antwort enthält eine Mcp-Session-Id. Wo möglich sollte die aktuelle Protokollgeneration verwendet werden.

Discovery und Lifecycle

curl -sS 'https://api.v8chat.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: server/discover' \
  --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{}}'

curl -sS 'https://api.v8chat.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Tools

v8chat.search

Eingabe: { query: string, limit?: 1..10 }

Sucht Funktionen, die für den authentifizierten Kontext freigegeben sind.

v8chat.describe

Eingabe: { capability: string }

Liefert vor der Ausführung den Eingabevertrag einer freigegebenen Funktion.

v8chat.execute

Eingabe: { capability: string, input: object, options?: object, idempotency_key?: string, organization_id?: string }

Führt die Funktion über die gemeinsame V8Chat-Runtime aus. organization_id ist nur für Partner vorgesehen; Self-Service-Zugriff ist bereits an den Arbeitsbereich gebunden.

v8chat.status

Eingabe: { job_id: string, organization_id?: string }

Liest den Status asynchroner Jobs, die von einer Ausführung zurückgegeben wurden.

Request-Beispiele

Allgemeine Client-Konfiguration

{
  "mcpServers": {
    "v8chat": {
      "url": "https://api.v8chat.com/mcp",
      "headers": {
        "Authorization": "Bearer v8m_…"
      }
    }
  }
}

Suchen

curl -sS 'https://api.v8chat.com/mcp' \
  -H 'Authorization: Bearer v8m_…' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: v8chat.search' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"v8chat.search","arguments":{"query":"translate text","limit":5}}}'

Ausführen

curl -sS 'https://api.v8chat.com/mcp' \
  -H 'Authorization: Bearer v8m_…' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: v8chat.execute' \
  --data '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"v8chat.execute","arguments":{"capability":"translate.text","input":{"text":"Hello","to":"de"},"idempotency_key":"client-123"}}}'

Initialisierung für ältere Clients

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}

Fehler und Retry-Verhalten

Protokollfehler werden als JSON-RPC-Fehlerobjekte zurückgegeben. Authentifizierungs- und Richtlinienfehler tragen zusätzlich passende HTTP-Statuscodes. 429, 502, 503 und 504 können erneut versucht werden; sofern vorhanden wird Retry-After gesendet.

Code	Bedeutung
`mcp_self_service_disabled`	Der persönliche MCP-Zugriff ist für das Konto ausgeschaltet.
`invalid_mcp_token`	Der Zugangsschlüssel ist ungültig, widerrufen oder nicht mehr nutzbar.
`workspace_access_required`	Der Nutzer hat keinen Zugriff mehr auf den zum Schlüssel gehörenden Arbeitsbereich.
`organization_mismatch`	Die angeforderte Organisation bzw. der Arbeitsbereich passt nicht zum authentifizierten Gültigkeitsbereich.
`mcp_header_mismatch`	Die MCP-Routing-Header passen nicht zur JSON-RPC-Anfrage.
`unsupported_mcp_version`	Die angeforderte Protokollversion wird nicht unterstützt.

Sicherheit und Gültigkeitsbereich

Self-Service-MCP ist pro Nutzer standardmäßig ausgeschaltet.
Persönliche Schlüssel sind an genau einen Nutzer und einen V8Chat-Arbeitsbereich gebunden.
Beim Ausschalten von MCP werden bestehende persönliche Schlüssel sofort blockiert.
Beim Rotieren werden vorherige aktive Schlüssel für Nutzer und Arbeitsbereich widerrufen.
Die Ausführung nutzt denselben Capability-, Policy-, Idempotency- und Job-Runtime-Pfad wie die Partner-REST-Schnittstelle.
Bei Self-Service-Schlüsseln kann organization_id nicht zum Wechsel in einen anderen Arbeitsbereich verwendet werden.