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.| Side | What you get |
|---|---|
| Halo as MCP server | External AI clients sign in with OAuth, discover the tools your integrations expose, and run them on behalf of your org. |
| Halo as MCP client | Connect a third-party MCP server (your internal API, a vendor’s tools) and its tools become available to your AI agents alongside the built-in actions. |
action_executions audit log. Destructive tools (refunds, deletes, irreversible writes) are intentionally not exposed via MCP — the action registry’s destructive: true flag is enough to keep them out of tools/list and tools/call.
Halo as MCP server
HaloAgents exposes a single MCP endpoint for every workspace: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:
actions:*or fine-grainedactions:<integration>:<action>to call non-destructive integration toolsdocs:readto proxysearch_docsandread_docagainst the public Halo docssetup:readto 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 widgetdata:readto read workspace data: users, leads, companies, tickets, transcripts, negative feedback, 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, email-automation 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.
Halo as MCP client
You can also connect any third-party MCP server to your org. Once connected, Halo runstools/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:
| Use case | What you connect |
|---|---|
| Internal API exposed as tools | Your own MCP server (Express, FastAPI, Workers) |
| Vendor-provided MCP server | Anything from the public MCP server registry |
| Domain-specific knowledge base | A small MCP server in front of an internal Postgres |
Feature flags
Each side has a per-org feature flag that we keep wired up as a kill-switch even after the feature ships:| Flag | Default | Controls |
|---|---|---|
mcp_server | On | Whether /api/mcp accepts JSON-RPC calls for the org |
mcp_external_servers | Off | Whether the org can connect external MCP servers under Integrations |
mcp_server to false on the team. External MCP servers are still gated; ask your admin to flip mcp_external_servers if you don’t see the connect surface in your dashboard.
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.