MCP-Tool zur Untersuchung von CIB Seven-Prozessinstanzen. Bietet Claude umfassendes Wissen über CIB Seven REST-APIs mit Live-Ausführung und Keycloak-Authentifizierung.
Untersuchungstools — Prozessinstanzen, Anzahl, tägliche/wöchentliche/monatliche Statistiken, Vorfälle, Aktivitätshistorie, Variablen, BPMN XML, Jobs
Semantische Beschreibungen — Claude versteht, was jedes Feld operativ bedeutet, nicht nur Rohdaten der Endpunkte
BPMN-Introspektion — Abrufen von Prozessdefinitions-XML, Claude analysiert den erwarteten vs. tatsächlichen Ausführungspfad
Keycloak-Authentifizierung — OIDC Client Credentials Flow mit automatischer Token-Aktualisierung
Variablen-Schwärzung — konfigurierbare Regex-Muster zum Verbergen sensibler Daten
Diagnose-Prompts — diagnose_stuck_process und incident_report Workflows
Related MCP server: Procesio MCP Server
Hinzufügen zu Ihrer claude_desktop_config.json:
{
"mcpServers": {
"cib7": {
"command": "npx",
"args": ["cib7-mcp"],
"env": {
"CIB7_URL": "http://localhost:6009/rest"
}
}
}
}claude mcp add cib7-mcp -- npx cib7-mcpSetzen Sie dann die Umgebungsvariable CIB7_URL auf Ihre CIB Seven-Instanz.
Die gesamte Konfiguration erfolgt über Umgebungsvariablen.
Variable | Erforderlich | Beschreibung |
| Ja | CIB Seven REST-API-URL (z. B. |
| Nein | Keycloak-Server-URL (z. B. |
| Nein | Keycloak-Realm-Name |
| Nein | Keycloak-Client-ID |
| Nein | Keycloak-Client-Secret |
| Nein | Kommagetrennte Regex-Muster für die Variablen-Schwärzung (z. B. |
Wenn eine KEYCLOAK_*-Variable gesetzt ist, müssen alle vier bereitgestellt werden. Wenn keine gesetzt ist, läuft das Tool im nicht authentifizierten Modus.
{
"mcpServers": {
"cib7": {
"command": "npx",
"args": ["cib7-mcp"],
"env": {
"CIB7_URL": "https://your-instance.com/rest",
"KEYCLOAK_URL": "https://your-keycloak.com",
"KEYCLOAK_REALM": "your-realm",
"KEYCLOAK_CLIENT_ID": "mcp-client",
"KEYCLOAK_CLIENT_SECRET": "your-secret",
"CIB7_REDACT_PATTERNS": "password.*,secret.*,token.*,creditCard.*"
}
}
}
}Tool | Beschreibung |
| Nachschlagen einer Prozessinstanz nach ID — Status, Definition, Business Key |
| Suchen von Prozessinstanzen nach Definition, Business Key, Status, Start-/Enddatum, Vorfallstatus, mit Sortierung |
| Zählen übereinstimmender Instanzen ohne Abruf der Zeilen. Gleiche Filteroberfläche wie |
| Tägliches / wöchentliches / monatliches Histogramm gestarteter Instanzen. Gibt Anzahl pro Zeitraum + Zusammenfassung (Gesamt, Durchschnitt, Maximum, Minimum) zurück. |
| Auflisten offener Vorfälle, optional gefiltert nach Prozessinstanz |
| Ausführungsprotokoll — jede ausgeführte Aktivität in der richtigen Reihenfolge |
| Alle Variablen für eine Prozessinstanz (mit Schwärzung) |
| BPMN XML-Modell (Diagrammelemente zur besseren Lesbarkeit entfernt) |
| Job-Ausführungsdetails — Wiederholungsversuche, Fehlermeldungen |
Vier der listenartigen Tools akzeptieren einen view-Parameter, um zu steuern, welche
Zeilenfelder zurückgegeben werden. Die Antwort auf oberster Ebene ist immer ein einfaches Array von
Zeilen — nur der Feldsatz pro Zeile ändert sich.
Tool | Zusammenfassungsfelder (Standard) |
|
|
|
|
|
|
|
|
view: "summary" ist der Standardwert und reduziert die Antwortgröße im Vergleich zur
Rohform der Engine typischerweise um 40–60 %. Verwenden Sie view: "full", wenn Sie ein
Feld benötigen, das nicht in der obigen Zusammenfassungsliste enthalten ist (z. B. processDefinitionName,
startUserId, executionId, causeIncidentId, jobDefinitionId, Tenant-IDs).
Prompt | Beschreibung |
| Schritt-für-Schritt-Diagnose für eine hängende Prozessinstanz |
| Umfassender Bericht aller offenen Vorfälle mit Ursachenanalyse |
Drei Tools arbeiten für Volumenfragen zusammen, ohne Zeilen abzurufen:
list_process_instances — wenn Sie die Datensätze tatsächlich benötigen. Unterstützt das Filtern nach Definitions-Key (einzeln oder mehrfach), Definitionsname, Business Key, startedBy, aktivem/angehaltenem/abgeschlossenem Status, startedAfter/startedBefore, finishedAfter/finishedBefore, withIncidents, incidentStatus sowie sortBy/sortOrder und Paginierung über maxResults/firstResult.
count_process_instances — gleiche Filteroberfläche, gibt nur { count: N } zurück. Verwenden Sie dies für "Wie viele?"-Fragen, damit die Engine niemals Zeilen serialisieren muss.
process_instance_stats — tägliches / wöchentliches / monatliches Histogramm gestarteter Instanzen über einen Datumsbereich. Nimmt from, to und periodUnit (day, week oder month) entgegen. Führt intern count_process_instances parallel über Zeitfenster aus, sodass ein tägliches 30-Tage-Histogramm 30 kostengünstige Zählabrufe sind, kein Zeilenabruf.
process_instance_stats gibt jeden Bucket sowie eine Zusammenfassung mit Gesamtanzahl, Durchschnitt pro Bucket und dem geschäftigsten/ruhigsten Bucket zurück:
{
"from": "2025-03-01T00:00:00.000Z",
"to": "2025-03-31T00:00:00.000Z",
"periodUnit": "day",
"bucketCount": 30,
"summary": {
"total": 4820,
"average": 160.67,
"max": { "period": "2025-03-17", "count": 412 },
"min": { "period": "2025-03-09", "count": 3 }
},
"periods": [
{ "period": "2025-03-01", "start": "...", "end": "...", "count": 145 },
{ "period": "2025-03-02", "start": "...", "end": "...", "count": 160 }
]
}Ein paar Dinge, die Sie wissen sollten:
Fenster sind rechts offen [start, nextStart), sodass kein Bucket den Grenzzeitpunkt doppelt zählt.
Wochenfenster rücken um 7 Tage von from vor. Sie sind nicht auf Montag ausgerichtet, es sei denn, from ist selbst ein Montag — wählen Sie Ihr from entsprechend, wenn Sie ISO-Wochen wünschen.
Monatsfenster rücken um Kalendermonate vor (behandelt Monate mit unterschiedlicher Länge korrekt).
Eine Sicherheitsgrenze von 500 Buckets schützt vor außer Kontrolle geratenen Abfragen. Erhöhen Sie diese mit maxBuckets, wenn Sie wirklich einen längeren Bereich benötigen, oder verwenden Sie eine gröbere periodUnit.
Fragen Sie Claude:
"Ist Prozess abc-123 hängengeblieben?"
"Zeige mir alle offenen Vorfälle"
"Was ist die BPMN-Definition für Prozessdefinition orderProcess:1:456?"
"Erstelle einen Vorfallbericht"
"Wie viele Instanzen von orderProcess laufen gerade?"
"Wie viele orderProcess-Instanzen endeten letzte Woche mit Vorfällen?"
"Zeige mir das tägliche Volumen für orderProcess über die letzten 30 Tage — welcher Tag war am geschäftigsten?"
"Gib mir ein monatliches Histogramm aller Prozessstarts in diesem Jahr."
npm install
npm run build
npm testErfordert Node.js 18+.
MIT
Get the execution trace for a process instance — every activity that ran, in order.
This shows you exactly what happened: which tasks executed, in what order, and how long each took. Activities with a startTime but no endTime are currently executing or waiting.
Key fields:
activityType: startEvent, serviceTask, userTask, exclusiveGateway, etc.
activityName: human-readable name from the BPMN model
startTime/endTime: when the activity started and finished
durationInMillis: how long it took (null if still running)
canceled: true if the activity was interrupted
| Name | Required | Description | Default |
|---|---|---|---|
| processInstanceId | Yes | The process instance ID to trace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It excellently documents output semantics: explaining that missing endTime indicates running activities, that durationInMillis is null for active tasks, and detailing the canceled flag. It could improve by explicitly stating this is read-only/safe or mentioning any rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Information is perfectly front-loaded: purpose in sentence one, value proposition in sentence two, critical interpretation guidance in sentence three. The 'Key fields' section efficiently documents output structure without verbosity. Every sentence and bullet earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description compensates comprehensively by enumerating and explaining key response fields (activityType, activityName, timestamps, duration, canceled). It contextualizes these within BPMN concepts (startEvent, serviceTask, etc.). Only minor gap is explicit confirmation of read-only safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with clear description 'The process instance ID to trace'. The tool description references 'process instance' in the context but doesn't add parameter-specific guidance beyond the schema's documentation. Baseline 3 is appropriate given the schema does the heavy lifting for this single required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Get') and resource ('execution trace for a process instance'), clearly distinguishing this from siblings like get_process_instance (current state) or get_process_variables (data). The scope 'every activity that ran, in order' precisely defines what this tool retrieves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool returns (execution history, task order, duration), which implies when to use it (when you need audit trails). However, it lacks explicit guidance on when to prefer this over get_process_instance for current state or how it relates to the process lifecycle.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get job execution details for a process instance. Jobs are units of work the engine executes — service tasks, timers, message events.
Key fields:
retries: how many retry attempts remain. 0 means the engine gave up and created an incident.
exceptionMessage: the error from the last failed execution attempt
dueDate: when the job is scheduled to execute (for timers)
suspended: true if the job is paused
| Name | Required | Description | Default |
|---|---|---|---|
| processInstanceId | No | Filter jobs by process instance ID | |
| maxResults | No | Max results (default 25) | |
| firstResult | No | Offset for pagination (default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no output schema, the description carries full disclosure burden. It excellently documents key output fields (retries, exceptionMessage, dueDate, suspended) and their semantics (e.g., '0 means the engine gave up'). Explains job states and error conditions without contradicting the read-only nature of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured blocks: purpose definition followed by key field documentation. Every sentence earns its place. Front-loaded with the primary action, followed by domain context, then specific field semantics. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Compensates effectively for missing output schema by documenting four critical output fields with their meanings and relationships. Explains domain concepts (jobs vs incidents) necessary for interpretation. Given 3 simple parameters and no annotations, the description provides sufficient context for successful invocation and result interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (all 3 params documented). Description implies 'processInstanceId' usage via 'for a process instance', but doesn't add syntax details, format constraints, or pagination guidance beyond the schema. Baseline 3 appropriate given schema completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear specific verb ('Get') and resource ('job execution details'). Defines what jobs are ('units of work... service tasks, timers, message events') distinguishing them from process instances or activities. However, it doesn't explicitly differentiate from sibling 'list_incidents' despite mentioning the incident relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains job lifecycle concepts (retries=0 creates incident) which implies usage context, but lacks explicit guidance on when to use this vs 'get_activity_history' or 'list_incidents'. No explicit prerequisites or exclusions stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the BPMN XML model for a process definition. This is the blueprint — it shows the expected flow of the process.
Use the definitionId from get_process_instance to fetch the model. The XML includes all activities, gateways, sequence flows, and conditions. Diagram layout elements are stripped for readability.
Read the XML to understand:
The expected happy path (sequence of activities)
Gateway conditions (what determines which path is taken)
Error boundary events (what happens when activities fail)
Timer events (scheduled waits or timeouts)
| Name | Required | Description | Default |
|---|---|---|---|
| processDefinitionId | Yes | The process definition ID (from definitionId field of a process instance) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Successfully discloses that 'Diagram layout elements are stripped for readability' (transformation behavior) and details what the XML includes (activities, gateways, sequence flows). Minor gap: could mention if this is expensive or cached, but 'Fetch' clearly indicates read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Excellent structure: first sentence defines purpose, second links to prerequisite tool, third sets expectations about XML content, followed by targeted bullet points explaining analytical use cases. No wasted words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, description comprehensively compensates by detailing XML contents (activities, gateways, conditions) and explaining analytical value (happy path, error boundaries, timers). For a single-parameter read operation, coverage is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing full parameter documentation. Description reinforces the parameter provenance by referencing get_process_instance, matching the schema description. At 100% coverage, baseline 3 is appropriate as schema carries the semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Fetch' with clear resource 'BPMN XML model for a process definition' and distinguishes from siblings like get_process_instance (which retrieves runtime instance data) by emphasizing this retrieves the static 'blueprint' model.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states prerequisite 'Use the definitionId from get_process_instance to fetch the model,' providing clear workflow guidance linking to sibling tool. Also explains when to use the result (to understand happy path, gateway conditions, error events).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a CIB Seven process instance by its ID. Returns the instance's current state, definition reference, business key, and suspension status.
Use this when you have a specific process instance ID and need to understand its current state. If you only have a business key or definition key, use list_process_instances instead.
Key response fields:
suspended: true means manually paused by an operator
ended: true means the process completed or was cancelled
businessKey: the domain identifier (e.g. order number, case ID)
definitionId: use this to fetch the BPMN XML via get_process_definition_xml
| Name | Required | Description | Default |
|---|---|---|---|
| processInstanceId | Yes | The UUID of the process instance |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It explains semantic meaning of key response states (suspended=manually paused, ended=completed/cancelled, businessKey=domain identifier) and cross-tool workflow (definitionId links to get_process_definition_xml). Could explicitly state read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three logical segments (purpose/return, usage guidance, response documentation) with efficient bullet points for field definitions. No redundant text, though slightly longer than minimal necessary due to embedded response documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Compensates for missing output schema by comprehensively documenting key response fields and their domain semantics (e.g., business key examples). Covers relationships to sibling tools and CIB Seven domain context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter description ('The UUID of the process instance'). Description mentions lookup 'by its ID' but adds no additional semantic details (format constraints, validation rules) beyond schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Look up' with resource 'CIB Seven process instance' and explicitly distinguishes from sibling 'list_process_instances' by stating it requires a specific ID vs business/definition keys.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Contains explicit when-to-use clause ('when you have a specific process instance ID') and explicit alternative routing ('If you only have a business key... use list_process_instances instead').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all variables for a process instance. Variables hold the data that drives process execution — form inputs, API responses, decision results.
Sensitive variable values may be redacted (shown as [REDACTED]) based on configured patterns.
Common variable patterns:
Error flags or status fields that indicate why a process is waiting
Retry counters that show how many times something was attempted
Input data from forms or API calls
| Name | Required | Description | Default |
|---|---|---|---|
| processInstanceId | Yes | The process instance ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full disclosure burden. Adds valuable security context about redaction ('[REDACTED]' based on patterns). Missing confirmation that this is read-only, auth requirements, or return structure details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear paragraph separation and bullet points for common patterns. No filler text; redaction warning and usage patterns earn their place. Appropriately sized for the domain complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a single-parameter read tool. Compensates for missing output schema by explaining what variables represent and their business relevance. Redaction disclosure addresses a key operational concern.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage ('The process instance ID'), meeting baseline expectations. Description mentions 'process instance' but doesn't add parameter-specific semantics like ID format or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource ('Get all variables for a process instance') and distinguishes scope by explaining what variables contain (form inputs, API responses) versus instance metadata or activities. Lacks explicit differentiation from sibling tools like get_process_instance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides implied usage guidance through 'Common variable patterns' section (error flags, retry counters, input data), hinting at when to use the tool. However, lacks explicit when-to-use/when-not-to-use guidance or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List open incidents in the process engine. Incidents record things that went wrong during execution.
Key incident types:
failedJob: a service task or timer threw an exception and the engine gave up retrying (retries=0)
failedExternalTask: an external task worker reported a failure
Use without filters to see all open incidents. Filter by processInstanceId to see incidents for a specific process.
| Name | Required | Description | Default |
|---|---|---|---|
| processInstanceId | No | Filter by process instance ID | |
| incidentType | No | Filter by type: failedJob, failedExternalTask | |
| maxResults | No | Max results (default 25) | |
| firstResult | No | Offset for pagination (default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It effectively discloses behavioral traits by explaining the domain logic: failedJob means 'retries=0' and failedExternalTask means 'worker reported a failure.' It also clarifies these are 'open' incidents (state-based filtering). Could explicitly state this is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections: purpose declaration, bulleted type definitions with explanations, and usage guidance. Every sentence earns its place—no filler. The progression from general definition to specific types to usage patterns is logical and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters with 100% schema coverage and no output schema, the description provides adequate domain context. It explains the process engine incident model sufficiently and covers pagination parameters implicitly through usage guidance. As a list operation, it appropriately focuses on filtering logic rather than return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage, but the description adds crucial semantic context beyond the schema. It explains what 'failedJob' actually means (service task/timer threw exception, retries exhausted) and defines failedExternalTask, helping the agent understand the business logic behind the incidentType parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'List[s] open incidents in the process engine' with specific verb and resource. It defines what incidents are ('things that went wrong during execution') and identifies key types. However, it does not explicitly distinguish from sibling tools like get_activity_history or list_process_instances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit filtering guidance: 'Use without filters to see all open incidents. Filter by processInstanceId to see incidents for a specific process.' This clarifies how to scope queries. Lacks explicit alternatives (e.g., when to use get_job_details instead), but the context provided is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for process instances using filters. Uses the history API to find both running and completed instances.
Use this when you need to find process instances by business key, definition key, or state. Returns an array of historic process instances.
Filter options:
processDefinitionKey: the BPMN process ID (e.g., "orderProcess")
businessKey: domain identifier (e.g., "ORDER-12345")
state: ACTIVE, COMPLETED, SUSPENDED, or EXTERNALLY_TERMINATED
maxResults: limit results (default 25)
firstResult: offset for pagination
| Name | Required | Description | Default |
|---|---|---|---|
| processDefinitionKey | No | Filter by BPMN process definition key | |
| businessKey | No | Filter by business key | |
| active | No | Only active (running) instances | |
| suspended | No | Only suspended instances | |
| completed | No | Only completed instances | |
| maxResults | No | Max results to return (default 25) | |
| firstResult | No | Offset for pagination (default 0) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It successfully adds critical behavioral context by specifying the tool uses the 'history API' and returns 'historic process instances,' implying read-only access to archived data. It also discloses the default pagination limit (25).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Text is efficiently structured with a clear opening sentence, a 'when to use' sentence, a return value statement, and a bulleted list for filter options. Every sentence earns its place; no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters with 100% schema coverage and no output schema, the description adequately covers tool purpose, behavioral API type (history), return structure (array), and provides concrete examples for key filters. Missing only minor details like explicit mention that all parameters are optional or the relationship between the three boolean state flags.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema has 100% description coverage (baseline 3), the description adds helpful examples for processDefinitionKey and businessKey. However, it documents a 'state' enum parameter (ACTIVE, COMPLETED, SUSPENDED, EXTERNALLY_TERMINATED) that does not exist in the schema; instead, the schema implements these as three separate boolean flags (active, suspended, completed). This mismatch creates confusion about how to structure filter parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search for process instances using filters' providing a specific verb and resource. It further distinguishes scope by noting it uses the 'history API to find both running and completed instances,' which differentiates it from siblings like get_process_instance (singular retrieval) and get_activity_history (activity level vs instance level).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use this when you need to find process instances by business key, definition key, or state,' providing clear context for when to select this tool. While it doesn't explicitly name the alternative (e.g., 'use get_process_instance when you have an ID'), the filtering focus implies this is for discovery rather than direct retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_activity_historyget_job_detailsget_process_definition_xmlget_process_instanceget_process_variableslist_incidentslist_process_instancesScored across 7 tools
Each tool targets a distinct aspect of process execution with clear boundaries: instances (list/get), execution trace (activity_history), data (variables), background work (job_details), blueprint (definition_xml), and errors (incidents). No ambiguous overlap exists between these concepts.
Follows consistent snake_case verb_noun pattern (get_*, list_*), but applies the 'process_' prefix inconsistently (e.g., get_process_instance vs get_activity_history). Despite this, the naming remains readable and predictable.
Seven tools provide a focused, well-scoped surface for process observability without bloat. Each tool earns its place by covering a specific inspection need, fitting appropriately within the typical 3-15 tool range for this domain.
Covers core read-only inspection workflows well, but has notable gaps for a general CIB Seven integration: missing list_process_definitions (required to browse definitions without an instance), missing task-specific operations, and lacks any write/modify capabilities (create instances, update variables, resolve incidents).
Business Observability: process inventory, AP risk, sales temperature, savings. diezX customers only
IncidentOracle - 12-tool incident management MCP: triage, BaFin DORA reporting, RCA.
ZEN SecDB MCP server for CVE intelligence, CVSS/EPSS scoring, advisories, SSVC, and package audits.
Managed Keycloak from any MCP client: clusters, realms, apps, SSO, users, domains, audit events.
