Zum Hauptinhalt springen

MCP-Zugang (SpeamCore als MCP-Server)

Dieser Artikel erklärt, wie SpeamCore sich selbst als MCP-Server (Model Context Protocol) bereitstellt, sodass externe KI-Assistenten — z. B. Claude (Custom Connector) oder ChatGPT — direkt auf SpeamCore zugreifen können. Die operative Verwaltung der Zugangs-Tokens beschreibt die Seite MCP-Zugang — Einstellungen.

Abgrenzung​

SpeamCore nutzt MCP an zwei Stellen — wichtig, beide nicht zu verwechseln:

  • Intern: Der eingebaute KI-Chat verwendet dieselben MCP-Tools lokal.
  • Extern (dieser Artikel): Ein außenstehender Assistent (Claude/ChatGPT) verbindet sich über das Netz mit SpeamCore und ruft dieselben Werkzeuge auf.

Das Problem​

Anwender wollen SpeamCore nicht nur über die eigene Oberfläche bedienen, sondern aus ihrem KI-Assistenten heraus („Lege in SpeamCore ein Angebot für Kunde X an"). Dafür muss SpeamCore von außen erreichbar sein — kontrolliert, authentifiziert und auf die Rechte des Nutzers begrenzt.

Lösung — ein MCP-Endpunkt mit zwei Auth-Wegen​

Der MCP-Server läuft als eigener HTTP-Transport (Standard-Port 4001, env MCP_PORT) neben der normalen API; ein Proxy leitet POST /mcp dorthin. Er ist stateless (keine Session-Bindung), damit Anfragen über mehrere Server-Instanzen hinweg funktionieren.

Die zwei Authentifizierungswege​

1. Bearer-Token (statisch) — für ChatGPT & headless​

Ein im System erzeugtes MCP-Access-Token (Format mcp_…) wird als Authorization: Bearer … mitgeschickt. Dieser Weg gewährt ROOT-Vollzugriff (alle Rechte). Das Token wird nur als SHA-256-Hash gespeichert und erscheint genau einmal bei der Erzeugung. Verwaltung: MCP-Zugang — Einstellungen.

2. OAuth via Keycloak — für Claude Custom Connector​

Claude meldet sich über OAuth 2.0 an (RFC 9728, „Protected Resource"). SpeamCore veröffentlicht dazu öffentlich die Metadaten unter /.well-known/oauth-protected-resource; der Login läuft gegen den Keycloak-Realm. Anschließend wirkt der Zugriff mit den Rechten des angemeldeten Nutzers — nicht ROOT. Die Rollen werden dabei aus dem Keycloak-userinfo-Endpunkt aufgelöst (die APP_SPEAMCORE_*-Rollen sind zu groß für das Access-Token).

WegIdentitätRechteTypischer Einsatz
Bearer-Tokendas TokenROOT (alles)ChatGPT, Automatisierung, Headless
Keycloak-OAuthangemeldeter Nutzerdessen RolleClaude Custom Connector

Was ein externer Assistent tun kann​

Über MCP stehen dieselben Werkzeuge zur Verfügung wie im internen KI-Chat (rund 80 Tools — Angebote/Aufträge anlegen, Abwesenheiten, Berechnungen u. v. m.). Jeder Tool-Aufruf wird CASL-geprüft: Beim Keycloak-Weg gegen die Nutzer-Rolle, beim Bearer-Token gegen die ROOT-Ability. Es gibt keine Abkürzung an den Geschäftsregeln vorbei — alles läuft durch dieselbe Service-Schicht wie die REST-API.

Sicherheit​

Zusätzlicher Schutz: Über die Umgebungsvariable MCP_ALLOWED_HOSTS wird DNS-Rebinding abgewehrt.

Architektur / Komponenten​

Backend​

  • MCP-Server (@modelcontextprotocol/sdk) auf Port 4001, Endpunkt POST /mcp, stateless.
  • Auth-Gateway (mcpAuthMiddleware): unterscheidet mcp_-Bearer-Token von Keycloak-JWT.
  • Modell mcpAccessToken (Hash, Prefix, Ablauf, Widerruf) + Endpoints /mcp-access-tokens (CASL McpAccessToken).
  • OAuth-Metadaten unter /.well-known/oauth-protected-resource.

Frontend​

Anti-Pattern (was NICHT machen)​

  • ❌ Ein Bearer-Token ohne Ablauf oder dauerhaft in einem Skript hinterlegen.
  • ❌ Ein ROOT-Token weitergeben, wenn der nutzergebundene Keycloak-Weg reicht.
  • ❌ Den MCP-Port 4001 direkt ins Internet stellen, ohne Proxy + MCP_ALLOWED_HOSTS.

Verwandte Doku​