unblu-mcp

<!- - mcp-name: io.github.detailobsessed/unblu - ->

A Model Context Protocol (MCP) server for debugging and operating Unblu deployments. Optimised for debugging workflows — curated typed tools for common operations, plus an escape hatch for the full 300+ endpoint API.

📚 Full Documentation

# Design

The server exposes three layers, each progressively more powerful:

| Layer | What it is | When to use |
|- -- -- --|- -- -- -- -- --|- -- -- -- -- -- --|
| Curated tools | Typed, token-efficient tools for common debugging tasks | 90% of debugging sessions |
| execute_operation | Generic escape hatch for any of 331 Unblu API operations | When a curated tool doesn't exist |
| Resources | Read-only api:// URIs for browsing the API surface | Discovery and schema inspection |

# Quick Start

# # Installation

uvx unblu-mcp

Or install persistently: uv tool install unblu-mcp

# # MCP Client Configuration

Direct API access with an API key:

{
  "mcpServers": {
    "unblu": {
      "command": "uvx",
      "args": ["unblu-mcp"],
      "env": {
        "UNBLU_BASE_URL": "https://your-instance.unblu.cloud/app/rest/v4",
        "UNBLU_API_KEY": "your-api-key"
      }
    }
  }
}

Kubernetes port-forward (auto-managed):

{
  "mcpServers": {
    "unblu": {
      "command": "uvx",
      "args": ["unblu-mcp", "- -provider", "k8s", "- -environment", "dev"],
      "env": {
        "PATH": "/Users/YOUR_USERNAME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

# Tools

# # Curated tools (read-only)

| Tool | Description |
|- -- -- -|- -- -- -- -- -- --|
| get_current_account | Current account info — good first call to verify connectivity |
| search_conversations(status?, topic?, assignee_id?, limit?, fields?) | Search conversations with filters |
| get_conversation(conversation_id) | Full conversation detail with participants |
| search_persons(query?, email?, limit?, fields?) | Find persons (visitors, agents) |
| get_person(person_id) | Full person detail |
| get_persons(identifiers, fields?) | Batch-resolve up to 20 persons in parallel |
| search_users(query?, email?, limit?, fields?) | Find registered users |
| get_user(user_id) | Full user detail |
| check_agent_availability(named_area_id?) | Check agent availability per named area |
| search_named_areas(query?, limit?) | List named areas (routing targets) |
| find_operation(query, service?, include_schema?, limit?) | Discover API operations by keyword |

# # Mutation tools

| Tool | Description |
|- -- -- -|- -- -- -- -- -- --|
| assign_conversation(conversation_id, agent_id) | Assign a conversation to an agent |
| end_conversation(conversation_id) | End an active conversation |

# # Escape hatch

| Tool | Description |
|- -- -- -|- -- -- -- -- -- --|
| execute_operation(operation_id, path_params?, query_params?, body?, fields?, confirm_destructive?) | Execute any of the 331 Unblu API operations |

# # Resources

| URI | Description |
|- -- --|- -- -- -- -- -- --|
| api://services | JSON list of all API service groups |
| api://operations/{operation_id} | Full resolved schema for a specific operation |

# # Prompts

| Prompt | Description |
|- -- -- -- -|- -- -- -- -- -- --|
| debug_conversation(conversation_id) | Step-by-step debugging workflow for a conversation |
| find_agent(criteria) | Locate an agent and check their availability |
| account_health_check | Validate account configuration and connectivity |

# Safety

By default, execute_operation blocks DELETE operations unless confirm_destructive=True is passed. For stricter control, install the optional Eunomia policy engine:

uv tool install "unblu-mcp[safety]"

Then point to a policy file:

{
  "mcpServers": {
    "unblu": {
      "command": "unblu-mcp",
      "args": ["- -policy", "config/mcp_policies.json"],
      "env": { "UNBLU_BASE_URL": "...", "UNBLU_API_KEY": "..." }
    }
  }
}

The bundled config/mcp_policies.json allows all read-only and curated tools while blocking destructive execute_operation calls by operation ID pattern.

# Development

git clone https://github.com/detailobsessed/unblu-mcp.git
cd unblu-mcp
uv sync - -all-extras - -dev
uv run poe test

# License

ISC License