Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Colba MCP Server list my pending approval requests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This server implements the Model Context Protocol (MCP) specification for the Colba workflow automation platform, enabling AI agents (e.g., Claude Desktop, Cursor, or custom autonomous agents) to interact with approval requests, processes, and business workflow creation directly on behalf of users.
The server is written in Python 3.12+ and uses the mcp library. We recommend using uv for fast, isolated execution.
uv (Recommended)Ensure uv is installed. No pre-installation step is required — uv will execute the server and automatically manage dependencies.
pipFrom the directory containing pyproject.toml, run:
pip install -e .Related MCP server: Automatisch MCP Server
The MCP server is configured via the following environment variables:
Variable | Description | Default Value |
| Base URL of the running Colba REST API |
|
| Your personal API member token ( | Required |
You can generate a member API token and a ready-to-use configuration file in the Colba Admin Panel underSettings → MCP Agent Integration.
Edit your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the following entry to mcpServers:
{
"mcpServers": {
"colba": {
"command": "uv",
"args": [
"run",
"--quiet",
"--directory",
"PATH_TO_PROJECT_ROOT",
"python",
"-m",
"colba_mcp"
],
"env": {
"COLBA_API_URL": "http://localhost:9000",
"COLBA_TOKEN": "tk_live_your_token_here"
}
}
}
}ReplacePATH_TO_PROJECT_ROOT with the absolute path to your cloned colba repository (e.g., /Users/username/Projects/colba).
Go to Settings > Features > MCP.
Click + Add New MCP Server.
Fill in the parameters:
Name: colba
Type: command
Command:
uv --directory PATH_TO_PROJECT_ROOT run --quiet python -m colba_mcpAdd environment variables:
COLBA_API_URL = http://localhost:9000
COLBA_TOKEN = tk_live_your_token_here
The MCP server exposes the following tools to AI agents:
list_pipelinesRetrieve available workflow templates and required input header schemas.
Example prompt: "What workflow pipelines can I start?"
start_processStart a new workflow process instance for a template.
Parameters:
template_id (string, UUID): Template identifier.
payload (object): Initial form data payload.
Example prompt: "Start a 'Travel Expense' process with amount 1500 USD and purpose 'Conference'"
list_processesList workflow process instances with status and pagination filters.
Parameters:
status (string, optional): Filter status (active, completed, rejected, failed).
pipeline_id (string, optional): Filter by pipeline template UUID.
limit (integer, optional, default: 50, max: 200).
offset (integer, optional, default: 0).
Example prompt: "Show my last 10 active processes"
list_pending_requestsFetch approval requests waiting for action by the current user/agent.
Parameters:
limit (integer, optional, default: 50).
offset (integer, optional, default: 0).
Example prompt: "Are there any pending requests requiring my approval?"
get_process_detailsGet detailed state and context variables of a process instance.
Parameters:
process_id (string, UUID).
verbose (boolean, optional, default: false): If true, returns full pipeline structure (pipeline_config).
Example prompt: "What is the status of process abc-123?"
get_request_detailsRetrieve complete approval request payload and valid available actions.
Parameters:
request_id (string, UUID).
Example prompt: "Show details for request xyz-456"
submit_decisionSubmit an approval decision for a pending request.
Parameters:
request_id (string, UUID).
status (string): Selected action identifier (must match an ID from available_actions).
comment (string, optional).
Example prompt: "Approve request xyz-456 with comment 'Budget approved'"
get_pipeline_generation_rulesRetrieve the official specification and validation rules for generating pipeline JSONs.
Example prompt: "Get the rules for creating a pipeline JSON"
create_pipelineCreate a new workflow pipeline template in Colba.
Parameters:
name (string): Template title (e.g., "Procurement Invoice Approval").
pipeline_config (object): Valid pipeline JSON configuration matching docs://skills/workflow_json_creation.
description (string, optional): Human-readable summary.
Example prompt: "Create a new travel request pipeline template with manager approval and budget verification nodes"
Agents can manage a public form_start widget with get_pipeline_embed,
enable_pipeline_embed, refresh_pipeline_embed, and
disable_pipeline_embed. get_pipeline_embed returns the ready-to-paste
script_tag; the generated script contains no credentials.
list_custom_fieldsRetrieve all registered global custom fields in the organization.
Example prompt: "Show all custom fields configured in the system"
list_membersList all active members (users/employees) in the organization.
Parameters:
query (string, optional): Search string to filter members by name.
Example prompt: "Show all members or search for 'Alice'"
list_workgroupsList the organizational hierarchy (departments and locations).
Example prompt: "Show the departments tree"
list_vendorsList all registered vendors/counterparties in the organization.
Example prompt: "Show all vendors"
update_pipelineUpdate an existing workflow pipeline template.
Parameters:
template_id (string, UUID): Template identifier.
pipeline_config (object, optional): Updated JSON configuration.
name (string, optional): New template name.
description (string, optional): New description.
Example prompt: "Rename pipeline template 'abc' to 'xyz'"
update_custom_fieldUpdate an existing custom field or global field registration.
Parameters:
field_id (string, UUID): Custom field identifier.
label (string, optional): New display label.
options (object/array, optional): New choices or source.
is_active (boolean, optional): Active status.
Example prompt: "Mark custom field 'tax_rate' as inactive"
get_update_logRetrieve the update log and changelog of the Colba MCP server.
Example prompt: "Show recent MCP server updates and changelog"
list_blueprintsList all available workflow pipeline blueprints that can be instantiated.
Parameters:
category (string, optional): Filter by category.
query (string, optional): Search query to filter by name.
Example prompt: "Show all HR blueprints"
get_blueprintRetrieve the full configuration of a specific pipeline blueprint.
Parameters:
blueprint_id (string, UUID): Blueprint identifier.
Example prompt: "Get details for blueprint 'xyz'"
instantiate_blueprintCreate a new pipeline template in the current organization based on a blueprint.
Parameters:
blueprint_id (string, UUID): Blueprint identifier.
Example prompt: "Create template from blueprint 'abc'"
docs://skills/workflow_json_creationThe official specification and validation rules for creating pipeline JSON structures in Colba.
Includes node type hierarchies (prioritizing action with action_type: "integration"), output_enum validation, escalations policies, condition dotted-path syntax, form field types (type: "array" for line items), and validation checklists.
An external agent can fetch this resource via read_resource before generating a new pipeline JSON.
docs://mcp/update_logThe official update log and changelog of the Colba MCP server, reflecting all newly added tools, features, and notifications about client restarts.
generate_pipeline_jsonSystem prompt template that automates instruction setup for an LLM agent.
Arguments:
user_requirements: Textual description of desired business process requirements.
Output: Loads the full specification docs://skills/workflow_json_creation and formats a strict generation prompt for the LLM.
Deactivate/archive a workflow pipeline template. template_id: UUID of the template (MUST use the 'id' field from list_pipelines, NOT 'pipeline_id').
Inputs: template_id (required).
Create a custom metadata field for workflows. name: Identifier name (alphanumeric/snake_case). label: Human readable display label. type: Field type (e.g. 'text', 'number', 'select', 'date'). description: Optional details. validation: Optional regex/constraint config dictionary. options: Optional choice list for select fields. is_active: True if field is enabled.
Inputs: name (required), type (required), label (required), options, +3 more.
Create a new workflow pipeline template in Colba. name: Human readable template name (e.g. 'Vendor Invoice Approval'). pipeline_config: Complete JSON workflow configuration complying strictly with docs://skills/workflow_json_creation specification. Must contain start_node_id and valid nodes list. Call get_pipeline_generation_rules tool first to inspect the required format. description: Optional human-readable description. Returns: Created pipeline template details including template_id.
Inputs: name (required), pipeline_config (required), description.
Create a new supplier/vendor profile. name: Name of the vendor. email: Primary email. account_number: Bank account number. bank_country_code: country code. financial_details: List of financial settings/details for invoicing.
Inputs: name (required), email, visible, settings, +6 more.
Create a new workgroup (DEPARTMENT, LOCATION, etc.) in the organization. name: Name of the workgroup. type: 'DEPARTMENT', 'LOCATION', or 'SQUAD'. parent_id: Optional parent workgroup UUID. key: Optional unique workgroup key.
Inputs: name (required), type (required), key, parent_id.
Delete a custom field from the system. field_id: UUID of the custom field to delete.
Inputs: field_id (required).
Delete a vendor from accounting records. vendor_id: UUID of the vendor.
Inputs: vendor_id (required).
Delete a workgroup from the organization structure. workgroup_id: UUID of the workgroup to delete.
Inputs: workgroup_id (required).
Retrieve the full configuration of a specific pipeline blueprint. blueprint_id: UUID of the blueprint. Returns: Complete blueprint details including its pipeline_config baseline.
Inputs: blueprint_id (required).
Get the official specification, validation rules, node type hierarchies, and schema guidelines for generating new Colba workflow pipeline JSON configurations. Returns: Complete Markdown specification text to guide pipeline JSON creation.
Inputs: no named parameters.
Fetch detailed status, current node states, and context variables of a specific process. process_id: UUID of the process. verbose: If True, returns full process structure including pipeline_config and display_all_data. If False (default), returns a compact representation with context variables but config omitted.
Inputs: process_id (required), verbose.
Fetch detailed request information, including audit history, context payload, and available_actions. Always call this before submit_decision to know which action values are valid for this request. request_id: UUID of the pending approval request.
Inputs: request_id (required).
Retrieve the Colba MCP Server Update Log and Changelog. Contains lists of new tools, changes, and alerts about required client restarts.
Inputs: no named parameters. Returns: result
Create a new pipeline template in the current organization based on a blueprint. blueprint_id: UUID of the blueprint to instantiate. Returns: Status of the instantiation and the created template_id (requires approval).
Inputs: blueprint_id (required).
List all available workflow pipeline blueprints that can be instantiated. category: Optional category filter (e.g. 'finance', 'hr', 'it'). query: Optional search query. Returns: A list of blueprints with their details and base configurations.
Inputs: query, category.
List all registered global custom fields in the organization. Returns: A list of custom fields with their ID, name, label, type, validation, and options.
Inputs: no named parameters.
List all active members (users/employees) in the organization. query: Optional search string to filter members by full name. Returns: A list of members with their IDs, names, emails, roles, and status.
Inputs: query.
List pending approval requests waiting for this member's decision. Includes the available_actions list for each request so you know valid statuses. limit: Max results to return (default: 50, max: 200). offset: Pagination offset (default: 0). NOTE: Pagination is server-side; the list may be incomplete if total > limit.
Inputs: limit, offset.
Get a list of available workflow templates/pipelines that can be started. Returns: List of pipeline templates with their required header schemas. Note: Always use the 'id' field (and not the legacy 'pipeline_id' field) to start a process or archive a pipeline.
Inputs: no named parameters.
List all processes visible to the member (filtered by backend per role). status: Filter by status: 'active', 'completed', 'rejected', 'failed'. pipeline_id: Filter by pipeline template UUID (use the 'id' field from list_pipelines). limit: Max results to return (default: 50, max: 200). offset: Pagination offset (default: 0). NOTE: Pagination is server-side; the list may be incomplete if total > limit.
Inputs: limit, offset, status, pipeline_id.
List all registered vendors/counterparties in the organization. Returns: A list of vendors with their IDs, names, and profiles.
Inputs: no named parameters.
List the organizational workgroups hierarchy (departments and locations). Returns: A tree structure of workgroups with their member details and counts.
Inputs: no named parameters.
Resolve (approve or reject) a pending MCP human-in-the-loop (HITL) transaction. action: MUST be 'approve' or 'reject'. approval_id: UUID of the pending approval (optional, exactly one of approval_id or token is required). token: Raw token string from the pending approval response (optional). session_key: Operator's active session key. If not provided, defaults to COLBA_TOKEN.
Inputs: action (required), token, approval_id, session_key.
Start a new workflow process under a template. template_id: UUID of the workflow template (MUST use the 'id' field from list_pipelines, NOT 'pipeline_id'). payload: Input data matching the template's header_schema. Returns: The started process ID and initial status.
Inputs: payload (required), template_id (required).
Submit a decision on a pending approval request. request_id: UUID of the pending approval request. status: MUST be one of the values from available_actions returned by get_request_details. Always call get_request_details first to obtain valid action IDs. comment: Optional explanation for the decision (recommended for audit trail).
Inputs: status (required), request_id (required), comment.
Sync members of the organization. data: List of members mapping to the onboarding structure.
Inputs: data (required).
Update an existing custom field / global field registration. field_id: UUID of the custom field to update. name: Optional system name. label: Optional display label. type: Optional field type. description: Optional description. validation: Optional validation schema. options: Optional dropdown options or dynamic source settings. is_active: Optional active status.
Inputs: field_id (required), name, type, label, +4 more.
Update an existing workflow pipeline template. template_id: UUID of the template to update. pipeline_config: Optional updated JSON workflow configuration. name: Optional updated name. description: Optional updated description.
Inputs: template_id (required), name, description, pipeline_config.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 28 tools
Most tools target distinct resource-action pairs (e.g., list_pipelines, list_blueprints, list_processes), but some overlap exists between approval tools (submit_decision vs resolve_mcp_approval) and template creation (create_pipeline vs instantiate_blueprint). The descriptions are detailed enough to differentiate them with careful reading.
All tools follow a consistent verb_noun pattern in snake_case (e.g., list_pipelines, create_workgroup, submit_decision). Minor deviations like resolve_mcp_approval and get_update_log are still predictable and stylistically consistent.
With 28 tools, the server is on the heavier side, but the broad enterprise workflow domain (pipelines, processes, approvals, org structure, custom fields, vendors) justifies the count. The scope is not single-purpose, so the number feels appropriate though slightly over the typical comfort zone.
The server covers core lifecycle operations for pipelines, custom fields, and processes, with adequate approval and org tools. Minor gaps exist (e.g., no vendor update, no workgroup update, no process cancellation), but these do not create dead ends for common workflows.
Run business workflows and route requests for human approval from AI agents.
Connect, monitor, and control AI agents — tasks, approvals, schedules, and governance.
Connect AI agents to Process Street workflows, tasks, runs, data sets, and operational records.
Integrate Connext AI into agentic workflows, enabling Connext product-aware assistance.
