Workflow/mcp

Workflow-MCP-Server

MCP-Server (Model Context Protocol) des Workflow-Systems. Erlaubt KI-Clients, Workflows zu erstellen, zu bearbeiten, zu starten und mit laufenden Instanzen zu interagieren.

Endpoint & Auth

• URL: https://workflow.flurneuordnung-sachsen.de/mcp (JSON-RPC 2.0 ueber HTTP POST, „Streamable HTTP")
• Auth: HTTP-Header Authorization: Bearer <token>
• Keys: werden im Workflow-Dashboard (dashboard.php → Card „MCP-API-Keys") erstellt. Der Klartext-Token ist nur einmal bei der Erstellung sichtbar (Server speichert nur den SHA-256-Hash).

Scopes

Jeder Key traegt eine Auswahl aus drei Scopes; tools/list zeigt nur erlaubte Tools, tools/call prueft den Scope.

Scope	Tools
read	workflow_list, workflow_get, workflow_validate, workflow_lint, workflow_vars, workflow_instances, workflow_status, workflow_log, task_list, task_doc, task_search, workflow_batch*
author	workflow_create, workflow_update
interact	workflow_start, workflow_interact

Tools

Tool	Zweck
workflow_list	Alle Definitionen (workflows/*.xml) mit ID/Task-Anzahl.
workflow_get	Workflow laden. format=xml (Standard) oder format=struktur — nur der Task-Baum (Typ, id, assign_to, Verzweigung, output_var), rund 70 % weniger Token.
workflow_lint	Statische Prüfung: unbekannte Task-Typen, doppelte ids, fehlende Pflichtparameter, interaktive Tasks ohne <assign_to>.
workflow_vars	Variablen-Landkarte: was der Workflow erzeugt, was er liest, und was gelesen wird, ohne je gesetzt zu sein (Tippfehler).
workflow_batch	Mehrere Werkzeuge in einem Aufruf (z. B. create + lint + start). Jede Operation wird einzeln gegen die Scopes geprüft; Verschachtelung verboten; max. 20 Operationen; bricht standardmäßig beim ersten Fehler ab.
task_list	Alle Task-Typen mit Einzeiler; interaktiv=true = braucht <assign_to>. Optional suche.
task_doc	Doku zu mehreren Task-Typen in einem Aufruf; format=xml|kurz|md.
task_search	Findet den passenden Task zu einer Aufgabenbeschreibung.
workflow_validate	Workflow-XML auf Wohlgeformtheit + Grundstruktur pruefen.
workflow_instances	Laufende/vergangene Instanzen (filterbar nach status/type/assignee).
workflow_status	Detailstatus einer Instanz (Status, Bearbeiter, Kontext, Tokens).
workflow_log	Fachliches Audit-Log einer Instanz.
workflow_create	Neue Definition anlegen (Fehler, wenn Name existiert).
workflow_update	Definition ueberschreiben (mit automatischem Backup).
workflow_start	Neue Instanz starten und ersten Schritt ausfuehren.
workflow_interact	Laufende Instanz weiterfuehren; optional Kontextvariablen einspielen.

Beispiel

curl -s -X POST https://workflow.flurneuordnung-sachsen.de/mcp \
  -H "Authorization: Bearer wfmcp_..." \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"workflow_list\",\"arguments\":{}}}"

Technik

Code unter 0_workflow/mcp/: index.php (Bootstrap + Auth + JSON-RPC-Transport), McpServer.php (Protokoll + Registry + Scope-Enforcement), WorkflowTools.php (Fachlogik), McpKeys.php (Key-Verwaltung, Tabelle WORKFLOW_MCP_KEY). nginx: exakte location = /mcp noetig (sonst faengt der Scan-Blocker den slash-losen Pfad ab).

Verbinden mit claude.ai (OAuth)

Der claude.ai-Connector nutzt OAuth 2.1 (statische Bearer-Keys funktionieren dort nicht). Der Server bildet OAuth auf die MCP-Keys ab.

1. In claude.ai einen Custom Connector anlegen, als URL nur https://workflow.flurneuordnung-sachsen.de/mcp eintragen — KEIN client_id / kein Key in die Connector-Felder.
2. Auf Verbinden klicken. Es öffnet sich eine Anmeldeseite des Workflow-MCP.
3. Dort den wfmcp_…-Key (aus dem Dashboard) eingeben → Zugriff erlauben. Das erteilte Token trägt die Scopes dieses Keys.

Discovery/Endpunkte (automatisch genutzt): /.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server, /register (DCR), /authorize, /token.

Fehler „nur die Startseite erscheint" / „invalid_client": Der Connector wurde mit dem Key als client_id angelegt (ohne Discovery). Connector entfernen und neu hinzufügen — dann registriert sich claude.ai selbst.

Token sparen

Der Server ist darauf ausgelegt, mit wenigen und kleinen Antworten auszukommen:

1. Erst suchen, dann lesen. task_search statt task_list, wenn nur ein Task gesucht wird.
2. Kleinste ausreichende Stufe. task_doc format=xml liefert nur das Beispiel, kurz zusätzlich Zweck und Parametertabelle, md die volle Doku.
3. Struktur statt XML. workflow_get format=struktur reicht zum Verstehen; die XML erst zum Ändern.
4. Bündeln. workflow_batch ersetzt mehrere Roundtrips (create + lint + start).
5. Vor dem Start prüfen. workflow_lint und workflow_vars fangen Fehler ab, die sonst erst eine gescheiterte Instanz und einen weiteren Roundtrip kosten.

* workflow_batch selbst hat den Scope read, prüft aber jede enthaltene Operation gegen die gewährten Scopes — ein read-Key kann darüber kein workflow_create ausführen.