MCP-Server

Die Engine enthält einen integrierten MCP-Server (Model Context Protocol), über den KI-Assistenten wie Claude Desktop  oder Claude Code  die Engine fernsteuern können — Prozessmodelle deployen, Prozessinstanzen starten, UserTasks abschließen und den aktuellen Zustand abfragen.

Architektur

Der MCP-Server läuft im selben Prozess wie die Engine und teilt sich den HTTP-Port. Der Endpunkt /mcp wird genau dann registriert, wenn er in der Konfiguration aktiviert ist.

Konfiguration

In der Engine-Konfiguration wird der MCP-Server über den Abschnitt mcp aktiviert:

{
  "mcp": {
    "enabled": true
  }
}

Ohne enabled: true wird kein MCP-Endpunkt registriert.

Transport

Die Engine stellt MCP ausschließlich über HTTP bereit. Der Endpunkt teilt sich den Port mit der Engine:

• URL: http(s)://<engine-host>:<port>/mcp
• Sessions: Jeder Client erhält eine UUID-basierte Session über den Header mcp-session-id
• Resumability: Reconnects sind über den InMemoryEventStore möglich, Sessions überleben aber keinen Engine-Neustart

Der HTTP-Transport unterstützt sowohl Root-Token- als auch Authority-basierte Authentifizierung (siehe unten).

Authentifizierung

Der HTTP-Endpunkt akzeptiert zwei Authentifizierungs-Varianten:

Variante 1: Root Access Token

Für lokale Entwicklungs- und Testszenarien reicht der Root Access Token:

{
  "iam": {
    "allowAnonymousRootAccess": true,
    "rootAccessToken": "mein-geheimer-access-token"
  },
  "mcp": {
    "enabled": true
  }
}

Aufrufe gegen /mcp funktionieren dann auf zwei Arten:

• Mit Header: Authorization: Bearer mein-geheimer-access-token
• Ohne Header: Wenn allowAnonymousRootAccess: true ist, fällt die Engine automatisch auf den Root-Zugriff zurück.

Variante 2: Authority (OpenID Connect)

Für produktive Multi-User-Szenarien wird die Authority für die Authentifizierung verwendet. Es reicht, die baseUrl der Authority zu setzen — die Engine zieht die OAuth-Metadaten automatisch und veröffentlicht sie unter /.well-known/oauth-protected-resource:

{
  "iam": {
    "baseUrl": "https://authority.example.com/",
    "allowAnonymousRootAccess": false
  },
  "mcp": {
    "enabled": true
  }
}

Der MCP-Client führt damit den üblichen OAuth/OIDC-Flow gegen die Authority durch und schickt den erhaltenen Access Token im Authorization: Bearer <token>-Header.

Was muss in der Authority eingerichtet sein?

• Die Authority muss eine erreichbare /.well-known/openid-configuration ausliefern.
• Für den MCP-Client muss ein OAuth-Client registriert sein, der einen für die Engine gültigen Access Token erhalten kann (Authorization Code + PKCE empfohlen).
• Es ist keine spezielle MCP-Scope-Registrierung in der Authority nötig — der Server setzt intern scopes: []. Es genügt ein gültiger Token, der von der Engine via IdentityService.getIdentity validiert werden kann.
• Alle Aufrufe der MCP-Tools werden anschließend gegen die Identity des Users ausgeführt — das normale Berechtigungskonzept der Engine greift unverändert.

Verfügbare Tools

Der Engine MCP-Server stellt folgende Tools bereit:

Prozessmodelle

UserTasks

Laufzeit-Abfragen

MCP-Clients einrichten

Claude Desktop (HTTP via mcp-remote)

{
  "mcpServers": {
    "ProcessCube Engine": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--header",
        "Authorization: Bearer mein-geheimer-access-token"
      ]
    }
  }
}

Claude Code

claude mcp add --transport http processcube-engine http://localhost:8000/mcp \
  --header "Authorization: Bearer mein-geheimer-access-token"

MCP Inspector

Der offizielle MCP Inspector  ist hilfreich zum Debuggen:

npx @modelcontextprotocol/inspector

Im Inspector als Transport „Streamable HTTP” wählen, URL http://localhost:8000/mcp eintragen und im Header-Feld Authorization: Bearer <token> ergänzen.

Technische Details

• Protokoll: MCP 2.0 über JSON-RPC mit StreamableHTTPServerTransport
• Session-Header: mcp-session-id wird per CORS bereits exposed — Browser-Clients funktionieren ohne weitere Konfiguration
• OAuth-Metadaten: Werden bei gesetzter iam.baseUrl automatisch unter /.well-known/oauth-protected-resource ausgeliefert
• User-Identität: Alle Tool-Aufrufe werden gegen die Identity des authentifizierten Users ausgeführt; Berechtigungen folgen den üblichen Engine-Regeln

Bekannte Einschränkungen

• Sessions überleben keinen Engine-Neustart — der Event-Store ist In-Memory.
• deploy-processmodel mit User-Identität unterliegt den gleichen Berechtigungen wie das Deploy über die REST-API.

Weitere Informationen

• Root Access Token — Engine-Absicherung über Bearer Token
• Authority — Identity Provider für die Engine
• Berechtigungskonzept — Wie User-Berechtigungen in der Engine wirken
• Studio MCP-Server — MCP für die Modellier-Umgebung