Skip to main content

​
What MCP is

The Model Context Protocol is an open standard for AI clients (Claude Desktop, Cursor, VS Code, custom agents) to discover and call tools on a remote server. Halo speaks MCP on both sides. Both sides reuse Halo’s existing security model: the action registry, agent-action toggles, per-org rate limits, and the action_executions audit log. Write and destructive capabilities live behind dedicated per-token scopes the operator grants at consent (shown grouped and labelled Read / Write, and never implied by the broad actions:*), and every write additionally re-checks that the operator who authorized the token holds the matching dashboard permission, so a connected client can never do more than the person who connected it.

​
Halo as MCP server

HaloAgents exposes a single MCP endpoint for every workspace:
Authentication is OAuth 2.1 with PKCE and Dynamic Client Registration (RFC 7591). MCP-aware clients walk the flow automatically the first time they hit the URL: they get a 401 with a WWW-Authenticate header pointing at the discovery metadata, register themselves, redirect the user to the Halo consent UI, and exchange the resulting code for an access + refresh token pair. What an external client can do is gated by scopes the user grants at consent time. Read scopes:
  • actions:* or fine-grained actions:<integration>:<action> to call non-destructive integration tools
  • docs:read to proxy search_docs and read_doc against the public Halo docs
  • setup:read to use the read-only setup helpers (setup_get_install_snippet, setup_get_jwt_sample) so the connected client can walk a customer through installing the widget
  • data:read to read workspace data: users, leads, companies, tickets, transcripts, negative feedback, saved segments and subscription lists, plus the full Ask-AI-parity retrieval and analytics surface (semantic knowledge search powered by Voyage embed + match_knowledge + Voyage rerank, recency cuts over synced integration data, KPI snapshots, bucketed time-series, HubSpot deals + engagements, Stripe billing, outreach email analytics, web search and fetch). Lets a connected client answer questions like “who is this customer”, “what did we tell Acme about onboarding last quarter”, and “how has churn changed in the last 30 days” without opening the dashboard.
  • sales:read / cs:read to read the Sales Suite and CS Suite: pipelines, deals, the Customers (accounts) list, and issues. Only available when the org has the corresponding suite enabled.
  • workflows:read to list workflows, read a workflow’s step graph, and view enrollment history.
Write scopes (labelled Write on the consent page, never implied by actions:*):
  • inbox:write to answer and manage customer conversations: reply to tickets over chat and email, add internal notes, change status / assignee / snooze, create tickets, and proactively message a customer on a new thread. Replies and outreach can be sent under a named alias identity (e.g. “Bella”) via alias_user_id
  • automations:write to create, edit, and launch outreach campaigns across every type: email broadcasts, series (drip sequences), in-app messages, and banners. Includes a readiness preflight, an audience-count preview, teammate test sends, and a recipient-count confirmation handshake so a campaign can never launch against an unconfirmed audience
  • data:write to update contact and company records (lifecycle, lead status, custom fields). No deletes
  • sales:write / cs:write to manage the suites: create and edit deals, move stages, log notes, and (CS) create / update / comment on issues
  • workflows:write to create workflows and control their lifecycle — activate, pause, resume, enroll and cancel records. Activating or enrolling can trigger the workflow’s actions, including sending email
  • actions:destructive to unlock destructive-flagged integration actions (Stripe refunds / credits / cancellations, posting to Slack)
Every write is double-gated: the token must carry the scope, and the operator who authorized the token must hold the matching dashboard permission (for example inbox:reply for inbox tools, automation:send to activate a campaign). Every call, allowed or refused, lands in the action_executions audit log. See Connecting Clients for the install path on each major client, and Scopes & Permissions for the full scope grammar.

​
Halo as MCP client

You can also connect any third-party MCP server to your org. Once connected, Halo runs tools/list against it, snapshots the discovered tools, and surfaces them in AI Agents > [Agent] > Actions under a synthetic “MCP server” integration. Enable the tool on an agent and the AI will call it during conversations. Common patterns: See External MCP Servers for the connect flow and what gating applies to discovered tools.

​
Feature flags

Each side has a per-org feature flag that we keep wired up as a kill-switch even after the feature ships: Both sides are GA, so every org gets them by default. To disable either for a specific workspace, ask your Halo admin to set the flag to false on the team.

​
Where to go next

Connecting Clients

Install Halo as an MCP server in Claude Desktop, Cursor, VS Code, or any custom client.

Scopes & Permissions

The full scope grammar, the gating model, and per-customer session binding.

External MCP Servers

Bring your own MCP server in as a set of agent actions.

Protocol Reference

JSON-RPC methods, OAuth metadata URLs, and rate limits for custom client builders.