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.
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):
For --provider k8s, you need all of the following:
kubectlinstalled and available to the MCP client process- a valid Kubernetes login with access to the target namespace
- a K8s environment map in
~/.unblu-mcp/k8s_environments.yamlor passed with--k8s-config
Quick bootstrap:
mkdir -p ~/.unblu-mcp
uvx unblu-mcp --print-k8s-config-template > ~/.unblu-mcp/k8s_environments.yaml
The --environment value must match a key from that YAML file, such as dev, test1, or t1.
Minimal config file:
environments:
dev:
local_port: 8084
namespace: unblu-dev
service: haproxy
service_port: 8080
api_path: /app/rest/v4
Then point your MCP client at that environment:
{
"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"
}
}
}
}
The env block is optional if your MCP client already inherits a PATH that includes both uvx and kubectl. Keep it if the client cannot otherwise find those binaries.
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