Operaton MCP
# operaton-mcp
> MCP server exposing the full Operaton BPMN/DMN REST API to AI assistants
[](https://www.npmjs.com/package/@operaton/mcp)
[](https://github.com/operaton/operaton-mcp/actions/workflows/ci.yml)
[](https://opensource.org/licenses/Apache-2.0)
[](https://nodejs.org)
[Operaton](https://operaton.org) is an open-source BPMN and DMN workflow engine. **operaton-mcp** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes 300+ Operaton REST API operations as MCP tools, enabling AI assistants like Claude to interact directly with your workflow engine — deploying processes, managing instances, handling tasks, and querying history.
## Features
- **Full REST API coverage** — 300+ operations across process definitions, instances, tasks, jobs, incidents, users, history, and decisions
- **Multi-engine support** — connect to multiple Operaton instances from a single server
- **Basic Auth & OIDC** — supports both HTTP Basic authentication and OAuth2 client credentials (OIDC)
- **Access control guards** — configurable operation guards to restrict what the AI can do (`OPERATON_GUARD`, `OPERATON_DENY_RESOURCES`, `OPERATON_DENY_OPS`)
- **Zero-setup with npx** — run without installation via `npx @operaton/mcp`
- **Type-safe** — written in TypeScript with strict type checking
## Quick Start
> **Prerequisites:** Node.js ≥ 22, a running Operaton instance.
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
```json
{
"mcpServers": {
"operaton": {
"command": "npx",
"args": ["-y", "@operaton/mcp"],
"env": {
"OPERATON_BASE_URL": "http://localhost:8080/engine-rest",
"OPERATON_USERNAME": "demo",
"OPERATON_PASSWORD": "demo"
}
}
}
}
```
Restart Claude Desktop — you're ready to use natural-language commands against your Operaton instance.
## Authentication
### Basic Auth
| Variable | Required | Description |
|---|---|---|
| `OPERATON_BASE_URL` | Yes | Operaton REST API URL, e.g. `http://localhost:8080/engine-rest` |
| `OPERATON_USERNAME` | Yes | Basic Auth username |
| `OPERATON_PASSWORD` | Yes | Basic Auth password |
| `OPERATON_ENGINE` | No | Operaton engine name (default: `default`) |
| `OPERATON_SKIP_HEALTH_CHECK` | No | Set `true` to skip startup connectivity check |
### OIDC / Client Credentials
| Variable | Required | Description |
|---|---|---|
| `OPERATON_BASE_URL` | Yes | Operaton REST API URL |
| `OPERATON_CLIENT_ID` | Yes | OAuth2 client ID |
| `OPERATON_CLIENT_SECRET` | Yes | OAuth2 client secret |
| `OPERATON_TOKEN_URL` | Yes | Token endpoint URL |
```json
{
"mcpServers": {
"operaton": {
"command": "npx",
"args": ["-y", "@operaton/mcp"],
"env": {
"OPERATON_BASE_URL": "https://operaton.example.com/engine-rest",
"OPERATON_CLIENT_ID": "mcp-client",
"OPERATON_CLIENT_SECRET": "your-secret",
"OPERATON_TOKEN_URL": "https://keycloak.example.com/realms/myapp/protocol/openid-connect/token"
}
}
}
}
```
> For multi-engine deployments, see the [Configuration Guide](docs/configuration.md).
## Access Control Guards
Guards let you constrain what the AI assistant is allowed to do. They are enforced at the MCP dispatch layer — blocked calls never reach Operaton.
### `OPERATON_GUARD` — overall mode
| Value | Effect |
|---|---|
| *(unset)* or `unrestricted` | All operations permitted (default) |
| `read-only` | Only read operations permitted; all mutating tools are hidden from the AI and blocked if called directly |
| `safe` | Read and reversible mutations permitted; irreversible operations (delete, deploy, migrate-execute) are hidden from the AI and blocked if called directly |
```json
"env": {
"OPERATON_GUARD": "read-only"
}
```
### `OPERATON_DENY_RESOURCES` — block specific domains
Comma-separated list of resource domains to deny entirely. Both reads and writes in the named domain are blocked.
Valid domains: `process-definitions`, `deployments`, `instances`, `tasks`, `jobs`, `incidents`, `users-groups`, `decisions`, `migrations`, `infrastructure`
```json
"env": {
"OPERATON_DENY_RESOURCES": "users-groups,decisions"
}
```
### `OPERATON_DENY_OPS` — block specific operation classes
Comma-separated list of operation classes to deny regardless of domain.
Valid classes: `read`, `create`, `update`, `delete`, `suspend-resume`, `deploy`, `migrate-execute`, `migrate-control`
```json
"env": {
"OPERATON_DENY_OPS": "delete,deploy"
}
```
### Combining guards
All three env vars can be set together. The most restrictive rule that matches a call wins. Precedence: `OPERATON_GUARD` → `OPERATON_DENY_RESOURCES` → `OPERATON_DENY_OPS`.
Guards are enforced at two layers. Forbidden tools are **hidden from the tool list** — the AI never sees them and cannot propose their use. If a forbidden tool is called directly despite being absent from the list, the call-time guard rejects it as a second line of defence. When a call is blocked, the MCP client receives an `isError` response naming the blocked operation and the guard rule that triggered. The server logs a WARN entry with full detail including a remediation hint.
> **Production tip:** Use `OPERATON_GUARD=safe` to prevent the AI from accidentally deleting definitions or executing migrations while still allowing it to start instances, complete tasks, and manage jobs.
## Available Tools
### `processDefinition`
Manage deployed process definitions — browse, inspect, suspend, and delete BPMN definitions.
- **list** — query definitions with optional filters (key, name, version, tenant); count total matches
- **get by ID / key** — retrieve definition metadata for a specific ID or latest by key
- **get XML** — fetch BPMN 2.0 XML for a definition by ID or key
- **statistics** — process-level and activity-level statistics across all running instances
- **suspend by key** — suspend or resume all instances belonging to a definition
- **delete by ID / key** — remove a definition (and optionally its instances and history)
- **restart instances** — restart historic process instances synchronously or asynchronously
- **set history TTL** — update the history time-to-live for a definition
- **get called processes** — list static called process definitions for a given definition
### `deployment`
Deploy, inspect, and manage Operaton deployments (BPMN, DMN, CMMN, and form files).
- **create** — upload a BPMN/DMN/CMMN resource to create a new deployment
- **list** — query deployments with optional filters; count total matches
- **get by ID** — retrieve metadata for a specific deployment
- **list resources** — list all resources included in a deployment
- **redeploy** — create a new deployment from the resources of an existing one
- **delete** — remove a deployment by ID
### `processInstance`
Start and manage the lifecycle of running process instances.
- **start** — start a new instance by definition ID or key, with optional business key and variables
- **list** — query active instances with filters; count total matches
- **get** — retrieve metadata for a specific instance
- **get activity tree** — inspect the current activity instance hierarchy
- **suspend / resume** — suspend or resume execution of an instance or a group of instances
- **delete** — terminate and remove a process instance
- **get / set variables** — read or write individual or multiple process variables
- **set suspension** — bulk suspend/resume by definition ID, key, or tenant
### `task`
Query and manage the full lifecycle of user tasks.
- **list** — query tasks with rich filter criteria; count total matches
- **get** — retrieve a task by ID
- **claim / unclaim** — assign or release a task
- **complete** — complete a task with optional output variables
- **delegate** — delegate a task to another user
- **resolve** — resolve a delegated task back to the owner
- **set assignee** — directly set or change task assignee
- **create / update** — create a standalone task or update task properties
- **get / set variables** — read or write task-local variables
- **throw BPMN error** — trigger a BPMN error boundary event from a task
### `job`
Inspect and control asynchronous jobs (timers, async continuations, retries).
- **list** — query jobs with filters; count total matches
- **get** — retrieve a job by ID
- **trigger execution** — execute a job immediately (bypass timer)
- **suspend / resume** — suspend or resume a job
- **set retries** — update the retry count on a failed job
- **get stack trace** — retrieve the exception stack trace for a failed job
### `jobDefinition`
Manage job definitions — the templates from which individual jobs are created.
- **list** — query job definitions with filters
- **get** — retrieve a job definition by ID
- **set suspension** — suspend or activate job definitions by process definition
### `incident`
Query and resolve process incidents (failed jobs, failed external tasks, etc.).
- **list** — query open incidents with filters; count total matches
- **get** — retrieve an incident by ID
- **resolve** — resolve an open incident
### `user`
Manage Operaton users and their credentials.
- **list** — query users with filters
- **get profile** — retrieve a user's profile information
- **create** — create a new user with profile and credentials
- **update profile** — update a user's display name and email
- **update password** — change a user's password
- **delete** — remove a user
- **unlock** — unlock a user account after too many failed logins
### `group`
Manage Operaton groups and their memberships.
- **list** — query groups with filters
- **create / delete** — create or remove a group
- **add / remove member** — manage group membership
### `history`
Query the audit trail of completed and historic process data.
- **list process instances** — query finished or active process instances in history
- **list activity instances** — query historic activity executions
- **list task instances** — query historic task completions and assignments
- **list variable instances** — query historic variable values
- **list incidents** — query historic incidents (including resolved)
- **list job logs** — query historic job execution log entries
- **list user operations** — query the audit log of user operations (claims, completions, etc.)
### `decision`
Deploy and evaluate DMN decision tables.
- **list** — query deployed decision definitions
- **get by key** — retrieve a decision definition by key
- **get XML by key** — fetch DMN XML for a decision
- **evaluate** — evaluate a decision table with input variables
- **list requirements** — list decision requirement diagrams (DRDs)
### `migration`
Discover, plan, execute, monitor, and audit process instance migrations between definition versions.
- **listMigratable** (`processInstance_listMigratable`) — list active instances eligible for migration with per-instance eligibility and call-activity blocking conditions
- **getMigrationCandidates** (`processDefinition_getMigrationCandidates`) — compare source and target definition activities; returns auto-mappable pairs, unmapped source activities, and new target activities
- **generatePlan** (`migration_generatePlan`) — generate a migration plan with auto-mapped instructions and a list of unmapped activities requiring explicit mapping
- **validatePlan** (`migration_validatePlan`) — validate a migration plan against a set of instances; returns typed errors, sampled-validation flag, and consequence disclosure
- **executeBatch** (`migration_executeBatch`) — execute a migration plan asynchronously with auto-chunking; supports dry-run mode
- **suspendBatch** (`migration_suspendBatch`) — suspend one or more active migration batches
- **resumeBatch** (`migration_resumeBatch`) — resume one or more suspended migration batches
- **deleteBatch** (`migration_deleteBatch`) — cancel (delete) one or more migration batches
- **listBatches** (`migration_listBatches`) — list active migration batches, optionally filtered by suspended state
- **awaitBatch** (`migration_awaitBatch`) — poll migration batches until completion or timeout; returns aggregated progress
- **getBatchStatus** (`migration_getBatchStatus`) — get current job counts and suspension state for a single batch
- **getBatchFailures** (`migration_getBatchFailures`) — retrieve per-instance failure details including error messages and stack traces
- **retryFailedJobs** (`migration_retryFailedJobs`) — reset retries on all failed migration jobs in one or more batches
- **getBatchSummary** (`migration_getBatchSummary`) — aggregate post-migration summary across batch IDs: submitted, succeeded, failed, duration
- **listAuditEntries** (`migration_listAuditEntries`) — query the user operation log for migration audit entries with operator, timestamp, and definition filters
- **listHistoricBatches** (`migration_listHistoricBatches`) — query the history log for completed migration batches with date-range and completion-state filters
## Example Prompts
**Deployments & Definitions**
> "Deploy this BPMN file to Operaton and name it `loan-approval-v3`."
> "List all deployed versions of the `invoice-approval` process."
> "Show me the BPMN XML for the latest version of the `onboarding` process."
**Process Instances**
> "Start a new `invoice-approval` process with business key `INV-2024-001` and set the `amount` variable to 15000."
> "List all active instances of the `loan-approval` process."
> "What variables are currently set on process instance `abc-123`?"
**User Tasks**
> "Show me all unassigned tasks for the `approvers` group."
> "Claim task `task-456` for user `john.doe`."
> "Complete the approval task for invoice INV-2024-001 and set `approved = true`."
**Operations & Incidents**
> "Are there any failed jobs with no retries left?"
> "Reset the retry count to 3 for job `job-789` and trigger immediate execution."
> "List all open incidents for the `payment-processing` process."
**History & Audit**
> "Show me all completed `invoice-approval` instances from last week."
> "Who completed the approval task for business key `INV-2024-001`, and when?"
**Decisions**
> "Deploy this DMN decision table for loan eligibility checking."
> "Evaluate the `credit-check` decision with `income = 50000` and `creditScore = 720`."
## Development
```bash
# Install dependencies (triggers code generation automatically)
npm install
# Run code generation manually
npm run generate
# Build (generate + compile + alias rewrite)
npm run build
# Watch mode for local development
npm run dev
# Run all tests (unit + smoke)
npm test
# Run integration tests (requires live Operaton instance)
OPERATON_BASE_URL=http://localhost:8080/engine-rest \
OPERATON_USERNAME=demo \
OPERATON_PASSWORD=demo \
npm run test:integration
```
### Project Structure
```
src/
index.ts — MCP server entry point
config.ts — Configuration loading (env vars + config file)
auth/
token-manager.ts — OIDC client credentials token manager
http/
client.ts — Operaton HTTP client (Basic + OIDC auth)
errors.ts — Error normalization with BPM-domain hints
generated/ — Build artifact (gitignored); produced by npm run generate
tools/ — Curated tool wrappers (hand-written)
config/
tool-manifest.json — Full curation manifest (name, description, frMapping per operationId)
tool-manifest.fixture.json — Fixture for development/testing
resources/
operaton-rest-api.json — Authoritative OpenAPI 3.0.2 spec (never modify)
scripts/
generate.ts — Code generation pipeline
docs/
configuration.md — Full configuration reference
```
## Out of Scope
The following capabilities are not available in the current release:
- **Autonomous monitoring** — AI-initiated process health watching and alerting (planned: Vision phase)
- **BPMN generation** — natural language → BPMN authoring and AI-assisted process design (planned: Growth phase)
- **Prompt templates** — guided scenario workflows for common operational tasks (planned: Growth phase)
- **UI or dashboard** — no web interface; operaton-mcp is a pure MCP server
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute, commit conventions, and the PR process.
## License
Apache 2.0 — see [LICENSE](LICENSE) for details.
TDQS
Scored across 105 tools
Most tools target distinct resource/action pairs, and ID-vs-key variants are generally explained. However, deployment_create, processDefinition_deploy, and decision_deploy overlap on artifact deployment, while task_setAssignee overlaps with task_claim and task_update; at 105 tools, misselection is likely.
Names mostly follow a predictable resource_action pattern such as task_complete, processInstance_get, and migration_executeBatch. There are minor deviations in casing and operation grouping (e.g. getById/getByKey camelCase actions, deployment_create vs processDefinition_deploy), but the convention remains readable.
105 tools is far beyond a well-scoped MCP surface and is extreme for this domain. Many ID/key variants, migration batch lifecycle operations, and separate list/count/get tools could have been consolidated.
The surface covers core BPM lifecycle operations widely: definitions, instances, tasks, jobs, incidents, deployments, history, users, groups, decisions, and migration. Some notable gaps remain, such as external tasks, message/signal correlation, tenant/authorization management, and form handling, but agents can work around most core workflows.