operaton-mcp

MCP server exposing the full Operaton BPMN/DMN REST API to AI assistants

Operaton is an open-source BPMN and DMN workflow engine. operaton-mcp is a Model Context Protocol (MCP) 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):

{
  "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

{
  "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.

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

"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

"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

"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

# 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 for guidelines on how to contribute, commit conventions, and the PR process.

License

Apache 2.0 — see LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 73 Commits
.github		.github
_bmad-output		_bmad-output
config		config
docs		docs
resources		resources
scripts		scripts
src		src
test		test
.commitlintrc.json		.commitlintrc.json
.gitignore		.gitignore
.nvmrc		.nvmrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
check-deployment.mjs		check-deployment.mjs
commitlint.config.ts		commitlint.config.ts
jreleaser.yml		jreleaser.yml
operaton-mcp.iml		operaton-mcp.iml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

operaton-mcp

Features

Quick Start

Authentication

Basic Auth

OIDC / Client Credentials

Access Control Guards

OPERATON_GUARD — overall mode

OPERATON_DENY_RESOURCES — block specific domains

OPERATON_DENY_OPS — block specific operation classes

Combining guards

Available Tools

processDefinition

deployment

processInstance

task

job

jobDefinition

incident

user

group

history

decision

migration

Example Prompts

Development

Project Structure

Out of Scope

Contributing

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`OPERATON_GUARD` — overall mode

`OPERATON_DENY_RESOURCES` — block specific domains

`OPERATON_DENY_OPS` — block specific operation classes

`processDefinition`

`deployment`

`processInstance`

`task`

`job`

`jobDefinition`

`incident`

`user`

`group`

`history`

`decision`

`migration`

Packages