Zum Inhalt springen
EmpCo-UWG Monitor

EmpCo-UWG Monitor

MCP-API

Referenz des MCP-Endpunkts für KI-Werkzeuge mit MCP-Connector.

Ein nativer MCP-Endpunkt (Model Context Protocol) für KI-Werkzeuge mit eigenem MCP-Connector – ChatGPT, Claude, Microsoft Copilot Studio. Für die REST-API mit demselben Inhalt siehe die REST-Dokumentation.

Endpunkt

POST https://claims.agent-services.at/v1/mcp – Streamable HTTP, JSON-RPC 2.0 (tools/list, tools/call). Der Pfad ohne Plattform liefert die allgemeinen Regeln und ist der Zugang des Plugins für ChatGPT und Claude. Ein Plattform-Pfad /v1/mcp/<plattform> (chatgpt, claude oder m365-copilot) wählt die für das jeweilige Werkzeug angepassten Regeln, etwa für den Agenten in Microsoft 365 Copilot und den Connector in Copilot Studio. Zustandslos: jede Anfrage ist ein in sich abgeschlossener Austausch, keine Mcp-Session-Id, keine SSE-Streams – die Antwort ist reines JSON.

Authentifizierung

Drei Wege, je nach Zugang:

  • Lizenz (OAuth): Für ChatGPT, Claude und andere Clients mit OAuth-fähigem MCP-Connector wird der Connector nur mit der URL angelegt. Beim ersten Aufruf antwortet der Server mit 401 und einem WWW-Authenticate-Header, der auf /.well-known/oauth-protected-resource/v1/mcp/<plattform> verweist (RFC 9728); der Connector startet daraufhin selbst die Anmeldung, bei der der gekaufte Zugangscode eingegeben wird. Eine Anmeldung gilt für alle Plattform-Pfade.
  • Token einer Kunden-Instanz: Per Header Authorization: Bearer <token> oder Query-Parameter ?api_key=<token> (z. B. für den Connector in Copilot Studio). Den Token stellt der Serverbetreiber aus.
  • Organisationstoken: Per Header X-Empco-Token: <token> (das Plugin sendet ihn aus der Umgebungsvariable EMPCO_MONITOR_TOKEN). Ein leerer Wert oder eine nicht expandierte Variable (${…}) gilt als fehlender Token; die OAuth-Anmeldung bleibt dann möglich.

Tool: fetch_claims_monitor_step

Liefert die Regeldatei und die zugehörigen Wissensbasis-Dateien für einen Verarbeitungsschritt – ein Aufruf pro Schritt statt einem Aufruf pro Datei.

  • Parameter: step; optional platform (Plattform des aufrufenden Werkzeugs, wählt wie ein Plattform-Pfad die Regelvariante; der Pfad hat Vorrang, ein unbekannter Wert wird ignoriert)
  • Erlaubte Werte: die Schritt- und Modul-Kennungen des Regelstands des Zugangs (ein Modul ist ein bei Bedarf nachladbarer Teil eines Schritts); der Einstieg ist report-intake, jede Antwort nennt ihre Folgeschritte im Feld next-steps (ende = kein weiterer Schritt). Ungültige Werte weist das Tool-Schema ab.
  • Antwort: reiner Markdown-Text als Text-Inhalt der Tool-Antwort, mit einem YAML-Frontmatter-Block am Anfang – keine Dateinamen: version (Stand der Regeln), license, fetched-on (Tag des Abrufs in UTC; ein an einem späteren Tag fortgesetztes Gespräch ruft die Regeln vor der nächsten Prüfung neu ab), next-steps (erlaubte Folgeschritte), platform (Plattform, nach der die Regelvariante gewählt wurde: Pfad, Parameter oder zugeordneter Client; sonst fehlt das Feld), variant (Plattform der gelieferten Regelvariante, nur wenn eine geliefert wurde), request-id (Kennung dieser Anfrage; dieselbe steht im Header X-Request-Id jeder Antwort und im Zugriffsprotokoll des Servers, sodass der Support einen Abruf eindeutig zuordnen kann) und, nur bei einer Lizenz über ihrer fairen Nutzung, fair-use-seats (Anzahl der gekauften Plätze).

Fehler

  • 401: kein oder ungültiger Token bzw. Anmeldung
  • 404: unbekannte Plattform im Pfad
  • 405: GET/DELETE – der Endpunkt ist zustandslos und hat keinen Stream

Ein ungültiger Schrittname ergibt keinen HTTP-Fehler, sondern ein Tool-Ergebnis mit isError: true und Fehlermeldung (HTTP 200, wie jede JSON-RPC-Antwort).

Beispiel

curl -X POST https://claims.agent-services.at/v1/mcp/m365-copilot \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"fetch_claims_monitor_step","arguments":{"step":"report-classify"}}}'