MCP Server

Breeze exposes a built-in Model Context Protocol (MCP) server that lets external AI clients – Claude Desktop, Cursor, and any other MCP-compatible application – interact directly with your fleet. Instead of copying data between dashboards and chat windows, you can ask an AI assistant to query devices, triage alerts, run scripts, and manage patches, all within the client you already use.

The MCP server reuses the same tools, guardrails, and audit infrastructure as the built-in Breeze AI assistant, so every operation is scoped to your organization and governed by the same tiered permission model.

---

How MCP works

The Model Context Protocol is an open standard that defines how AI applications discover and invoke tools and resources hosted by external servers. A single MCP connection gives the AI client a live catalogue of everything it can do inside Breeze – no custom plugin code required.

Breeze implements the 2024-11-05 protocol version with three capabilities:

Capability	Description
Tools	100+ callable operations across device management, monitoring, alerting, compliance, backups, configuration policies, ticketing, billing, analytics, and more
Resources	Read-only data endpoints (breeze://devices, breeze://alerts, etc.)
Prompts	Five guided MSP workflows the AI client can launch as ready-made starting points (see Guided prompts)

On connection the server also returns an instructions string describing the Partner → Organization → Site → Device Group → Device hierarchy and a read-before-write approach, so the AI client orients itself to your tenant before it acts.

---

Transport

The Breeze MCP server uses the SSE + HTTP POST transport, which is the standard remote MCP transport for server-deployed instances.

Endpoint	Method	Purpose
/api/v1/mcp/sse	GET	Opens a long-lived Server-Sent Events stream. The server sends an endpoint event containing the URL the client should POST messages to, then streams responses and keepalive pings.
/api/v1/mcp/message	POST	Receives JSON-RPC 2.0 requests from the client. If a sessionId query parameter is present and matches an active SSE session, the response is delivered over SSE (HTTP 202). Otherwise the response is returned inline.

The SSE stream sends keepalive pings every 30 seconds to prevent proxy timeouts. The client can also call /api/v1/mcp/message without an SSE session for stateless, request-response usage.

---

Finding your MCP URL

Your tenant’s MCP SSE endpoint is surfaced in two places in the dashboard so you can copy it without having to construct it by hand:

• Login page — a compact “Connecting an AI agent?” card sits below the sign-in form, so you can grab the URL before you authenticate.
• Settings → Connected Apps — a full card above the apps list with a one-click copy button, ready to paste into Claude.ai, ChatGPT, Cursor, or any other MCP-compatible client.

Both cards resolve the URL from the tenant you’re connecting to, so what’s shown is what the AI client should use.

---

Authentication

All MCP endpoints require an API key with ai:* scopes. Authentication is performed via the X-API-Key header.

Creating an API key

1. Navigate to Settings > API Keys in the Breeze dashboard.

2. Click Create API Key.

3. Enter a descriptive name (e.g., “Claude Desktop MCP”).

4. Select the scopes you need (see Scope-based access control below).

5. Copy the generated key (it starts with brz_). You will not be able to see it again.

Caution

Store your API key securely. It grants programmatic access to your organization’s fleet data and, depending on scopes, the ability to execute commands on devices. Never commit API keys to version control.

Key format

API keys follow the format brz_<random>. The server stores only a SHA-256 hash of the key; the plaintext is never persisted.

OAuth 2.1

For AI clients that implement OAuth 2.1 with Dynamic Client Registration (DCR) and PKCE — including Claude.ai and ChatGPT — Breeze can authorize MCP connections through a real OAuth handshake instead of pasted API keys. The user pastes the tenant’s /mcp/sse URL into the client, signs in to Breeze, grants the AI client a scoped session, and the assistant receives a refreshable access token bound to that user and organization. No API key is created or copied.

OAuth is enabled with the MCP_OAUTH_ENABLED=true server setting. Once enabled, Breeze acts as a standards-compliant authorization server and advertises the following endpoints (all discoverable automatically by the client — there is nothing to configure by hand):

Endpoint	Purpose
/.well-known/oauth-authorization-server	Authorization server metadata (RFC 8414) — issuer, endpoints, supported scopes and grant types
/.well-known/oauth-protected-resource	Protected-resource metadata (RFC 9728) — tells the client which authorization server protects the MCP endpoint
/.well-known/jwks.json	Public signing keys for validating access tokens
/oauth/auth	Authorization endpoint — user sign-in and consent (PKCE S256 required)
/oauth/token	Token endpoint — authorization_code and refresh_token grants
/oauth/reg	Dynamic Client Registration (RFC 7591) — clients self-register
/oauth/token/revocation	Token revocation (RFC 7009)
/oauth/token/introspection	Token introspection (RFC 7662)

OAuth sessions use the mcp:read, mcp:write, and mcp:execute scopes (plus openid and offline_access), which map to the same Tier 1 / 2 / 3 model as the ai:* API-key scopes. Access tokens are short-lived (30 minutes) and signed with EdDSA; refresh tokens last 14 days and rotate on every use. Revoking a grant invalidates all of its sibling access and refresh tokens immediately.

When OAuth is enabled, the MCP endpoints accept an Authorization: Bearer <access_token> header and return a WWW-Authenticate challenge pointing OAuth-capable clients at the protected-resource metadata.

Note

OAuth is opt-in. It is off by default, and the /oauth/* and /.well-known/oauth-* routes only mount when MCP_OAUTH_ENABLED=true. In production, enabling it also requires OAUTH_JWKS_PRIVATE_JWK (token-signing key) and OAUTH_COOKIE_SECRET (session cookie secret) — the API refuses to boot without them. See Environment variables.

API key authentication via the X-API-Key header continues to work for every client, and remains the only option for self-hosted MCP clients (Claude Desktop, Cursor) that don’t implement OAuth.

---

Connecting Claude Desktop

1. Open Claude Desktop and go to Settings > Developer > Edit Config (or directly edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS).

2. Add the Breeze MCP server to the mcpServers section:

3. Restart Claude Desktop. You should see the Breeze tools appear in the tool picker.

macOS / Linux

{
  "mcpServers": {
    "breeze": {
      "url": "https://your-breeze-instance.example.com/api/v1/mcp/sse",
      "headers": {
        "X-API-Key": "brz_your_api_key_here"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "breeze": {
      "url": "https://your-breeze-instance.example.com/api/v1/mcp/sse",
      "headers": {
        "X-API-Key": "brz_your_api_key_here"
      }
    }
  }
}

The config file on Windows is located at %APPDATA%\Claude\claude_desktop_config.json.

Note

Replace your-breeze-instance.example.com with your actual Breeze API hostname and brz_your_api_key_here with the API key you created.

---

Connecting Cursor

1. Open Cursor and go to Settings > MCP.

2. Click + Add new global MCP server.

3. Enter the following configuration:

4. Save and reload the window. Breeze tools will appear in Cursor’s agent mode.

{
  "mcpServers": {
    "breeze": {
      "url": "https://your-breeze-instance.example.com/api/v1/mcp/sse",
      "headers": {
        "X-API-Key": "brz_your_api_key_here"
      }
    }
  }
}

---

Available tools

Tools are the primary way AI clients interact with Breeze. Each tool maps to one or more fleet operations and is classified into a tier that determines how it executes. The MCP server filters the tool list based on the scopes attached to your API key – you only see tools you are authorized to use.

Device tools

Tool	Tier	Description
query_devices	1	Search and filter devices by status, OS, site, tags, or hostname. Returns summary list with totals.
get_device_details	1	Comprehensive device detail including hardware specs, network interfaces, disks, and recent metrics.
analyze_metrics	1	Query CPU, RAM, disk, and network time-series data with aggregation (raw, hourly, daily). Up to 168 hours back.
get_active_users	1	Active user sessions per device or fleet-wide, with reboot safety signals based on idle thresholds.
get_user_experience_metrics	1	Login performance and session behavior trends per device or user over time.
get_device_context	1	Retrieve AI memory about a device – known issues, quirks, follow-ups, and preferences from past interactions.
set_device_context	2	Record new context/memory about a device for future conversations.
resolve_device_context	2	Mark a context entry as resolved. Hidden from active context but preserved in history.

Alert tools

Tool	Tier	Description
manage_alerts	1/2	List, get, acknowledge, or resolve alerts. List/get are Tier 1; acknowledge/resolve are Tier 2.
manage_alert_rules	1/2/3	Full alert rule lifecycle: list, get, create, update, delete rules; test rules; list notification channels; alert summary. Create/update are Tier 2; delete is Tier 3.

Command and script execution

Tool	Tier	Description
execute_command	3	Execute system commands (list processes, manage services, file operations, event log queries) on a device.
run_script	3	Execute a script by ID on up to 10 devices.
manage_services	3	List, start, stop, or restart system services on a device. List is Tier 2; start/stop/restart are Tier 3.

File and disk tools

Tool	Tier	Description
file_operations	1/3	List and read files (Tier 1). Write, delete, mkdir, rename (Tier 3).
analyze_disk_usage	1	Filesystem analysis with cleanup candidate detection. Can trigger fresh scans on online devices.
disk_cleanup	1/3	Preview cleanup candidates (Tier 1). Execute cleanup by deleting selected paths (Tier 3).

Security tools

Tool	Tier	Description
security_scan	3	Run security scans, check status, quarantine/remove/restore threats.
get_security_posture	1	Fleet-wide or device-level security posture scores with factor breakdowns and recommendations.

Fleet orchestration tools

Tool	Tier	Description
manage_policies	1/2/3	Compliance policy lifecycle: list, get, compliance status/summary, evaluate, create, update, activate/deactivate, delete, remediate.
manage_deployments	1/2/3	Staged software deployments: list, get, device status, create, start, pause, resume, cancel.
manage_patches	1/2/3	Patch management: list, compliance, scan, approve/decline/defer, bulk approve, install, rollback.
manage_groups	1/2/3	Device group lifecycle: list, get, preview dynamic filters, membership log, create, update, delete, add/remove devices.
manage_maintenance_windows	1/2/3	Maintenance windows: list, get, check active, create, update, delete.
manage_automations	1/2/3	Automation lifecycle: list, get, history, create, update, delete, enable, disable, manual run.
generate_report	1/2	Reports: list, generate, get report data, create/update/delete definitions, view history.

Network tools

Tool	Tier	Description
network_discovery	3	Initiate a network discovery scan from a device (ping, ARP, or full).

Diagnostic tools

Tool	Tier	Description
search_agent_logs	1	Search agent diagnostic logs with filters for device, level, component, time range, and message text.
set_agent_log_level	2	Temporarily increase agent log shipping verbosity for debugging. Auto-reverts after a set duration.
query_audit_log	1	Search the audit log for recent actions, filterable by action, resource, actor type, and time range.

Configuration policy tools

Tool	Tier	Description
list_configuration_policies	1	List configuration policies with linked feature types.
get_effective_configuration	1	Resolve the effective configuration for a device through the full hierarchy (device > group > site > org > partner).
preview_configuration_change	1	Preview how adding or removing policy assignments would change effective configuration.
apply_configuration_policy	2	Assign a configuration policy to a target in the hierarchy.
remove_configuration_policy_assignment	2	Remove a configuration policy assignment.

Ticketing tools

Tool	Tier	Description
manage_tickets	1/2/3	Full ticket lifecycle. List/get are Tier 1. Create, comment, assign, update status, update fields (subject, description, category, priority, due date, tags, device, submitter), link/unlink alerts, create a ticket from an alert, and edit/delete comments are Tier 2. Time tracking (log time entry, start/stop timer) and moving a ticket to a different organization are Tier 3.

Billing tools

Tool	Tier	Description
list_invoices	2	List invoices across the organizations you can access, newest first, with optional organization and status filters.
get_invoice	2	Full accounting view of one invoice — header plus all line items.
manage_invoices	2/3	Invoice lifecycle. Draft create/update/delete, line management (manual, catalog, bundle, and contract lines), assembling a draft from an organization’s billable period or from a ticket’s billable time and parts, and creating a Stripe payment link are Tier 2. Financial finalization — issue, void, record payment, void payment — is Tier 3.
search_catalog	2	Search the partner product catalog (hardware, software, services, bundles) by name or type.
get_catalog_item	2	Full detail for one catalog item, including bundle components.
lookup_distributor_product	2	Live TD SYNNEX (EC Express) price & availability lookup for a single distributor SKU or manufacturer part number that isn’t in your catalog yet — returns reseller cost, MSRP, currency, total stock, and per-warehouse availability. Partner-scoped: organization-scoped callers get availability but reseller cost is redacted, and a caller with no partner in context receives an error with no outbound call made.
manage_catalog	2	Catalog maintenance: create, update, and archive items; set or remove per-organization price overrides; manage bundle components. All actions are Tier 2.
list_contracts	2	List recurring contracts across accessible organizations, newest first, with optional filters.
get_contract	2	Full contract view — header, lines, and billing-period history.
manage_contracts	2/3	Contract lifecycle. Draft create/update/delete and line management are Tier 2. Lifecycle state changes — activate, pause, resume, cancel — are Tier 3.
manage_quotes	2/3	Quote/proposal lifecycle. Draft, content-block, and line management, declining a quote, and creating a payment link are Tier 2. Sending a quote to the customer is Tier 3.

Note

The billing read tools (list_invoices, get_invoice, search_catalog, get_catalog_item, list_contracts, get_contract) are deliberately classified Tier 2 even though they are read-only — financial data requires the ai:write scope, not just ai:read. In earlier releases these six tools appeared in the catalogue but every call failed; they work as of v0.89.0. lookup_distributor_product is Tier 2 for a different reason — it is read-only, but each call makes a billed outbound request to the TD SYNNEX distributor API, so it is gated on ai:write rather than plain ai:read. All ticketing and billing tools additionally require the matching role permission on the API key’s creator (for example, issuing an invoice requires the invoices send grant, and contract lifecycle changes require the contracts manage grant).

Note

Tier classification is action-level, not tool-level. For example, manage_alerts is Tier 1 for list/get, but Tier 2 for acknowledge/resolve. The MCP server resolves the effective tier at runtime for each specific action.

---

Available resources

Resources provide read-only access to fleet data via the resources/read JSON-RPC method. The AI client can read these to get context before invoking tools.

URI	Name	Description	Limit
breeze://devices	Device Inventory	All managed devices with hostname, status, OS, agent version, and last seen time.	500
breeze://alerts	Active Alerts	Currently active alerts with title, severity, status, and device ID.	200
breeze://scripts	Script Library	Available scripts with name, description, language, and category.	200
breeze://automations	Automation Rules	Configured automation rules with name, description, enabled state, and trigger.	200
breeze://devices/{id}	Device Detail	Full detail for a specific device by UUID.	1

All resource reads are org-scoped – the API key’s organization determines which records are visible.

---

Guided prompts

Beyond individual tools, the server advertises five guided prompts – ready-made workflows for the tasks MSPs run most often. An AI client lists them with prompts/list and expands one with prompts/get; the prompt returns a structured starting message (with any argument you supply filled in) that steers the assistant through the right sequence of tools. They’re a fast on-ramp: rather than describing a whole procedure, you pick the workflow and let it drive.

Prompt	What it does	Arguments
breeze-fleet-triage	A read-only health sweep of the fleet – surfaces what needs attention right now.	scope (optional org or site)
breeze-device-investigate	Deep-dives a single device and summarizes the likely root cause (read-only).	device (name, hostname, or ID)
breeze-patch-remediate	Safely patches a target – scan, confirm, then apply. Touches higher-risk execute tools, so it stays approval-gated.	target (device, site, or org)
breeze-incident-kickoff	Opens and structures an incident with a timeline, evidence collection, and a report.	summary (required), scope (optional)
breeze-turnkey-setup	An opinionated baseline-configuration wizard – partner-wide by default so a policy applies across every organization.	scope (optional; defaults to partner-wide)

Prompts don’t bypass permissions or approvals: every tool a prompt drives is still subject to your API key’s scopes, the step-up approval flow, and the production allowlist.

---

Scope-based access control

The tools visible and callable through MCP are determined by the scopes on your API key. Breeze uses a four-scope model for AI operations:

Scope	Access level	Tools exposed
ai:read	Read-only fleet data	All Tier 1 tools (query devices, analyze metrics, list alerts, etc.) and all resources. Required for SSE connection.
ai:write	Low-risk mutations	All Tier 1 + Tier 2 tools (acknowledge alerts, set device context, apply configuration policies, etc.)
ai:execute	Destructive operations	All Tier 1 + 2 + 3 tools (execute commands, run scripts, security scans, etc.)
ai:execute_admin	Production-hardened execute	Same as ai:execute, but required when the MCP_REQUIRE_EXECUTE_ADMIN flag is enabled in production.

A wildcard scope (*) grants access to all tools.

How scope filtering works

When a client calls tools/list, the server filters the full tool catalogue:

1. Tier 1 tools (read-only) are always included if the key has ai:read.
2. Tier 2 tools are included if the key has ai:write (or ai:execute, which implies write).
3. Tier 3+ tools are included if the key has ai:execute.
4. In production with MCP_REQUIRE_EXECUTE_ADMIN=true, Tier 3+ tools additionally require ai:execute_admin.

When a client calls tools/call, the server re-checks scopes before execution. Attempting to call a tool your key lacks permission for returns a JSON-RPC error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Tool \"execute_command\" requires ai:execute scope"
  }
}

RBAC permission checks

In addition to API key scopes, every tool call passes through the Breeze RBAC system. The user who created the API key must have the appropriate role-based permissions for the resource and action. For example, calling run_script requires the scripts.execute permission on the creator’s role.

---

Rate limiting

Rate limiting is enforced at multiple levels to protect your fleet and the Breeze API.

Transport-level limits

These apply in production (NODE_ENV=production) and are backed by Redis sliding-window counters:

Endpoint	Default limit	Window	Env override
GET /api/v1/mcp/sse	30 connections	60 seconds	MCP_SSE_RATE_LIMIT_PER_MINUTE
POST /api/v1/mcp/message	120 requests	60 seconds	MCP_MESSAGE_RATE_LIMIT_PER_MINUTE

When a rate limit is exceeded, the server returns HTTP 429 with a Retry-After header.

Per-tool rate limits

Each tool has its own sliding-window rate limit, enforced per user:

Tool	Limit	Window
execute_command	10	5 min
run_script	5	5 min
security_scan	3	10 min
network_discovery	2	10 min
file_operations	20	5 min
manage_services	10	5 min
analyze_disk_usage	10	5 min
disk_cleanup	3	10 min
manage_policies	20	5 min
manage_deployments	10	10 min
manage_patches	15	5 min
manage_groups	20	5 min
manage_maintenance_windows	15	5 min
manage_automations	10	10 min
manage_alert_rules	15	5 min
generate_report	10	5 min
set_device_context	20	5 min
resolve_device_context	20	5 min

Tools without an entry in this table (e.g., query_devices, get_device_details) have no per-tool rate limit.

---

Session management

The MCP server supports concurrent SSE sessions with the following constraints:

Parameter	Default	Env override
Max total SSE sessions (server-wide)	100	–
Max SSE sessions per API key	5	MCP_MAX_SSE_SESSIONS_PER_KEY
Session TTL	30 minutes	–

Stale sessions are cleaned up automatically when they exceed the 30-minute TTL. Each SSE session is owned by the API key that created it; the server verifies ownership before delivering responses to prevent cross-key session hijacking.

When the session limit is reached, the server returns HTTP 503 (“Too many active MCP sessions”) for server-wide limits, or HTTP 429 (“Too many active MCP sessions for this API key”) for per-key limits.

---

Security considerations

Organization isolation

API keys are always scoped to a single organization. The MCP server constructs an AuthContext from the API key that enforces org-level data isolation on every query and mutation. There is no way to access data from another organization through MCP, even with a wildcard scope.

Guardrails

Every tools/call request passes through the guardrail system before execution:

1. Scope check – verifies the API key has the required scope for the tool’s effective tier.
2. Guardrail check – evaluates action-level tier escalation (e.g., file_operations with action: "delete" escalates from Tier 1 to Tier 3).
3. RBAC permission check – verifies the API key creator has the required role-based permission.
4. Per-tool rate limit – enforces the sliding-window rate limit for the specific tool.
5. Production allowlist – for Tier 3+ tools in production, the tool must appear in the MCP_EXECUTE_TOOL_ALLOWLIST environment variable.

If any check fails, the request is rejected with an appropriate error before the tool handler executes.

Step-up approval (out-of-band)

Beyond scope and RBAC checks, a sensitive tool call can require an explicit out-of-band approval before it executes. When step-up is required, Breeze creates an approval request, pushes it to the user’s trusted mobile device, and blocks the action until the user decides on their phone:

• Approved — the tool call proceeds.
• Denied or expired — the tool call fails with the recorded reason.
• Reported — the user flagged the request as unrecognised; the requesting OAuth client’s access is revoked immediately.

This makes the mobile app a second factor for high-risk automation: even a valid API key cannot complete a step-up-gated action without a live approval from a trusted device. See Approval Mode for the full request lifecycle, risk tiers, and trusted-device management.

Production allowlist for destructive tools

In production, Tier 3+ (destructive) tools are blocked by default unless explicitly listed in the MCP_EXECUTE_TOOL_ALLOWLIST environment variable. This is a comma-separated list of tool names:

# Allow specific tools
MCP_EXECUTE_TOOL_ALLOWLIST=execute_command,run_script,manage_services

# Allow all (not recommended)
MCP_EXECUTE_TOOL_ALLOWLIST=*

If the environment variable is unset or empty, all Tier 3+ tools are blocked in production.

Audit logging

Every JSON-RPC request is recorded in the Breeze audit log with:

• The API key ID as the actor
• The JSON-RPC method (e.g., mcp.tools.call)
• Whether a session was active
• Success or failure result
• Error message (if any)

You can query MCP audit events using the query_audit_log tool or the Audit Log page in the dashboard.

Input validation

All tool inputs are validated against Zod schemas before execution. Invalid inputs are rejected with a descriptive error before reaching the tool handler.

---

Environment variables

MCP server

Variable	Default	Description
MCP_EXECUTE_TOOL_ALLOWLIST	(empty)	Comma-separated list of Tier 3+ tool names allowed in production. Set to * to allow all.
MCP_REQUIRE_EXECUTE_ADMIN	true	In production, Tier 3+ tools require the ai:execute_admin scope. Set to false to fall back to ai:execute. (No effect outside production.)
MCP_MAX_SSE_SESSIONS_PER_KEY	5	Maximum concurrent SSE sessions per API key.
MCP_SSE_RATE_LIMIT_PER_MINUTE	30	Maximum SSE connections per API key per minute.
MCP_MESSAGE_RATE_LIMIT_PER_MINUTE	120	Maximum JSON-RPC messages per API key per minute.
MCP_MESSAGE_MAX_BODY_BYTES	65536	Maximum accepted JSON-RPC request body size, in bytes (64 KB). Larger requests are rejected.
MCP_SESSION_TTL_SECONDS	660	Idle lifetime, in seconds, of a minted streamable-HTTP session principal in Redis (11 minutes).

OAuth 2.1

These apply only when OAuth is enabled. When MCP_OAUTH_ENABLED=true in production, OAUTH_JWKS_PRIVATE_JWK and OAUTH_COOKIE_SECRET are required — the API refuses to boot without them.

Variable	Default	Description
MCP_OAUTH_ENABLED	false	Master switch for OAuth 2.1. When true, the /oauth/* and /.well-known/oauth-* routes mount and MCP endpoints accept Authorization: Bearer tokens.
OAUTH_ISSUER	(empty)	Public issuer base URL (e.g. https://api.example.com). Used to build every advertised OAuth endpoint URL.
OAUTH_RESOURCE_URL	(empty)	Protected-resource identifier advertised in /.well-known/oauth-protected-resource (RFC 9728).
OAUTH_JWKS_PRIVATE_JWK	(empty)	EdDSA private signing key (JWK JSON) for access tokens. Required in production when OAuth is enabled.
OAUTH_JWKS_PUBLIC_JWK	(empty)	Matching public key, advertised at /.well-known/jwks.json. Derived from the private key if unset.
OAUTH_COOKIE_SECRET	(empty)	Secret used to sign sign-in / consent session cookies. Required in production when OAuth is enabled.
OAUTH_DCR_ENABLED	false	Allow Dynamic Client Registration at POST /oauth/reg. Off by default. When true in production you must also set one of the two posture flags below, or the API refuses to boot.
OAUTH_DCR_REQUIRE_IAT	false	Gate DCR behind an initial access token issued out-of-band. Closes the public-spam vector, but is incompatible with public MCP clients (Claude.ai / ChatGPT) — they register anonymously and cannot supply an IAT. Use OAUTH_DCR_ALLOW_ANONYMOUS instead for a public server.
OAUTH_DCR_ALLOW_ANONYMOUS	false	Deliberately permit anonymous DCR. This is the required posture for connecting Claude.ai / ChatGPT (see above). Spam risk is bounded by the controls on /oauth/reg: per-IP rate limit, forced public clients, mandatory PKCE S256, software_id rejection, and a daily stale-client GC.
OAUTH_CONSENT_URL_BASE	(empty)	Optional origin for the consent UI redirect (e.g. http://localhost:4321 for split API/web dev). Defaults to a relative path, which works when the API and web app share an origin behind a reverse proxy.

---

API reference

The MCP server implements the following JSON-RPC 2.0 methods:

initialize

Returns server capabilities and metadata.

// Request
{ "jsonrpc": "2.0", "id": 1, "method": "initialize" }

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": { "listChanged": false },
      "resources": { "subscribe": false, "listChanged": false },
      "prompts": { "listChanged": false }
    },
    "serverInfo": {
      "name": "breeze-rmm",
      "version": "1.0.0"
    },
    "instructions": "You are connected to Breeze RMM — a multi-tenant RMM platform for MSPs. ..."
  }
}

prompts/list

Returns the catalogue of guided workflow prompts (see Guided prompts).

// Request
{ "jsonrpc": "2.0", "id": 6, "method": "prompts/list" }

prompts/get

Returns a prompt’s rendered messages, ready to seed a conversation. Pass the prompt name and any arguments.

// Request
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "prompts/get",
  "params": {
    "name": "breeze-device-investigate",
    "arguments": { "device": "ACME-LT-014" }
  }
}

tools/list

Returns the filtered list of available tools based on API key scopes.

// Request
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

// Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "query_devices",
        "description": "Search and filter devices in the organization...",
        "inputSchema": { "type": "object", "properties": { "..." } }
      }
    ]
  }
}

tools/call

Invokes a tool with the given arguments.

// Request
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "query_devices",
    "arguments": { "status": "offline", "limit": 10 }
  }
}

// Response (success)
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{\"devices\":[...],\"total\":42,\"showing\":10}" }]
  }
}

// Response (error)
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{\"error\":\"Device not found or access denied\"}" }],
    "isError": true
  }
}

resources/list

Returns the catalogue of available resources.

// Request
{ "jsonrpc": "2.0", "id": 4, "method": "resources/list" }

resources/read

Reads a specific resource by URI.

// Request
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "resources/read",
  "params": { "uri": "breeze://devices" }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "contents": [{
      "uri": "breeze://devices",
      "mimeType": "application/json",
      "text": "[{\"id\":\"...\",\"hostname\":\"...\",\"status\":\"online\",...}]"
    }]
  }
}

---

Troubleshooting

“Missing X-API-Key header” (401)

The request does not include an X-API-Key header. Ensure your MCP client configuration includes the header. In Claude Desktop and Cursor, this goes in the headers block of the server config.

“Invalid API key format” (401)

The key does not start with brz_. Verify you copied the full key from the API Keys page.

“Rate limit exceeded” (429)

You have exceeded the per-minute transport rate limit. The response includes a Retry-After header with the number of seconds to wait. If this happens frequently, increase the limit via MCP_SSE_RATE_LIMIT_PER_MINUTE or MCP_MESSAGE_RATE_LIMIT_PER_MINUTE.

“Too many active MCP sessions” (503 or 429)

Either the server-wide limit (100 sessions) or the per-key limit (default 5) has been reached. Close unused MCP clients, or increase the per-key limit via MCP_MAX_SSE_SESSIONS_PER_KEY.

“Service temporarily unavailable” (503)

Redis is not available. The MCP server requires Redis for rate limiting in production. Check that your Redis instance is running and the REDIS_URL environment variable is set.

Tool returns “requires ai:execute scope”

The API key does not have the ai:execute scope. Regenerate the key with the required scope, or use a key that already has it.

Tool returns “not in MCP_EXECUTE_TOOL_ALLOWLIST”

In production, Tier 3+ tools must be explicitly allowlisted. Add the tool name to the MCP_EXECUTE_TOOL_ALLOWLIST environment variable.

Tools not appearing in Claude Desktop

1. Verify the SSE endpoint URL is correct and reachable from your machine.
2. Check that the API key has at least the ai:read scope.
3. Restart Claude Desktop after editing the config file.
4. Open the Claude Desktop developer console to check for connection errors.

“Unknown tool” errors

The tool name in tools/call does not match any registered tool. Use tools/list to see the current catalogue. Tool names are case-sensitive.

Stale SSE session

SSE sessions expire after 30 minutes. If you see errors about missing sessions, the client should reconnect to /api/v1/mcp/sse to obtain a new session.