> ## Documentation Index > Fetch the complete documentation index at: https://docs.haloagents.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP Overview > Connect your AI tools to HaloAgents via the Model Context Protocol, and bring your own MCP servers in as agent actions. ## What MCP is The [Model Context Protocol](https://modelcontextprotocol.io) 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. | 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: ``` https://app.haloagents.ai/api/mcp ``` 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::` 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](/mcp/connecting-clients) for the install path on each major client, and [Scopes & Permissions](/mcp/scopes-and-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: | 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 | See [External MCP Servers](/mcp/external-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: | Flag | Default | Controls | | ---------------------- | ------- | -------------------------------------------------------------------------------- | | `mcp_server` | On | Whether `/api/mcp` accepts JSON-RPC calls for the org | | `mcp_external_servers` | On | Whether the org can connect external MCP servers (Connectors) under Integrations | 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 Install Halo as an MCP server in Claude Desktop, Cursor, VS Code, or any custom client. The full scope grammar, the gating model, and per-customer session binding. Bring your own MCP server in as a set of agent actions. JSON-RPC methods, OAuth metadata URLs, and rate limits for custom client builders.