Differences

This shows you the differences between two versions of the page.

--- 262:mcpserver [2026/10/20 09:44] – [Stages MCP Server] Fuhl, Alexander
+++ 262:mcpserver [2026/10/28 10:46] (current) – Policnik, Florian
@@ Line 5: / Line 5: @@
 Through our MCP server, AI systems can access process data managed in Stages for various purposes and use cases.
-In the currently provided MCP solution Stages provides access to a **valid versions of workspaces only**.
+In the currently provided MCP solution Stages provides access to **valid versions of workspaces only**.
-===== How it works =====
-The Stages MCP server uses the [[262:collector_data_rest_api|Stages Collector Data API]]. Data that should be provided via MCP need to be provided by one or multiple Stages Collector jobs. The MCP server then provides the AI-systems with the collected data.
+===== What it offers =====
-===== How to get started =====
+The Stages MCP server grants access to the valid versions of all workspaces the authenticated user has access to and for which the "MCP" permission is granted.
-This feature is currently in beta. It requires Stages 7.12.5.1 or later, or Stages 26.1.0.0 or later.
+Currently it offers 10 tools to browse and search workspaces and elements. This is subject to change.
-Please request the current version of the MCP package from Stages support. You will receive an MCP server, script, and configuration suitable for processes based on the unified configuration metamodel.
+===== Availability =====
-==== Installation =====
+The Stages MCP server is integrated into Stages 26.2.0.0 and later.
-  * Stop Stages
+Note: Stages 7.12.5.1 or later and Stages 26.1.0.0 or later had a beta implementation of this feature that worked quite differently.
-  * Activate [[262:api-tokens|API tokens in Stages]]
-  * Add ''mcp-server.properties'' to the Stages conf folder
-  * Choose the right WAR file:
-    * Stages 7.12: ''mcp-web-tomcat-9-*.war''
-    * Stages 26.1: ''mcp-web-tomcat-10-*.war''
-    * Extract the WAR file to ''stages/tomcat/webapps/mcp''. Ensue that the folders ''META-INF'' and ''WEB-INF'' are directly in the ''mcp'' folder
-  * Start Stages
-  * Go to the Company workspace and add the workspace variable ''mcpDefaultWorkspace''. Set the value to the ID of the workspace that you want to access.
-  * In Stages go to Administration -> Jobs and create a job for MCP (e.g. "mcp")
-  * Upload the ''mcp.js'' file to MCP job
-  * Run the job once
-  * Specify a cron expression to keep the data updated
-If Stages is running, you can check the path ''/mcp/status'' on your Stages server to see if the MCP server is running. For example: ''<nowiki>https://stages.example.com/mcp/status</nowiki>''
+===== Configuration =====
-==== Configure credentials =====
+Authentication is currently available only through an external identity provider (IdP), such as Microsoft Entra ID or Keycloak.
-Access to the MCP server and Stages data is protected. A [[262:api-tokens|personal Stages API token]] is required to access the REST API. The user must have the following privileges:
+==== IdP configuration ====
-  * Process Modeler
+To enable MCP, add a resource configuration to your IdP, typically by creating an app or client registration. If you already use OIDC, you can use that configuration.
-  * CollectorData Read and Create permission
-  * Permission according to the data collector (e.g. Process Read)
+Add the custom scope to the client:
+''stages:mcp:read''
-==== Configure AI system =====
+Depending on your IdP, you may find this under "Expose an API" or "Client scopes". In Microsoft Entra ID, specify the Application ID URI using this format:
-Configuration depends on Stages version
+''<nowiki>https://stages.example.com/stages/api/1/mcp</nowiki>''
-=== Stages 7.12 / Tomcat 9 ===
+Use this value as the audience in the configuration. In other systems, the audience may be the application's client ID. Stages checks this value against the JWT's audience claim.
-Currently Stages MCP server supports Server-Sent Events (SSE) protocol for Tomcat 9 version. The endpoint is ''/mcp/sse'', e.g.:
+==== Stages configuration ====
-''<nowiki>https://stages.example.com/mcp/sse</nowiki>''
+Add the following to the ''<authentication>'' section in ''config.xml'':
-The API token that was created must be provided to the MCP server via the header ''StagesToken''.
+<code xml>
+<method type="JWT" name="myIdp">
-An example MCP configuration:
+    <properties>
+        <property name="discoveryURI" value="${idp.myIdp.oidc.discovery.url}" />
-<code javascript>
+        <property name="audience" value="${idp.myIdp.oidc.audience}" />
-{
+        <property name="usernameAttribute" value="upn" />
-  "command": "npx",
+    </properties>
-  "args": [
+    <filters>
-    "mcp-remote",
+        <attribute-match id="*" pattern="*" defaultUserGroupsUsername="${user.default.username}"
-    "https://stages.example.com/mcp/sse",
+            defaultLicenseType="${user.default.licenseType}" autocreateUser="${saml.autocreate}" />
-    "--header",
+    </filters>
-    "StagesToken: ${AUTH_TOKEN}"
+</method>
-  ],
-  "env": {
-    "AUTH_TOKEN": "eyJh..."
-  },
-  "active": true
-}
 </code>
+  * ''discoveryURI'': The URL of the IdP's ''.well-known/openid-configuration'' file. For example, in Microsoft Entra ID: ''https://login.microsoftonline.com/<tenantId>/v2.0/.well-known/openid-configuration''.
+  * ''audience'': The audience value that Stages, as the resource server, checks in the JWT.
+  * ''usernameAttribute'': The JWT claim containing the username. This is typically the user's email address.
+  * Configure the filter as you would for [[.:integration:oidc|OIDC]] authentication.
-=== Stages 26.1 / Tomcat 10 ===
+==== Stages permissions ====
-Currently Stages MCP server supports Streamable HTTP protocol for Tomcat 10 version. The endpoint is ''/mcp/http'', e.g.:
+The MCP integration acts on behalf of the authenticated user. In addition to the usual permissions to view workspaces and process elements, the user must have the MCP permission to access them through MCP.
-''<nowiki>https://stages.example.com/mcp/http</nowiki>''
+To let all users use MCP, add the MCP domain to the default group.
-The API token that was created must be provided to the MCP server via the header ''StagesToken''.
+==== MCP client configuration ====
-An example MCP configuration:
+Configure your MCP client to connect to the Stages MCP server at this URL:
-<code javascript>
+''<nowiki>https://stages.example.com/stages/api/1/mcp</nowiki>''
-{
-  "command": "npx",
-  "args": [
-    "mcp-remote",
-    "https://stages.example.com/mcp/http",
-    "--header",
-    "StagesToken: ${AUTH_TOKEN}"
-  ],
-  "env": {
-    "AUTH_TOKEN": "eyJh..."
-  },
-  "active": true
-}
-</code>
+Stages currently supports Streamable HTTP.