Skip to main content
Glama
detailobsessed

Unblu MCP Server

by detailobsessed
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

unblu-mcp

ci documentation pypi version python versions license FastMCP

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

Related MCP server: Dialpad Universal MCP Server

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:

  • kubectl installed 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.yaml or 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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers