MCP-Server anbinden

Was der Server ist, und was er nicht ist

Der MCP-Server ist eine dünne Schicht über /api/v1. Er hat kein eigenes Fachwissen und keinen Datenbankzugriff: Jedes Werkzeug ruft die REST-API auf. Rechteprüfung, Marken-Abgrenzung und Protokollierung passieren serverseitig, genau wie bei einem Menschen in der Oberfläche.

Daraus folgt die wichtigste Eigenschaft: Ein KI-Aufruf kann nie mehr als die Identität, unter der er läuft. Fehlt das Recht, antwortet die Operation mit 403 — auch wenn das Token gültig ist.

Transport ist ausschließlich stdio. Der Client startet den Prozess selbst. Es gibt keinen Daemon, keine Unit und keinen HTTP-Endpunkt. Der frühere HTTP-Transport wurde entfernt, weil er keine Aufrufer-Authentifizierung hatte.

1. Eigene Identität anlegen

Die KI bekommt einen eigenen Benutzer, keinen persönlichen Account. Unter Einstellungen → Mitglieder anlegen, aktivieren und per Mitgliedschaft genau die Rolle und Marke zuweisen, die sie braucht. Ohne Mitgliedschaft lehnen alle Prüfungen das Token ab.

2. Token erzeugen

php bin/console auth:mcp-token mcp@deine-firma.de
php bin/console auth:mcp-token mcp@deine-firma.de --ttl 7 --name "Claude Desktop"
php bin/console auth:mcp-token mcp@deine-firma.de --scope customer.read --scope workitem.list

Ohne --ttl gilt das Token 30 Tage, 0 bedeutet unbegrenzt. Der Wert wird einmal ausgegeben; gespeichert wird nur sein Hash. Widerrufen lässt er sich jederzeit über POST /api/v1/api-tokens/{ulid}/revoke.

3. Client konfigurieren

Beispiel für Claude Desktop (claude_desktop_config.json, unter macOS in ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "octibiz": {
      "command": "php",
      "args": ["/pfad/zu/octibiz/mcp/bin/server.php"],
      "env": {
        "MCP_API_BASE_URL": "https://deine-instanz.example",
        "MCP_API_TOKEN": "octi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Mehr braucht es nicht. Die Konfiguration läuft ausschließlich über diese beiden Umgebungsvariablen: keine Konfigurationsdatei, keine Geheimnisse im Repository.

4. Die drei generischen Werkzeuge

Statt hunderter Werkzeug-Schemata im Kontext des Clients gibt es drei, über die jede Operation erreichbar ist:

Werkzeug	Wofür
`list_operations`	Operationen suchen, gefiltert nach Bereich oder Stichwort
`describe_operation`	Eine Operation samt Parametern und Rechten beschreiben
`invoke_operation`	Sie ausführen

Gespeist werden sie aus dem OpenAPI-Dokument der laufenden Instanz. Erzeugt wird der Katalog mit php bin/console app:mcp:export-operations; nach jeder API-Änderung gehört er nachgezogen. Fehlt er, läuft der Server weiter und bietet nur die kuratierten Werkzeuge an.

Was im Protokoll landet

Jede schreibende Aktion trägt die Urheber-Art ai und die Identität des Tokens. Wer im Nachhinein wissen will, ob ein Mensch oder ein Agent gehandelt hat, sieht es im Audit-Protokoll — ohne dass jemand daran denken musste, es mitzuschreiben.

Grenzen

Der Katalog kennt die Bootstrap-Strecken nicht: Anmeldung, öffentliche Formulare und

Webhook-Empfänger stehen bewusst nicht als Werkzeug zur Verfügung.

Ein Token ohne Mitgliedschaft ist wertlos. Das ist Absicht, nicht Bequemlichkeit.

mcp.connect · Gilt ab Version 0.5.4