> ## 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.

# Use Halo in Claude

> Connect Claude to your Halo workspace to answer customers, research accounts, review support quality, build outreach and run onboarding from a conversation.

Halo works as a connector for Claude: add it by URL today, or from the Connectors directory once Halo is published there. Once connected, Claude can read and answer your support conversations, look up any contact or company and replay their history, review negative feedback and unresolved questions, draft and launch outreach, and work your customer-success pipelines. Every action that changes a record, sends a message or launches an outreach is announced before it runs, and outreach activation requires the previewed recipient count.

## Before you connect

* A Halo workspace. [Start one](https://app.haloagents.ai/signup) if you do not have one.
* To grant write access (replying to customers, changing records, launching outreach), you need the matching permissions in Halo yourself, for example **inbox: reply** to reply to tickets or **automation: send** to activate a campaign. The consent screen only offers what you hold, and every write re-checks it.

## Connect from the Connectors directory

Once Halo is published in the directory:

1. In Claude, open **Customize > Connectors** and search for **Halo**.
2. Choose **Connect**. Claude opens the Halo consent screen in a new window.
3. Sign in to Halo if asked, then choose the **permissions** Claude should have. Read permissions are pre-selected; write permissions start unchecked.
4. Choose **Authorize**. Claude returns to the conversation with Halo connected.

Tokens refresh automatically and expire after an hour. To revoke access, remove the connector in Claude; the refresh token is discarded with it. A Halo admin can also remove the operator who connected it from the workspace, which invalidates every token they granted.

## Connect as a custom connector

If your organization installs connectors by URL, use:

```
https://app.haloagents.ai/api/mcp
```

In Claude: **Customize > Connectors > Add custom connector**, paste the URL, and follow the same consent flow. No client ID or secret is needed: Halo supports Dynamic Client Registration and Client ID Metadata Documents, so Claude registers itself.

## Connect from Claude Code

```bash theme={null}
claude mcp add --transport http halo https://app.haloagents.ai/api/mcp
```

Run `/mcp` inside Claude Code to complete sign-in and check the connection status. Claude Code is where the support loop closes: pull the tickets customers opened about a bug, fix it in the codebase, and reply to each conversation from the fix.

## What you can ask

> "Show me the open tickets about invoices and draft a reply to each."

> "Who at Acme has written in this quarter, and what did we tell them?"

> "What went badly in support this week, and what should we fix first?"

> "Write a renewal reminder series for accounts renewing next month and send me a test."

> "Which onboardings are stuck? Log a note on each and create a follow-up task."

> "Get the install snippet and add the Halo widget to our Next.js layout."

## What the connector can do

| Area | Tools |
| - | - |
| Inbox | Search and read tickets and transcripts; reply over chat or email; add internal notes; set status, assign, snooze, move; create tickets; message a customer |
| Contacts and companies | Find and search contacts, leads and companies; replay a contact's journey; create and update records |
| Workspace data | Semantic search across your knowledge base, help center, synced CRM data and past conversations; KPIs and time series; HubSpot and Stripe lookups; negative feedback, unresolved questions, low-sentiment conversations; web search and fetch |
| Outreach | Create broadcasts, series, in-app messages and banners; senders and merge fields; steps in markdown; audiences from saved segments; readiness check, test send, audience preview, activation and pause |
| Customer success | Onboarding pipelines and deals, stage moves, notes; issues and comments; tasks |
| Workflows | List, read, create, activate, pause and resume workflows; enroll and cancel records |
| Setup and docs | Widget install snippet, identity JWT sample, Halo documentation search |
| Connected integrations | Actions your workspace has enabled in HubSpot, Slack, Stripe and OrbitForms |

Every tool is annotated so Claude knows which ones only read (it runs them immediately) and which ones change state or send messages (it asks first). Read the full list under [Scopes & Permissions](https://docs.haloagents.ai/mcp/scopes-and-permissions.md).

## Permissions

The consent screen lists every permission Claude asks for, grouped into **Read** and **Write**. Write permissions are never implied by read ones, and the connector can never do more than the person who connected it: each write re-checks that you hold the matching permission in Halo. Integration secrets never leave Halo; Claude only ever sees tool results. See [Scopes & Permissions](https://docs.haloagents.ai/mcp/scopes-and-permissions.md) for the scope list and token lifetimes.

## Troubleshooting

* **A write tool says a permission is missing**: disconnect and reconnect the connector, then tick the write permission on the consent screen. Write permissions start unchecked, and only operators who hold the matching Halo permission can grant them.
* **Claude says the connector does not require sign-in**: you pasted a different URL. The connector URL is `https://app.haloagents.ai/api/mcp`; the `/chatgpt` surface is for the ChatGPT plugin.
* **No tools appear**: your workspace's plan does not include that feature, or the MCP server was disabled for your workspace. Ask your Halo admin.
* Still stuck? Email [support@haloagents.ai](mailto:support@haloagents.ai).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.