Command line / Automation
The MCP server
Let an AI assistant read, check and, if you allow it, edit the diagrams in your project, with the same checks a person gets.
What it is
MCP (Model Context Protocol) is a way for an AI assistant to use a program's tools. penstock mcp starts a small server on your machine that talks to the assistant over standard input and output. It offers thirty tools, the diagrams of the open folders as resources, and two prompts. It reads BPMN diagrams, DMN decision files and Camunda forms. An assistant that edits a diagram can check straight away that it still runs to its end.
Connect an AI assistant
The CLI needs Node.js. Node.js 22.22 or later must be on the PATH of your assistant. The tools that read, check, search, compare, analyse for Camunda 8 and draw are free, with no time limit: list_diagrams, show_diagram, element_context, check_diagram, search_elements, diff_diagrams, migrate_analyze, export_image, connections, agents, drift (for one environment), import_diagram, refactor_rename, test_dmn (up to 3 cases per decision) and the previews of migrate_agents and incident_to_scenario. The other tools, and the writes behind the free ones, are part of Penstock Pro, and Team in a pipeline, as penstock mcp --help states.
Running penstock mcp --config prints the standard client configuration. There is no project folder in the entry: you configure it once, and the server finds each project from the files the assistant asks about. The entry names the exact version of the command line that printed it, as npx --yes @kern0x1b/penstock-cli@<version> mcp, so the assistant runs the version you have. A development build of the command line has no published version, and prints penstock mcp instead. The entries below, written by hand, run whatever version npm serves; paste the printed one to pin it. With the command line installed (npm install -g @kern0x1b/penstock-cli), claude mcp add penstock -- penstock mcp adds it to Claude Code.
Two other ways to give an agent the tools need no entry in its settings. penstock agent claude, codex, gemini or opencode starts that agent in your terminal with the server set up for that one run and nothing written to the agent's configuration. See agent. And the AI chat in the Penstock editors starts your agent with the same server, so it reads diagrams, rules, scenarios and code links as the command line does.
penstock mcp --project <dir> fixes the project: every tool works on that folder, the assistant does not have to name it, and nothing outside it is read.
Claude Code
Run this command in your terminal:
claude mcp add penstock -- npx --yes @kern0x1b/penstock-cli mcp
Claude Desktop
In claude_desktop_config.json (under ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows), add penstock under mcpServers:
{
"mcpServers": {
"penstock": {
"command": "npx",
"args": ["--yes", "@kern0x1b/penstock-cli", "mcp"]
}
}
}
Cursor
In .cursor/mcp.json in your project, or in ~/.cursor/mcp.json for all projects, add the server under mcpServers:
{
"mcpServers": {
"penstock": {
"command": "npx",
"args": ["--yes", "@kern0x1b/penstock-cli", "mcp"]
}
}
}
VS Code
In VS Code 1.101 or later with GitHub Copilot agent mode, the Penstock extension registers the MCP server automatically in trusted workspaces when Node.js and npm are on the PATH. The extension launches ./penstockw mcp if the project has the wrapper, or npx @kern0x1b/penstock-cli mcp if not.
For manual setup in .vscode/mcp.json, VS Code uses the servers key and requires type: "stdio" rather than mcpServers:
{
"servers": {
"penstock": {
"type": "stdio",
"command": "npx",
"args": ["--yes", "@kern0x1b/penstock-cli", "mcp"]
}
}
}
JetBrains AI Assistant and Junie
For JetBrains AI Assistant, go to Settings | Tools | AI Assistant | Model Context Protocol (MCP), click Add, choose STDIO, and supply this JSON configuration:
{
"mcpServers": {
"penstock": {
"command": "npx",
"args": ["--yes", "@kern0x1b/penstock-cli", "mcp"]
}
}
}
For JetBrains Junie, add the entry under mcpServers in ~/.junie/mcp/mcp.json (global) or .junie/mcp/mcp.json (project root), or configure it in Settings | Tools | Junie | MCP Settings.
How the server finds your project
The server serves diagrams across projects. For each request it starts from the file or folder the assistant names, walks up to the nearest penstock.yaml (or the repository root), and uses that project's engine, settings and conventions.
| Kind of tool | How you point it at a project |
|---|---|
Tools that read any kind of file: show_diagram, element_context, check_diagram, diff_diagrams | The assistant passes the absolute path of a .bpmn, .dmn or .form file, in file. diff_diagrams also takes a second file of the same kind in other. |
BPMN-only tools: analyze_flow, list_scenarios, edit_diagram, layout_diagram, export_image | The assistant passes the absolute path of a .bpmn or .bpmn20.xml file, in file. |
Whole-project tools: list_diagrams, search_elements, check_code_links, run_scenarios, migrate_analyze | The assistant passes an absolute folder in the optional project. Without it, the tool uses the folders the AI client has open. run_scenarios and migrate_analyze also take a single file in file; migrate_analyze takes either file or project, not both. |
The tool that makes a file: create_diagram | The assistant passes the absolute path of the new .bpmn, .dmn or .form file, in file. The path must not exist yet. |
The folders the client has open (MCP roots)
Many AI clients tell the server which folders are open in their workspace. MCP calls these roots. When the client does, the server:
- uses those folders as the default projects for the whole-project tools,
- updates the list when the client says the folders changed,
- refuses any file or folder outside them, so the assistant cannot read outside the workspace it was given.
When the client sends no roots, the whole-project tools need an explicit absolute project. The file tools then accept any valid diagram whose path resolves to a project.
The tools
| Tool | What it does | Needs |
|---|---|---|
list_diagrams | Lists the BPMN diagrams, DMN decision files and Camunda forms of a project, as absolute paths, each with its kind: process, decision or form. | Free |
show_diagram | Describes a file. For a BPMN diagram: every element and flow with id, type, name, connections and engine properties. Read this before editing. Edits refer to these ids. For a DMN file: each decision with its hit policy, inputs, outputs, rules and the decisions, input data and knowledge it requires. For a form: its components with id, type, key, label, options and group. | Free |
element_context | Says what surrounds one element: the variables that reach it, what it reads and writes, its job types, and the job types, processes and decisions the project already uses. For a DMN file the element is a decision id and the answer is its table, the decisions that need it and the process elements that call it. For a form it is a component key or id, with the process elements that open the form. | Free |
check_diagram | Reports what is wrong, as the editor's check does: the drawing, your bpmnlint rules and, with a licence, how the process runs. For a form it reports duplicate or missing keys, and for a DMN file one that cannot be read, free of charge. Gaps and overlaps between the rules of a decision table need Pro, and Team in a pipeline; without it the answer says they were left out. | Free |
search_elements | Finds where a name is used across the project, by id or name and ignoring case: elements, processes, messages, decisions and their outputs, variables with the elements that write and read them, and form fields. It takes query and the optional project, kinds and limit. | Free |
diff_diagrams | Says what changed between two files of the same kind (BPMN, DMN or form), or between a file and its committed version (HEAD, or the revision in ref): the elements added, removed and changed, and the ids of those that only moved on the canvas or, in a form, were reordered or moved to another group. A decision table is compared by rule and cell id, and a form by component id. | Free |
migrate_analyze | Runs the Camunda 7 to 8 analysis of penstock migrate on one file or on a project, and returns as JSON the findings of each file, the effort and the blockers. It takes file or project, the optional target (a Camunda 8 version from 8.5 to 8.9, 8.8 by default) and verbose. It writes nothing. | Free |
export_image | Draws a BPMN diagram as SVG, returned as text, or as PNG, returned as an image. PNG needs puppeteer installed, as penstock export does. With out, an absolute folder, the file is written there instead. | Free |
connections | Shows the secrets and MCP clients the diagrams and element templates of a project name, where the project's own files define them (connector-secrets, .env, Docker Compose, Helm values, Spring Boot properties, MCP client configuration), what is missing, and the Camunda 8.7 property names that 8.8 renamed, as penstock connections does. It reads only; the answer holds names and places, never values. It takes project and the optional environment and against. | Free. against (compare two environments): Pro, Team in a pipeline |
agents | Lists the Camunda 8 AI agents of a project: for each, the model and provider, the prompts, the tools with the fromAi() parameters, the limits, the memory, the MCP clients with whether their configuration is found, the tool filters, and what the agents rules found. Names only, never secret values. It takes project. | Free |
drift | Compares the project's diagrams and decisions with what an environment has deployed, after the same normalisation, and says per resource whether it is in sync, ahead locally, ahead on the engine, only local, only on the engine or changed on both sides, as penstock drift does. It reads only: nothing is deployed or written, and only environments penstock.yaml declares are asked. It takes project and the optional environment and against. | Free for one environment. against: Pro, Team in a pipeline |
import_diagram | Imports a draw.io, Visio, Signavio, Bizagi or Flowable file as BPMN 2.0, or with from set to modeler reads a Camunda Modeler project folder, as penstock import does. It only previews: it returns what was converted, kept and could not be mapped. It writes only with write true, a new file inside the project root, and never over an existing one without force. It takes file and the optional from, to, write, out and force. Nothing in the imported file is ever run. | Free |
refactor_rename | Previews or applies the rename of a process variable, message, signal, error code, escalation, job type, topic, decision id, form key or process id across the project, as penstock refactor rename does. Without apply it returns the plan: every edit, and every place it refuses to touch with the reason. Applying needs the planId of that preview, so an agent cannot write what it has not shown, and it refuses when the git tree has uncommitted changes unless force is true. It takes kind, from, to and the optional project, apply, planId, acknowledge and force. | Free |
test_dmn | Runs the saved test cases of the decision tables in one DMN file, or in every DMN file of the project, and returns the outcome of each case, the rules that matched and the rules no case covers. It takes file or project. With case it saves a new case next to the file, which is a write. | Free up to 3 cases per decision. More cases and saving a case: Pro, Team in a pipeline |
migrate_agents | Moves the AI agent elements from the template versions of Camunda 8.9 and earlier to the 8.10 agent task and agent sub-process templates, as penstock migrate agents does. By default it is a dry run that previews the first 3 elements; write true replaces the files atomically. An element whose mapping cannot be proven is left untouched and listed with the reason. | Preview: Free. write: Pro, Team in a pipeline |
incident_to_scenario | Turns an incident of the project's engine into a scenario that reproduces it, as penstock incident scenario does. It takes the key of the incident or of its instance. Anything that looks like a secret is replaced by a placeholder. Reading and previewing write nothing; write saves the scenario next to the diagram's other scenarios, and run also runs it on the engine of the project, which has to be marked for tests. It stays inside the roots the client gave. | Preview: Free. write, run: Pro, Team in a pipeline |
migrate_verify | Runs the project's scenarios on the original Camunda 7 diagram on one test engine and on the converted Camunda 8 diagram on another, and reports per scenario equivalent, differs or cannot be compared, as penstock migrate verify does. Both engines must be marked for tests. It takes the optional project, target, scenarios, originalProfile and convertedProfile. | Pro, Team in a pipeline |
generate_templates | Makes one REST connector element template per operation from an OpenAPI 3, Swagger 2.0 or Postman collection file, as penstock templates generate does. It writes nothing unless write is true; the answer lists every template, whether it would be created or replaced, and the secrets to create. It takes spec and the optional out, write and secretPrefix, and stays inside the roots the client gave. | Pro, Team in a pipeline |
evidence_build | Builds the audit evidence pack of the project, as penstock evidence build does, and writes a zip or a folder inside the project. It takes the optional project, out, since, format (zip or dir) and force. It never holds a secret value. | Pro, Team in a pipeline |
refactor_bulk | Previews or applies the renames of a mapping file in order, with the same plan, refusals and limits as refactor_rename, and the same planId rule. It takes mapping and the optional project, apply, planId, acknowledge and force. | Pro, Team in a pipeline |
refactor_extract | Previews or applies moving a subprocess, or elements with one way in and one way out, into a new process file, replaced by a call activity wired through variable mappings. It refuses, with the reason, when the selection is not safe to move. It takes file, elements and processId, and the optional project, name, apply, planId and force. | Pro, Team in a pipeline |
migrate_apply | Applies the Camunda 7 to Camunda 8 migration, as penstock migrate apply does. By default it is a dry run that returns the diff and writes nothing; write true writes. only and exclude take the change ids of penstock migrate plan; an id the plan does not have, an empty list or an over-long id is refused before anything is written. It never deletes a file and never follows a symbolic link out of the project. | Pro, Team in a pipeline |
analyze_flow | Finds deadlocks, branches that run twice, elements that never run and loops with no way out, with the path of ids that leads there. Run it after edit_diagram. | Pro, Team in a pipeline |
list_scenarios | Lists every distinct way through a diagram: the decisions taken, their conditions, the steps and where it ends. | Pro, Team in a pipeline |
check_code_links | Checks every diagram against the code, with file and line. | Pro, Team in a pipeline |
edit_diagram | Changes a diagram through the editor's own modelling. Operations apply together or not at all. An edit that would break the drawing is refused, and so is a write over a diagram that changed on disk while the edit was made. dryRun shows the result without writing. It edits BPMN diagrams only. | Pro, Team in a pipeline |
layout_diagram | Runs the editor's auto layout on a BPMN diagram and writes the result in one atomic step. Elements and flows stay the same; only positions change. dryRun lists the elements that would move without writing. | Pro, Team in a pipeline |
create_diagram | Creates a BPMN diagram, a DMN decision or a Camunda form at a path that does not exist yet; the extension says which. The file is empty, or built from a spec, described below. It takes file and the optional name, description and spec. It never overwrites a file, writes atomically, and refuses a path outside the workspace roots or through a link. A file whose drawing or flow check finds an error is not written; the other findings of the check are returned with the result. | Pro, Team in a pipeline |
run_scenarios | Runs the saved test cases of a project, or of one diagram, as penstock scenarios run does, and returns which passed, failed or were skipped. The engine must be marked for tests. Traces are kept under .penstock/runs. | Pro, Team in a pipeline |
test_task | Runs one element of a diagram on the local engine the project marks for tests, as penstock test task does: the process is deployed as a test build, the path to the element is completed or mocked, then the element is completed, made to throw a BPMN error or left waiting. It returns the state of the element, what it received and sent, the variables, the incidents and the state of the instance, and removes the build. It takes file and element, and the optional variables, complete, error, hold, process and timeout. Use only one of complete, error and hold. Traces are kept under .penstock/runs. | Pro, Team in a pipeline |
edit_diagram takes file, operations and the optional dryRun. The operations are the same contract as penstock edit --ops: add, connect, set, remove and move, which shifts an element by dx and dy. A business rule task names its decision with decisionRef on Camunda 7, Operaton and CIB seven, and with decisionId on Camunda 8. penstock edit <file> --schema prints the contract for the file's engine. The whole-project tools take project. The others take file.
Receipts and the scenarios argument
Whenever an agent changes project files through one of the writing tools (edit_diagram, layout_diagram, create_diagram, migrate_apply, migrate_agents, refactor_*, generate_templates, incident_to_scenario and the saving of a case by test_dmn), Penstock records what changed and returns it in the receipt field of the result: each file with a SHA-256 before and after, the diff in the diagram's own terms, the Check result before and after with the new findings named by rule and element id, and a verdict (verified, has new findings, or not verified with the reason). It holds names, hashes and ids, never file contents or secret values. With Penstock Pro, new Check errors are handed back to the agent in the tool result, up to ai.verify.attempts times (3 by default, 0 turns it off). The saved scenarios of a change run only with scenarios: true, and only on an engine marked deployment.forTests. See AI receipt and auto-repair.
The spec of create_diagram
Without spec the file is empty, for the engine in penstock.yaml. name is the name of the diagram, the file name by default. description is the documentation of a BPMN process, or the description of a DMN decision; a form has none, and a description for one is refused. A spec that has an unknown key, or a value of the wrong kind, is refused with the place named, and nothing is written.
| File | The spec |
|---|---|
.bpmn | Exactly one of two keys. steps is a list of elements in a line, each after the one before and the first after the start event. A step has element (one of task, user-task, service-task, script-task, send-task, receive-task, business-rule-task, manual-task, call-activity, sub-process, end-event, intermediate-catch-event, intermediate-throw-event, exclusive-gateway, parallel-gateway, inclusive-gateway or event-based-gateway) and the optional name, event (message, timer, signal, error, escalation, conditional or terminate), id (Step_<n> by default) and properties. operations is a list of the operations of edit_diagram, applied to the empty diagram. |
.dmn | inputs, a list with expression and the optional label and typeRef; outputs, a list with name and the optional label and typeRef; the optional hitPolicy (UNIQUE by default, FIRST, PRIORITY, ANY, COLLECT, RULE ORDER or OUTPUT ORDER); and the optional rules, each with when (one text for each input, in order), then (one text for each output) and an optional description. typeRef is string (the default), number, boolean, integer, long, double, date, time or dateTime. |
.form | fields, a list. A field has type: textfield, textarea, number, checkbox, checklist, radio, select, taglist, datetime, text or button. An input field has a key, unique in the form, and the optional label and required. A checklist, radio, select or taglist also has options, each with label and value. A text field has text. A button has label and submits the form. |
{
"file": "/work/shop/src/main/resources/ship-order.bpmn",
"spec": {
"steps": [
{ "element": "service-task", "name": "Reserve stock" },
{ "element": "user-task", "name": "Pack the order" },
{ "element": "end-event", "name": "Order shipped" }
]
}
}
Resources and prompts
Besides tools, the server lists the diagrams, decision files and forms of the folders the client has open as MCP resources, each with its kind, and returns the text of one when the client reads it. Clients that show resources let you attach a diagram to a conversation without a tool call. Paths outside the open folders are refused, as for the tools. Without roots nothing is listed.
Two prompts are offered, both taking file: review_diagram asks the assistant to read a file, run the checks and list what to fix, most serious first, without editing; explain_process asks it to explain a process in plain language from its scenarios. Resources and prompts are free.
A tool that needs a licence you do not have appears in the tool list with a note on what it needs. Called without the licence, it says so in its error result, with how to buy or sign in. In a pipeline the paid tools need Team. See Plans and licence.
A result is bounded. When it is longer than 100,000 characters it is cut and says The result was cut at 100000 of … characters. Ask for less: one process, or a smaller diagram.
Safety
- The server runs on your machine. Nothing is sent anywhere by it. See Security and privacy.
- When the client gives roots, paths outside them are refused. Files that are not
.bpmn,.bpmn20.xml,.dmnor.formfiles are refused too, and so is a new file made through a link. - An assistant can change a diagram only with
edit_diagram,layout_diagram,migrate_apply,migrate_agentsand therefactor_*tools, make a new file only withcreate_diagram,import_diagram,generate_templates,incident_to_scenarioorevidence_build, none of which replaces a file without being told to, and write an image only withexport_imagewhen it passesout. The refactoring tools write only the plan they have just returned: applying needs itsplanId.run_scenarioswrites its traces under.penstock/runsand runs only on an engine marked for tests. Ask the assistant to usedryRunfirst, and keep your diagrams in Git so you can review the diff. A diagram that changed on disk while an edit was being made is never overwritten: the tool answers The diagram changed while the edit was being made, so it was not written over.
What you see
- The assistant lists the tools. Paid tools show a note on what they need.
- A tool call returns JSON, or a plain error message that says what is wrong.
Common problems
- The assistant does not see the tools.
- Check the
commandandargsin the entry. Node.js 22.22 or later must be on the PATH of the assistant. Runpenstock mcpby hand: it should wait silently for input. - "must be an absolute path to a diagram" or "\"project\" must be an absolute path".
- The tools take absolute paths. Ask the assistant to pass the full path, as
list_diagramsprints it. - "is outside the workspace roots".
- The path is not inside a folder the client has open. Open the project in the client, or give a path inside an open folder.
- "is not a Penstock project".
- The folder has no
penstock.yamland no repository root above it. Runpenstock initthere. - A paid tool says it needs a licence.
- Sign in on the machine that runs the server:
penstock license login.