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.

Free Reading and checking are free. Flow analysis, scenarios, code links and editing need Pro, and Team in a pipeline.

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 a few tools. 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. list_diagrams, show_diagram and check_diagram are free. The other tools 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.

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.

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 list_diagrams and check_code_links,
• 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 diagram tools then accept any valid BPMN diagram whose path resolves to a project.

The tools

edit_diagram takes file, operations and the optional dryRun. The operations are the same contract as penstock edit --ops, and penstock edit <file> --schema prints it for the file's engine. The whole-project tools take project. The others take file.

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.

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 or .bpmn20.xml diagrams are refused too.
• An assistant can change your files only with edit_diagram. Ask the assistant to use dryRun first, and keep your diagrams in Git so you can review the diff.

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 command and args in the entry. Node.js 22.22 or later must be on the PATH of the assistant. Run penstock mcp by 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_diagrams prints 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.yaml and no repository root above it. Run penstock init there.

A paid tool says it needs a licence.

Sign in on the machine that runs the server: penstock license login.