unblu-mcp

A Model Context Protocol (MCP) server for interacting with Unblu deployments. This server provides AI assistants with token-efficient access to 300+ Unblu API endpoints through progressive disclosure.

Features

This server implements best practices from Anthropic's guide on building effective agents:

• Progressive Disclosure — 5 discovery tools instead of 300+ API definitions upfront, dramatically reducing token usage
• Clear Tool Interfaces — Descriptive parameters with examples, helpful error messages that suggest alternatives
• Full API Coverage — Access to all Unblu REST API v4 endpoints
• Smart Discovery — Search and browse operations by service category or keyword
• Field Filtering — Request only the fields you need to reduce response size
• Response Truncation — Limit response sizes to prevent token overflow

Built with FastMCP 2.14+, leveraging cutting-edge features:

• MCP Annotations — Tools include readOnlyHint, destructiveHint, and openWorldHint metadata for smarter AI decision-making
• Response Caching — Discovery tools cache results via FastMCP middleware for faster repeated queries
• Policy-Based Authorization — Optional Eunomia integration for controlling which API operations are allowed
• Built-in Logging — Automatic file-based logging with daily rotation for debugging and usage analysis
• MCP 2025-11-25 Spec — Full support for the latest Model Context Protocol specification

Quick Start

# Install
uv tool install unblu-mcp

# Run with K8s provider
unblu-mcp --provider k8s --environment dev

# Or with environment variables
UNBLU_BASE_URL=https://your-instance.unblu.cloud/app/rest/v4 \
UNBLU_API_KEY=your-key \
unblu-mcp

See Getting Started for detailed installation and configuration instructions.

Available Tools

Tool	Description
list_services()	List all API service categories
list_operations(service)	List operations in a specific service
search_operations(query)	Search for operations by keyword
get_operation_schema(operation_id)	Get full schema for an operation
call_api(operation_id, ...)	Execute any API operation

See Available Tools for detailed usage examples.

Security

Security First

This server includes built-in safety controls. The call_api tool is marked with destructiveHint: true to trigger client confirmations, and optional Eunomia integration provides server-side policy enforcement to block destructive operations.

See Safety & Authorization for details on configuring access controls.

Feedback