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_instances, workflow_status, workflow_log
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	XML-Definition eines Workflows.
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.