MCP tools

The IBM Workflow Runtime MCP Server exposes tools through the Model Context Protocol (MCP).

When you connect an MCP client, the server automatically provides a list of available tools with their descriptions, parameters, and schemas. Dependent on your client, you can select the tools that are needed.

The server provides two separate MCP endpoints that you can add to your MCP client:

Process Server (/process/mcp): Process and task management tools
Case Server (/case/mcp): Case management tools

Each server exposes its own set of tools when you add it to your MCP client configuration. You can combine tools from both servers.

Tool prerequisites

Important: Many tools require calling other tools first to obtain necessary information (like IDs or system identifiers).

Common patterns

Process Initiation: get_exposed_processes → get_process_model → start_process
Task Completion: search_tasks → get_task_details → get_task_model → complete_task
Task Assignment: search_tasks → get_users → assign_task_to_user
Process Details: search_processes → get_process_details or get_process_documents
Case Information: list_case_types → search_cases → get_case_summary

Process management tools

Table 1. Process management tools
Tool	Description	Usage
`get_exposed_processes`	Retrieves all exposed process models that can be started	Call this tool first to discover available processes before you start one
`get_process_model`	Retrieves a process model with input and output parameters and JSON schema validation details	Call this tool after `get_exposed_processes` to inspect the schema before you start a process
`start_process`	Starts a process instance with input parameters	Call `get_exposed_processes` Select the target process version Call `get_process_model` Call `start_process` with validated inputs
`terminate_process`	Terminates a process instance	Use `search_processes` first to obtain the `process_instance_id` and `system_id`
`get_process_details`	Retrieves detailed information for a specific process instance, including metadata, business data, and associated tasks	Use `search_processes` first to obtain the `process_instance_id` and `system_id`
`get_process_documents`	Retrieves documents that are attached to a process instance	Use `search_processes` first to obtain the `process_instance_id` and `system_id`

Search helper tools

Table 2. Search helper tools
Tool	Description	Usage
`get_search_parameters`	Retrieves available parameters for searches	Call this tool before you use `search_processes` or `search_tasks`
`explain_search_processes`	Provides guidance and examples for constructing advanced search queries for process instances	Read this information before you construct queries for `search_processes`
`search_processes`	Searches for process instances by using an advanced search query	Call `explain_search_processes` and `get_search_parameters` first
`explain_search_tasks`	Provides guidance and examples for constructing advanced search queries for task instances	Read this information before you construct queries for `search_tasks`
`search_tasks`	Searches for task instances by using an advanced search query	Call `explain_search_tasks` and `get_search_parameters` first

Task management tools

Table 3. Task management tools
Tool	Description	Usage
`get_task_details`	Retrieves detailed information for a specific task instance	Use `search_tasks` first to obtain the `task_instance_id` and `system_id`
`claim_task`	Claims a task instance for the current user	Use `search_tasks` first to obtain the `task_instance_id` and `system_id`
`assign_task_to_user`	Assigns a task instance to a specific user	Use `search_tasks` to get `task_instance_id` and `system_id` Use `get_users` to get the `user_name`
`get_task_model`	Retrieves the task model with input and output parameters and JSON schema details	Use `search_tasks` to get `system_id` Use `get_task_details` to get `service_id` and `service_snapshot_id`
`complete_task`	Completes a task instance with optional output parameters	Use `search_tasks` to get `task_instance_id` and `system_id` Use `get_task_model` to understand required output parameters
`update_task_metadata`	Updates the due date or priority for a task instance	Use `search_tasks` first to obtain the `task_instance_id` and `system_id`
`update_task_business_data`	Updates business data for a task instance	Use `search_tasks` to get `task_instance_id` and `system_id` Use `get_task_model` to understand the expected business data structure
`get_users`	Retrieves users who can be assigned to a specific task instance	Use `search_tasks` first to obtain the `system_id` and `task_instance_id`
`assign_task_to_team`	Assigns a task instance back to its original team or owner	Use `search_tasks` first to obtain the `task_instance_id` and `system_id`

Case management tools

Table 4. Case management tools
Tool	Description	Usage
`get_case_types`	Retrieves available case types from Business Automation Workflow	Call this tool before you create or search for cases
`search_case_instances`	Searches for case instances by using a keyword and optional filters	Use this tool to find cases by keyword or metadata
`get_case_summary`	Retrieves case information including properties, stage, activities, and tasks	Use this tool to get a complete overview of a case instance
`get_current_case_stage`	Retrieves the current stage information for a case	Use this tool to determine the active case stage
`get_case_activities`	Retrieves activities for a case instance	Use this tool to inspect tasks and activities that are associated with a case
`manage_case_activity`	Lists or starts activities that can be started in a case	Use `list` to see available activities, then use `start` to initiate one
`get_tasks_by_case_role`	Retrieves tasks that are assigned to a specific case role	Use this tool to inspect tasks that are assigned to a specific role
`get_all_roles_for_current_user`	Retrieves all roles that the current authenticated user belongs to	Use this tool when the solution name or role name is not already known
`add_case_comment`	Adds a comment to a case instance	Use this tool to add notes or comments to a case
`add_case_document`	Adds document references to a case instance	Use this tool to attach documents to a case
`list_case_documents`	Lists documents that are associated with a case instance	Use this tool to inspect documents that are attached to a case

Parameter naming

process_instance_id: Process instance ID
task_instance_id: Task instance ID
system_id: System identifier (required for Process Federation Server (PFS) scenarios where multiple Business Automation Workflow systems are federated)
case_id: Case instance ID

Process Federation Server System ID usage

The system_id parameter is used to identify which Business Automation Workflow system to target in Process Federation Server (PFS) deployments. In PFS scenarios:

Multiple Business Automation Workflow systems are federated together
Each system has a unique identifier
Search tools (search_processes, search_tasks) return the system_id for each result
This system_id must be passed to subsequent tools that operate on that specific instance

Important: Always obtain the system_id from search results before calling tools that require it. In non-federated environments, the system_id is optional.

Federation of Business Automation Workflow traditional systems is not supported.

Tool dependencies

Many tools require that you call other tools first:

Before start_process: Call get_exposed_processes and get_process_model
Before terminate_process, get_process_details, and get_process_documents: Call search_processes
Before get_task_details, claim_task, assign_task_to_user, complete_task, and similar task operations: Call search_tasks
Before assign_task_to_user: Call get_users
Before complete_task: Call get_task_model

Data type support

Inputs and outputs can use the simple types that are included with the product, such as String, Integer, Boolean, Decimal, Date, Time or JSONObject, from the System Data toolkit or custom business objects. Types from other system toolkits are not supported.