Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@BPMN Live MCP Create a BPMN diagram for order processing"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for creating and manipulating BPMN 2.0 workflow diagrams programmatically. This server enables AI assistants and other tools to generate, edit, and export business process diagrams in the standard BPMN format.
Create BPMN Diagrams: Generate new workflow diagrams from scratch
Add Process Elements: Insert events, tasks, gateways, and subprocesses
Connect Elements: Create sequence flows between workflow components
Export Formats: Save diagrams as BPMN 2.0 XML or SVG
Import Support: Load and modify existing BPMN XML files
Live Modeler: Open a local bpmn-js modeler and explicitly save changes to the MCP session
Native Palette: Use the full bpmn-js palette and context pad in the browser modeler
Smart Hints: Get helpful nudges to ensure complete workflows with proper connections
Related MCP server: MCP-BPMN Server
Node.js (v18 or higher)
npm or yarn
Clone the repository:
git clone https://github.com/MykhailoPrykhodko/bpmn-live-mcp.git
cd bpmn-live-mcpInstall dependencies:
npm installBuild the project:
npm run buildAdd the following to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"bpmn": {
"command": "node",
"args": ["/absolute/path/to/bpmn-live-mcp/dist/index.js"]
}
}
}Replace /absolute/path/to/bpmn-live-mcp with the actual path where you cloned this repository.
This MCP server works with any tool that supports the Model Context Protocol. Configure it to run:
node /absolute/path/to/bpmn-live-mcp/dist/index.jsAdd the server to an OpenCode project configuration at .opencode/opencode.json or to the global OpenCode configuration at ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"bpmn": {
"type": "local",
"command": ["node", "dist/index.js"],
"cwd": "/absolute/path/to/bpmn-live-mcp",
"enabled": true
}
}
}Use the absolute path to your local bpmn-live-mcp project in cwd. Build the server before using it:
npm install
npm run buildRestart OpenCode after changing its MCP configuration. You can then ask OpenCode to create, inspect, edit, or export BPMN diagrams using the bpmn MCP tools.
Once configured, you can ask your AI assistant to create BPMN diagrams. Here are some example requests:
Create a BPMN diagram for an order processing workflow with these steps:
1. Order Received (start event)
2. Validate Order (user task)
3. Process Payment (service task)
4. Order Complete (end event)
Connect them with sequence flows.
Create a BPMN diagram for customer support ticket routing:
- Start: Ticket Received
- Task: Categorize Ticket
- Gateway: Check Priority
- If High: Escalate to Senior Support
- If Normal: Assign to Support Team
- Both paths lead to: Ticket Resolved (end)After creating or importing a diagram, open a browser-based modeler without exporting a file:
Open the live BPMN modeler for diagram diagram_123The open_bpmn_modeler tool returns a local URL. Open that URL in a browser to edit the diagram with bpmn-js. Browser changes remain local until you click Save or press Ctrl/Cmd + S, then they are saved back to the active MCP diagram session.
The modeler includes local-file open and drag-and-drop, a guarded New action that resets the active diagram, undo/redo, zoom and fullscreen controls, keyboard shortcuts, and downloads for both diagram.bpmn and diagram.svg.
The modeler runs on loopback only (127.0.0.1). The URL is tokenized and expires after one hour. If MCP changes the diagram while the browser has unsaved edits, the modeler reports a conflict instead of overwriting the newer change.
To inspect the same live modeler session from chat, copy the token after /modeler/ in the URL and call inspect_bpmn_modeler. The token is tied to the running MCP process and becomes invalid after that process restarts.
Create or import a diagram in OpenCode:
Create the archiving approval BPMN diagram and return its diagram ID.Open the live modeler:
Open the live BPMN modeler for diagram diagram_123Open the returned local URL in a browser. Use the native bpmn-js palette and context pad to add tasks, events, gateways, lanes, participants, annotations, data objects, and connections.
Click Save in the modeler, or press Ctrl+S / Cmd+S. Edits remain local until explicitly saved.
Ask OpenCode to inspect the saved modeler session. Copy the token from the URL, which is the value after /modeler/:
Inspect the live BPMN modeler using token 20a865e6d4217dade1c64448b9b9e2a70ad7dff5b615db14OpenCode can use inspect_bpmn_modeler to resolve the token and read the latest diagram state. It can also use inspect_bpmn_diagram with the resolved diagram ID.
The modeler provides separate Download BPMN and Download SVG actions. These downloads do not replace the explicit MCP Save action.
The MCP server provides these tools:
create_bpmn_diagramCreates a new BPMN diagram and returns a diagram ID.
add_bpmn_elementAdds an element to the diagram. Supported types:
Events: bpmn:StartEvent, bpmn:EndEvent, bpmn:IntermediateCatchEvent, bpmn:IntermediateThrowEvent
Tasks: bpmn:Task, bpmn:UserTask, bpmn:ServiceTask, bpmn:ScriptTask, bpmn:ManualTask, bpmn:BusinessRuleTask, bpmn:SendTask, bpmn:ReceiveTask
Gateways: bpmn:ExclusiveGateway, bpmn:ParallelGateway, bpmn:InclusiveGateway, bpmn:EventBasedGateway, bpmn:ComplexGateway
Containers and artifacts: bpmn:SubProcess, bpmn:CallActivity, bpmn:Participant, bpmn:Lane, bpmn:DataObjectReference, bpmn:DataStoreReference, bpmn:TextAnnotation, bpmn:Group
Boundary events: bpmn:BoundaryEvent
Use parentElementId for lanes and nested elements, hostElementId for boundary events, and eventDefinitionType for typed events.
connect_bpmn_elementsCreates a BPMN connection between two elements. Supported connection types include sequence flows, message flows, associations, data associations, and conversation links.
export_bpmn_xmlExports the diagram as BPMN 2.0 XML format.
export_bpmn_svgExports the diagram as SVG for visualization.
open_bpmn_modelerStarts a local browser-based bpmn-js modeler for a diagram and returns a tokenized URL. Browser edits are explicitly saved to the MCP session using revision checks.
close_bpmn_modelerRevokes a modeler URL before its normal expiration.
inspect_bpmn_modelerResolves a live modeler URL token to its MCP diagram and returns the latest inspection data. Use the token from the URL when the diagram ID is not available in chat.
list_bpmn_elementsLists all current elements, connections, containers, relationships, and revision metadata, including browser modeler edits.
inspect_bpmn_diagramReturns a chat-friendly summary of the latest diagram state, including element counts, properties, relationships, revision, and the last modification source. Set includeXml to true to include normalized BPMN XML.
import_bpmn_xmlImports an existing BPMN XML file for editing.
The server generates standard BPMN 2.0 XML files that can be opened in:
Any BPMN 2.0 compliant tool
Example XML output:
<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
xmlns:di="http://www.omg.org/spec/DD/20100524/DI">
<bpmn:process id="Process_1" isExecutable="true">
<bpmn:startEvent id="Event_1" name="Start">
<bpmn:outgoing>Flow_1</bpmn:outgoing>
</bpmn:startEvent>
<bpmn:task id="Task_1" name="Process">
<bpmn:incoming>Flow_1</bpmn:incoming>
<bpmn:outgoing>Flow_2</bpmn:outgoing>
</bpmn:task>
<bpmn:endEvent id="Event_2" name="End">
<bpmn:incoming>Flow_2</bpmn:incoming>
</bpmn:endEvent>
<bpmn:sequenceFlow id="Flow_1" sourceRef="Event_1" targetRef="Task_1" />
<bpmn:sequenceFlow id="Flow_2" sourceRef="Task_1" targetRef="Event_2" />
</bpmn:process>
<!-- Diagram information omitted for brevity -->
</bpmn:definitions>npm run watchThis will rebuild the project automatically when source files change.
You can test the server manually using the MCP protocol:
node dist/index.jsThen send JSON-RPC requests via stdin. Example:
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}Run the automated modeler and MCP integration tests with:
npm testRuntime: Node.js with TypeScript
BPMN Engine: bpmn-js (headless mode with jsdom)
Protocol: Model Context Protocol (MCP)
Output: BPMN 2.0 XML standard
Live UI: Local HTTP modeler using the bpmn-js browser bundle
The server includes helpful hints to ensure complete diagrams:
Reminds you to connect elements when adding tasks/events
Warns when exporting diagrams with disconnected elements
Suggests using connect_bpmn_elements to create proper workflows
MIT
Contributions are welcome! Please feel free to submit issues or pull requests.
For issues or questions:
Open an issue on GitHub
Check existing issues for solutions
bpmn-js - BPMN 2.0 rendering toolkit
Model Context Protocol - Protocol specification
Add an element (task, gateway, event, etc.) to a BPMN diagram
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | X coordinate for the element (default: 100) | |
| y | No | Y coordinate for the element (default: 100) | |
| name | No | The name/label for the element | |
| diagramId | Yes | The diagram ID returned from create_bpmn_diagram | |
| isExpanded | No | Whether a subprocess or participant is expanded | |
| elementType | Yes | The type of BPMN element to add | |
| hostElementId | No | Host element ID for boundary events | |
| parentElementId | No | Optional parent container ID, required for lanes and nested elements | |
| eventDefinitionType | No | Optional event definition type, for example bpmn:TimerEventDefinition |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for a mutation tool. It does not state whether the modeler must be open, whether changes are reversible, what is returned, or what permissions are required for adding elements.
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?
A single, front-loaded sentence with no wasted words. It is appropriately concise, though for a nine-parameter mutation tool it provides minimal structure beyond the bare statement.
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 nine parameters, no annotations, and no output schema, the description is too thin. It omits prerequisites, return behavior, and how this tool relates to siblings needed before or after adding an element.
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 description coverage is 100%, so all nine parameters are already documented with descriptions, including the elementType enum. The description's examples ('task, gateway, event, etc.') add minimal meaning beyond the schema, fitting the baseline 3 for high schema coverage.
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?
States a specific verb and resource ('Add an element') and clarifies the context with examples ('task, gateway, event, etc.'). However, it does not distinguish this tool from siblings such as create_bpmn_diagram, connect_bpmn_elements, or list_bpmn_elements.
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 gives no explicit when-to-use, when-not-to-use, or alternative-tool guidance. The schema mentions create_bpmn_diagram for diagramId, but that is structured field context, not description-level guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close a live local bpmn-js modeler preview URL
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | The preview token returned by open_bpmn_modeler |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not say whether closing releases server resources, whether the token becomes invalid, whether the call is idempotent, or what happens on an unknown/expired token.
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?
One short sentence, front-loaded with the verb and resource, with no waste. Brevity borders on under-specification, but there is no 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?
For a one-parameter cleanup tool with no output schema this is minimally adequate, but with no annotations it should say more about side effects and error behavior. The core information an agent needs to select and invoke it is present.
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 description coverage is 100% and the single token parameter is documented as coming from open_bpmn_modeler, so the schema does the heavy lifting. The description adds nothing beyond what the schema already provides, which is the baseline 3 case.
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?
States a specific verb (close) and resource (live local bpmn-js modeler preview URL), which distinguishes it from sibling open_bpmn_modeler by polarity. Minor muddiness: it says it closes a 'preview URL' while the schema accepts a token, leaving the object being closed slightly ambiguous.
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?
Usage is only implied by the pairing with open_bpmn_modeler (close what you opened). There is no explicit statement of when to call it, whether it is safe to call twice, or what alternative to use if the preview is already gone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect two BPMN elements with a BPMN connection
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | Optional label for the connection | |
| diagramId | Yes | The diagram ID | |
| connectionType | No | BPMN connection type (defaults to bpmn:SequenceFlow) | |
| sourceElementId | Yes | The ID of the source element | |
| targetElementId | Yes | The ID of the target element |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a mutation but never states failure behavior, whether invalid element IDs are rejected, whether the connection is immediately persisted, or what a successful call returns. For a write operation with zero annotation coverage this is a substantial gap.
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?
A single efficient sentence with no filler, and the operation is front-loaded. It is concise to the point of being sparse, but nothing in it is wasted.
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?
For a 5-parameter mutation tool with no annotations and no output schema, the description should carry more: prerequisites, return behavior, and where the created connection appears. Almost everything an agent needs beyond parameter names is absent.
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 description coverage is 100%, so all five parameters including the connectionType enum and its default are already documented in the schema. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.
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?
States a specific verb ('Connect') and resource ('BPMN elements'/'BPMN connection'), which is unambiguous about the operation. However, it does nothing to distinguish itself from siblings like add_bpmn_element or create_bpmn_diagram, so it stops short of a 5.
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?
There is no guidance on when to use this versus alternatives, no mention of prerequisites (e.g. that source and target elements must already exist in the diagram), and no exclusion conditions. The agent must infer usage entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new BPMN diagram. Returns a diagram ID that can be used with other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional name for the diagram |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool creates a new diagram and returns an ID, which implies a write operation, but lacks details on permissions, error handling, or side effects (e.g., if creation is idempotent or has rate limits). This is a significant gap for a creation tool with zero annotation coverage.
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?
The description is extremely concise—two sentences that directly state the action and the return value. It is front-loaded with the core purpose, and every sentence adds value without redundancy, making it efficient and well-structured.
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 the complexity of a creation tool with no annotations and no output schema, the description is incomplete. It doesn't explain the return value's format beyond 'diagram ID', error conditions, or how the ID integrates with sibling tools. For a tool that likely initiates a workflow (e.g., followed by 'add_bpmn_element'), more context is needed.
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?
The input schema has 100% description coverage, with the 'name' parameter documented as optional. The description adds no additional parameter semantics beyond what the schema provides, such as format constraints or examples. With high schema coverage, the baseline is 3, as the description doesn't compensate but doesn't detract either.
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 verb 'Create' and the resource 'BPMN diagram', making the purpose specific and understandable. It distinguishes from siblings like 'import_bpmn_xml' or 'list_bpmn_elements' by focusing on creation rather than import or listing. However, it doesn't explicitly differentiate from all siblings (e.g., 'add_bpmn_element' might be ambiguous), so it's not a perfect 5.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., if a diagram must be created before using 'add_bpmn_element'), exclusions, or comparisons to siblings like 'import_bpmn_xml' for existing diagrams. This leaves the agent with minimal context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a BPMN diagram as SVG
| Name | Required | Description | Default |
|---|---|---|---|
| diagramId | Yes | The diagram ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action (export) but doesn't describe what the export produces (e.g., file content, download link), error conditions, permissions required, or side effects. For a tool with no annotations, this leaves critical behavioral traits unspecified.
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?
The description is a single, efficient sentence ('Export a BPMN diagram as SVG') that directly states the tool's function with zero wasted words. It is appropriately sized and front-loaded, making it easy to parse quickly.
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 the tool's complexity (export operation with no annotations and no output schema), the description is incomplete. It lacks details on the output (what the SVG contains, how it's returned), error handling, and dependencies (e.g., diagram must exist). For a tool with no structured output or annotations, more context is needed.
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?
The input schema has 100% description coverage, with the single parameter 'diagramId' documented as 'The diagram ID.' The description adds no additional meaning beyond this, such as format examples or where to find the ID. With high schema coverage, the baseline score of 3 is appropriate.
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's purpose as 'Export a BPMN diagram as SVG,' which is a specific verb (export) and resource (BPMN diagram). It distinguishes from some siblings like 'export_bpmn_xml' by specifying the output format (SVG vs XML), but doesn't differentiate from all siblings (e.g., 'create_bpmn_diagram' is clearly different).
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing diagram), compare it to 'export_bpmn_xml' for format choice, or indicate when export might fail. Usage is implied from the name and purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export a BPMN diagram as XML
| Name | Required | Description | Default |
|---|---|---|---|
| diagramId | Yes | The diagram ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool exports XML, implying a read operation, but doesn't disclose behavioral traits such as whether it requires specific permissions, if it modifies the diagram, what happens on errors, or the format/scope of the exported XML. This leaves significant gaps for a tool with no annotation coverage.
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?
The description is a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, clearly stating the tool's purpose without unnecessary details.
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 the complexity (export operation), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the exported XML contains, how it's structured, or any limitations (e.g., size, supported BPMN versions). For a tool with no structured data to compensate, this leaves the agent under-informed.
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?
The input schema has 100% description coverage, with 'diagramId' documented as 'The diagram ID'. The description adds no additional meaning beyond this, such as where to find the ID or its format. With high schema coverage, the baseline is 3, as the schema does the heavy lifting.
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 'Export a BPMN diagram as XML' clearly states the action (export) and resource (BPMN diagram) with the output format (XML). It distinguishes from siblings like 'export_bpmn_svg' by specifying XML instead of SVG, but doesn't fully differentiate from 'import_bpmn_xml' which involves the same format for input.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing diagram), exclusions, or comparisons to siblings like 'export_bpmn_svg' for different output formats or 'list_bpmn_elements' for viewing without export.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import an existing BPMN XML diagram
| Name | Required | Description | Default |
|---|---|---|---|
| xml | Yes | The BPMN XML to import |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool imports BPMN XML, implying a write operation, but doesn't describe what happens during import (e.g., validation, error handling, or effects on existing diagrams). For a mutation tool with zero annotation coverage, this is a significant gap in transparency.
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?
The description is a single, efficient sentence: 'Import an existing BPMN XML diagram.' It is front-loaded with the core action and resource, with no wasted words. Every part of the sentence contributes to understanding the tool's purpose.
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 the complexity of importing BPMN XML (a mutation operation), the lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the tool returns, potential errors, or behavioral details like validation. For a tool with these gaps, it should provide more context to be fully helpful.
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?
The input schema has 100% description coverage, with the 'xml' parameter documented as 'The BPMN XML to import.' The description doesn't add any meaning beyond this, such as format details or constraints. With high schema coverage, the baseline score is 3, as the schema does the heavy lifting.
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's purpose: 'Import an existing BPMN XML diagram.' It specifies the verb ('import') and resource ('BPMN XML diagram'), making the action clear. However, it doesn't explicitly differentiate from sibling tools like 'create_bpmn_diagram' or 'export_bpmn_xml', which would require a 5.
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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing valid BPMN XML), exclusions (e.g., not for creating new diagrams), or comparisons to siblings like 'create_bpmn_diagram' or 'export_bpmn_xml'. This leaves the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the latest BPMN diagram state, including edits saved from the browser modeler
| Name | Required | Description | Default |
|---|---|---|---|
| diagramId | Yes | The diagram ID | |
| includeXml | No | Include the complete normalized BPMN XML |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that it retrieves the latest state including browser modeler edits, but it does not state whether the operation is read-only, what permissions are required, what the return format is, or whether there are side effects.
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?
A single front-loaded sentence with no wasted words. It is appropriately sized, though it could be slightly more structured by naming alternatives or return behavior.
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?
For a tool with no output schema and no annotations, the description should clarify what inspection returns, such as diagram state, element list, or the effect of includeXml on the response, and that it is a read-only operation. It only states the purpose, leaving key behavioral and return context missing.
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 description coverage is 100%, so the schema already documents diagramId and includeXml. The description adds no parameter-level syntax or format details beyond what the schema provides, so the baseline score of 3 applies.
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?
States a specific verb (Inspect) and resource (BPMN diagram state) and adds the scope of including browser modeler edits. It does not explicitly differentiate from sibling tools like inspect_bpmn_modeler or list_bpmn_elements, so an agent must infer which inspection tool is appropriate.
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?
No when-to-use or when-not-to-use guidance is given, and no alternatives are named. The phrase 'including edits saved from the browser modeler' hints at a context but does not tell the agent when this tool is preferable to inspect_bpmn_modeler or list_bpmn_elements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the latest diagram state behind a live bpmn-js modeler URL using its preview token
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | The preview token from the modeler URL or open_bpmn_modeler | |
| includeXml | No | Include the complete normalized BPMN XML |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It conveys that this reads the 'latest diagram state' of a *live* modeler session, which implies a non-mutating snapshot, but it never states side-effect behavior, whether the session must be open, or what happens with a stale token.
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?
A single front-loaded sentence with no filler; the key action and target are stated immediately.
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?
With no output schema and no annotations, the description should explain what inspection yields (elements, counts, validation state, XML vs structured view). Since the only return-related hint is the 'includeXml' flag in the schema, an agent knows how to call it but not what it gets back.
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 description coverage is 100%, so both 'token' and 'includeXml' are already fully documented in the schema. The description adds no syntax, format, or token-lifetime detail beyond what the schema provides, making this the baseline case.
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?
States a specific verb ('Inspect') and resource ('latest diagram state behind a live bpmn-js modeler URL'), which is clear and concrete. However, it does not differentiate itself from the sibling 'inspect_bpmn_diagram', which an agent could easily confuse with this tool.
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?
Usage is only implied: the reader must infer that this tool works with a preview token produced by 'open_bpmn_modeler' (mentioned only in the token parameter description). There is no explicit statement of when to prefer this over inspect_bpmn_diagram or other list/export tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all current BPMN elements, connections, containers, and relationships
| Name | Required | Description | Default |
|---|---|---|---|
| diagramId | Yes | The diagram ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not state that it is read-only/non-destructive (implied only by 'List'), nor describe return format, ordering, or pagination behavior. For a tool whose safety profile is undeclared, this is a gap, though the low implied risk keeps it from the bottom.
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?
A single front-loaded sentence with the verb first and zero waste. It is efficient, though very terse for a tool whose usage and behavior are otherwise undocumented.
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?
For a simple one-parameter read tool with no output schema and no annotations, the description minimally suffices to convey purpose. It falls short on sibling differentiation and on any behavioral or usage context that the absent annotations would otherwise supply.
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 description coverage is 100% with a single required diagramId parameter that the schema documents. The description adds no syntax, format, or scoping detail about diagramId, so the baseline 3 is appropriate.
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?
States a specific verb+resource ('List all current BPMN elements, connections, containers, and relationships'), which is more informative than the bare name. However, it does not differentiate itself from siblings like inspect_bpmn_diagram or inspect_bpmn_modeler, which likely also read diagram state, leaving some ambiguity about which read tool to pick.
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?
There is no when-to-use guidance, no prerequisites, and no mention of an alternative tool. The agent must infer from the sibling list that this is the enumeration option versus the inspection options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a live local bpmn-js modeler for a BPMN diagram. Browser edits are saved to the MCP session when the user clicks Save.
| Name | Required | Description | Default |
|---|---|---|---|
| diagramId | Yes | The diagram ID | |
| openBrowser | No | Open the returned modeler URL in the default browser |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose an important behavioral fact: browser edits are persisted to the MCP session only when the user clicks Save. However, it omits whether the call blocks, whether it is idempotent, what happens if a modeler is already open, and that a URL is returned.
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 short sentences, front-loaded with the core action and followed by the one behavioral detail that matters. Every clause 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?
No annotations and no output schema, so the description must stand alone; it covers what the tool does and the Save-persistence semantic, but leaves the session lifecycle relative to its sibling modeler tools and the returned URL unexplained.
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 description coverage is 100%, so both diagramId and openBrowser are already documented in the schema; per the rubric this establishes a baseline of 3. The description adds no syntax or format detail beyond what the schema provides.
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?
Specific verb 'Open' plus a concrete resource ('live local bpmn-js modeler for a BPMN diagram') that clearly distinguishes it from the export/inspect/close siblings. It does not name a sibling to avoid, so it stops short of the 5 bar.
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?
Usage is implied (open this when you need an interactive editor), and the Save-click sentence hints at the workflow, but there is no explicit when-to-use vs. when-not-to-use guidance and no mention of the sibling lifecycle tools (close_bpmn_modeler, inspect_bpmn_modeler).
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.
v1.0.0add_bpmn_elementclose_bpmn_modelerconnect_bpmn_elementscreate_bpmn_diagramexport_bpmn_svgexport_bpmn_xmlimport_bpmn_xmlinspect_bpmn_diagraminspect_bpmn_modelerlist_bpmn_elementsopen_bpmn_modelerScored across 11 tools
Most tools target distinct actions (create, add, connect, export, open/close modeler). However, inspect_bpmn_diagram, inspect_bpmn_modeler, and list_bpmn_elements overlap in reporting diagram state, which could cause occasional misselection.
All tools use snake_case with a consistent verb_bpmn_noun pattern (e.g., create_bpmn_diagram, export_bpmn_xml, open_bpmn_modeler). The convention is predictable and readable throughout.
11 tools is well within the ideal range for a BPMN diagram editor with live modeler support. Each tool covers a distinct operation without obvious bloat.
The surface covers creation, import, element addition, connection, inspection, and export well. However, it lacks update/delete operations for elements or connections, and no delete-diagram tool, leaving significant lifecycle gaps for programmatic editing.
Create, read and live-edit visual boards, Kanban plans, Gantt timelines and diagrams with AI agents.
Give any MCP-compatible AI assistant a builder for live, hosted web tools and workflows.
Give your AI agents the tools to build, manage, and run automation workflows.
Create, browse, remix, collaborate on, and run durable AI workflow nodes from MCP hosts.
