Colba Model Context Protocol (MCP) Server

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.

📦 Dependency Installation

The server is written in Python 3.12+ and uses the mcp library. We recommend using uv for fast, isolated execution.

Option 1: Using uv (Recommended)

Ensure uv is installed. No pre-installation step is required — uv will execute the server and automatically manage dependencies.

Option 2: Classical Installation via pip

From the directory containing pyproject.toml, run:

pip install -e .

Related MCP server: Automatisch MCP Server

⚙️ Environment Variables Configuration

The MCP server is configured via the following environment variables:

🖥️ Connecting to Clients

1. Claude Desktop

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

2. Cursor

1. Go to Settings > Features > MCP.

2. Click + Add New MCP Server.

3. Fill in the parameters:

   • Name: colba

   • Type: command

   • Command:

     uv --directory PATH_TO_PROJECT_ROOT run --quiet python -m colba_mcp

4. Add environment variables:

   • COLBA_API_URL = http://localhost:9000

   • COLBA_TOKEN = tk_live_your_token_here

🛠️ Available Tools

The MCP server exposes the following tools to AI agents:

1. list_pipelines

Retrieve available workflow templates and required input header schemas.

• Example prompt: "What workflow pipelines can I start?"

2. start_process

Start 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'"

3. list_processes

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

4. list_pending_requests

Fetch 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?"

5. get_process_details

Get 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?"

6. get_request_details

Retrieve complete approval request payload and valid available actions.

• Parameters:

  • request_id (string, UUID).

• Example prompt: "Show details for request xyz-456"

7. submit_decision

Submit 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'"

8. get_pipeline_generation_rules

Retrieve the official specification and validation rules for generating pipeline JSONs.

• Example prompt: "Get the rules for creating a pipeline JSON"

9. create_pipeline

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

10. list_custom_fields

Retrieve all registered global custom fields in the organization.

• Example prompt: "Show all custom fields configured in the system"

11. list_members

List 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'"

12. list_workgroups

List the organizational hierarchy (departments and locations).

• Example prompt: "Show the departments tree"

13. list_vendors

List all registered vendors/counterparties in the organization.

• Example prompt: "Show all vendors"

14. update_pipeline

Update 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'"

15. update_custom_field

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

16. get_update_log

Retrieve the update log and changelog of the Colba MCP server.

• Example prompt: "Show recent MCP server updates and changelog"

17. list_blueprints

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

18. get_blueprint

Retrieve the full configuration of a specific pipeline blueprint.

• Parameters:

  • blueprint_id (string, UUID): Blueprint identifier.

• Example prompt: "Get details for blueprint 'xyz'"

19. instantiate_blueprint

Create 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'"

📚 Resources

docs://skills/workflow_json_creation

The 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_log

The official update log and changelog of the Colba MCP server, reflecting all newly added tools, features, and notifications about client restarts.

💬 Prompts

generate_pipeline_json

System 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.