MCP¶

HostAdmin stellt einen Model Context Protocol Server bereit, mit dem KI-Agenten (Claude Desktop, eigene Anthropic-SDK-Skripte, n8n MCP-Nodes etc.) lesend auf Kunden, Services, Rechnungen und Server zugreifen können.

Endpoint¶

https://ihre-domain.de/mcp

Transport: HTTP / Streamable HTTP (kein stdio, kein WebSocket)
Authentifizierung: Bearer-Token eines Service Accounts mit allow_mcp = true

Authorization: Bearer <token>

MCP ist read-only

Der erste Release stellt ausschließlich Read-Tools bereit. Schreibende Operationen (Kunden anlegen, Rechnungen markieren, Billing-Run starten …) folgen in einer späteren Iteration. Daher reicht für jeden MCP-Token die Ability read.

Erforderliche Account-Konfiguration¶

Im Service-Account muss gesetzt sein:

Feld	Wert
Aktiv	✓
MCP	✓
Berechtigungen	mindestens `read`
Ablaufdatum	leer oder in der Zukunft

→ Schritt-für-Schritt-Anleitung zum Anlegen siehe System > Service Accounts.

Verfügbare Tools¶

Tool	Zweck
`find-customer-tool`	Suche nach Name, E-Mail, Firma oder Kundennummer
`get-customer-tool`	Volldetails inkl. aktiver Services und offener Rechnungen
`list-services-tool`	Customer Services mit Filter (Customer, Status, Type, Domain)
`list-invoices-tool`	Rechnungen mit Filter (Customer, Status, Datumsbereich)
`list-servers-tool`	Alle Server mit Hostname, IP, Stack, Status

Detaillierte Schemas und Beispiele unter Tools.

Client-Setup¶

Konfiguration für gängige MCP-Clients (Claude Desktop, n8n, Anthropic SDK, …) siehe Client-Setup.

Auth-Verhalten¶

Status	Bedeutung
`401 Unauthenticated`	Kein Token, ungültiger Token, abgelaufener Token, deaktivierter / gelöschter Service Account
`403 Forbidden`	Token gültig, aber `allow_mcp = false` oder Ability `read` fehlt

Fehlerdiagnose¶

„Method not found" / leere Tool-Liste: Vermutlich Initialize/Tools/List-Phase nicht durchgeführt — Client-spezifisch debuggen. Lokal mit curl kann die tools/list-Methode (siehe Tools) gegengeprüft werden.
401 mit gültig wirkendem Token: Der angezeigte Klartext-Token ist 50 Zeichen lang ({id}|{40 random}{8 crc}). Beim Kopieren werden gerne Zeichen abgeschnitten. Im Modal Token erstellt den Copy-Button rechts im Feld nutzen — dann ist der gesamte Token in der Zwischenablage.
403 MCP access not enabled for this service account: Im betreffenden Service Account ist der Toggle „MCP" nicht aktiv. Bearbeiten → MCP einschalten → speichern.
403 Missing ability: read: Der Service Account hat keine read-Ability gesetzt — oder der Token wurde mit nur einer Untermenge erzeugt, die read nicht enthält. Account oder Token entsprechend ergänzen / neu ausstellen.

Verhalten beim Widerrufen¶

Account auf inaktiv schalten → alle Requests des Accounts schlagen ab sofort mit 401 fehl
Token einzeln widerrufen → nur dieser eine Token ungültig
Account in den Papierkorb verschieben (Soft Delete) → alle Tokens werden sofort widerrufen, Account bleibt im Audit