# Camunda (BPMN Engine) MCP MCP > Camunda (BPMN Engine) MCP lets your AI agent orchestrate complex business processes using BPMN standards. You can start new workflows, monitor real-time incidents, assign human tasks, and retrieve process definitions—all without leaving your chat client. It gives you conversational control over operational workflow execution. ## Overview - **Category:** developer-tools - **Price:** Free - **Tags:** bpmn, workflow-automation, process-orchestration, camunda-8, human-tasks ## Description Managing complex business logic used to mean jumping between three different dashboards: the modeler, the task queue, and the incident log. Now, your AI agent handles it all. Connect this MCP through Vinkius, and treat your entire process suite like a single API endpoint. You can initiate new processes with specific variables; if that process hits a snag, you don't wait for an alert—you ask your agent to find and inspect the incident details immediately. Need to get work done? Your agent searches for pending tasks assigned to you and handles completion. This isn't just monitoring; it’s active orchestration from your IDE or chat client. ## Tools ### activate_jobs Marks jobs for workers as active so they can be processed. ### assign_user_task Assigns a required human task to a specific user account. ### complete_job Marks an activated job instance as successfully completed. ### complete_user_task Completes a human task, allowing the workflow to proceed using provided variables. ### deploy_resources Deploys new BPMN, DMN, or Form resources into the running process engine. ### fail_job Manually marks a job as failed; this action often triggers retries or alerts. ### get_incident Retrieves detailed information about a specific process incident. ### get_process_definition_xml Fetches the raw BPMN XML definition for a specified process model. ### get_process_instance Retrieves all current status details for an active or completed process instance. ### get_topology Returns the cluster topology, showing which nodes are online and how they connect. ### get_user_task_form Retrieves the associated form data linked to a pending user task. ### get_user_task Gets specific details for a single user task instance. ### get_variable Pulls the current value of any process or local variable by name. ### search_groups Finds and lists available user groups within the system. ### search_incidents Searches for specific process incidents based on criteria like date or severity. ### search_jobs Runs a query to find job instances matching specified search parameters. ### search_process_definitions Searches through all deployed process definitions by name or criteria. ### search_process_instances Queries and lists process instances based on current state or variables. ### search_tenants Finds and filters available tenants for multi-tenant applications. ### search_user_tasks Searches across all active user tasks to find pending items assigned to users or groups. ### search_users Finds and lists available user accounts by name or email. ### search_variables Searches the entire process memory for specific variable names or values. ### start_process_instance Initiates a brand new workflow instance, allowing you to pass initial data variables. ### throw_job_error Manually simulates an error condition within a job worker for testing purposes. ### unassign_user_task Removes a user task assignment, returning the item to an unassigned state. ## Prompt Examples **Prompt:** ``` Start a new instance of the 'order-fulfillment' process with orderId 550. ``` **Response:** ``` I've started the process instance for 'order-fulfillment'. The new instance key is 2251799813685249 and it's currently active. ``` **Prompt:** ``` Search for all pending user tasks assigned to 'admin'. ``` **Response:** ``` I found 3 pending tasks for 'admin'. The most urgent is 'Approve Invoice' (Key: 4503599627370501). Would you like to see the details or complete it? ``` **Prompt:** ``` Show me the BPMN XML for process definition 2251799813685250. ``` **Response:** ``` Retrieving the BPMN XML... I've fetched the definition. It contains a start event, two service tasks ('Fetch Data', 'Process Payment'), and an end event. ``` ## Capabilities ### Start and Manage Processes Initiate new workflows and track the status of existing process instances. ### Handle Human Tasks Locate, assign, and complete pending tasks that require human intervention to move a workflow forward. ### Diagnose Failures and Incidents Search for system incidents and jobs to quickly identify process bottlenecks or failures in real time. ### Examine Workflow Structure Retrieve the full XML definitions of processes or search through deployed models to understand the underlying logic. ### Monitor System Health Check the cluster topology and job status directly, confirming all nodes are online and functional. ## Use Cases ### Incident Response (Ops) The fulfillment system is failing. Instead of logging into the Operate dashboard, the engineer asks their agent to `search_incidents`. The agent returns a list, and by running `get_incident` on the key ID, they instantly see which step failed and why. ### Feature Development (Dev) A developer needs to test how an order fulfillment process handles payment failure. They use their agent to run `start_process_instance` with a specific variable set, then manually trigger a job error using `throw_job_error` to validate the retry logic. ### Workflow Audit (BA) A business analyst wants to know what steps are in place for 'Invoice Approval.' They ask their agent to retrieve the XML definition using `get_process_definition_xml`, getting the full technical map without touching any UI. ### User Management (Ops) A manager needs to track all outstanding tasks for a department. The agent runs `search_user_tasks` across the entire system, giving them a list of pending items and who needs to act on them. ## Benefits - You don't need to jump between the Modeler and Operate dashboards. Your AI agent acts as a single technical process orchestrator, letting you inspect definitions using `get_process_definition_xml` directly in chat. - When things break, find them instantly. Instead of navigating incident logs, use `search_incidents` or run `get_incident` to get the specific root cause and status summary immediately. - Manage human input effortlessly. You can search for all pending tasks using `search_user_tasks`, then assign one with `assign_user_task`, and finally complete it with `complete_user_task`—all in a conversational flow. - Debugging is faster than ever. Need to know why a job failed? Use `get_process_instance` or check the cluster health using `get_topology` for immediate system status confirmation. - Testing new flows is streamlined. You can start process instances with specific data variables (`start_process_instance`) and then simulate failure by running `throw_job_error`, all within a controlled test run. ## How It Works The bottom line is: you manage complex workflows conversationally, treating your process engine like an extension of your terminal. 1. Subscribe to this MCP and provide your Camunda Base URL and Bearer Token. 2. Reference a specific process need with your agent (e.g., 'Find all failed jobs for the fulfillment service'). 3. Your agent runs the necessary tool calls, returns structured data on incidents or tasks, and presents a simple summary in the chat. ## Frequently Asked Questions **How do I check if a specific job failed using activate_jobs?** You don't use `activate_jobs` to check for failures. Use `search_jobs` first, and then run `get_incident` on the resulting IDs to determine why it failed. **Can I start a new process instance using start_process_instance?** Yes. You simply tell your agent you want to start a process (e.g., 'Start order fulfillment for ID 123'). The tool handles the initiation and passes the necessary variables. **What is the difference between search_user_tasks and get_user_task?** `search_user_tasks` finds all pending tasks across the system, letting you scope your query (e.g., by user or group). `get_user_task` retrieves the full detail for one specific task ID. **If I need to know what variables are in a process, should I use get_variable?** Yes, that's the right call. Use `get_variable` and provide the name of the variable you want. It returns its current value within the specified process context. **How do I change who is responsible for a task using assign_user_task?** You use `assign_user_task` to re-route ownership. This function lets you take an existing user task and immediately assign it to a different specific user, managing the assignment history automatically. **If I suspect process failures, how do I find them using search_incidents?** Run `search_incidents` to pinpoint workflow breakdowns. This tool allows you to filter incidents by time or job ID, giving you the exact details needed to troubleshoot a failing business process step. **What is the command for updating and deploying new BPMN models?** `deploy_resources` handles all model updates. You call this tool to push new BPMN, DMN, or Form definitions into the Camunda engine, making them available for use in running processes. **How can I check the overall health of my Camunda cluster?** Use `get_topology` to monitor system health. This function pulls data on your entire cluster's topology and partition status, letting you see if all nodes are connected and operating correctly. **Can I start a process instance with specific input data?** Yes! Use the `start_process_instance` tool and provide the `variables` JSON object. The AI will map your data to the process requirements automatically. **How do I find all tasks currently assigned to a specific user?** You can use the `search_user_tasks` tool with a filter like `{"assignee": "user-id"}`. The agent will return a list of all active human tasks for that person. **Is it possible to see why a process instance is stuck?** Yes. Use `search_incidents` to find errors in the cluster, and then `get_incident` with the specific key to see the error message and stack trace.