unblu-mcp

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

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

Metadata

Release files for unblu-mcp 0.10.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for unblu-mcp 0.10.1
File	Size	Uploaded
unblu_mcp-0.10.1.tar.gz	34.6 kB	Mar 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for unblu-mcp 0.10.1
File	Interpreter	ABI	Platform	Reset
unblu_mcp-0.10.1-py3-none-any.whl 36.8 kB Mar 5, 2026	Python 3	none	any	Details

Total release size: 71.4 kB

Release files / unblu_mcp-0.10.1.tar.gz

Download URL	unblu_mcp-0.10.1.tar.gz
Size	34.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`7fd5543039d96978c07c24ced77a831a4562b9affc862a58f880da48c841f996`
BLAKE2b-256 checksum How to use checksums	`872e24776f214299b6e714c550892d4d9e0d90562edb1117a368ca77fd511515`
Upload date	Mar 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.10.8 {"installer":{"name":"uv","version":"0.10.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / unblu_mcp-0.10.1-py3-none-any.whl

Download URL	unblu_mcp-0.10.1-py3-none-any.whl
Size	36.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`48423f9695502567922aa2ec3752c00949bd921c3e92acfc961e1156a1a7256b`
BLAKE2b-256 checksum How to use checksums	`8714f64b8b3e61330cd3b6d39168e1db75e8e71eb13da1e935f792b3de135255`
Upload date	Mar 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.10.8 {"installer":{"name":"uv","version":"0.10.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`