The Halo MCP server
Let members connect Claude, Cursor and other AI tools to Halo as themselves, read-only, with OAuth or a personal token.
The Halo MCP server lets people use their own AI tools with your data. A connected tool reads your organization's datasets, charts, reports, websites and directory as the person who connected it, and can't change anything.
The server is at:
https://mcp.usehalo.net/mcpTurn it on
It's off until an Admin turns it on.
Go to Settings, Halo AI, and open the AI tools tab.
Turn on Let members connect their own AI tools. It saves at once.
Read the switch's description first: what a tool reads goes to that tool and its AI provider, outside Halo. Turning it off stops every tool at once. Tools stay listed for when it's back on.
For a tool to connect, all of these must hold, and Halo checks them on every request:
Use Halo AI is on for the organization, and your plan includes Halo AI.
The person's role has the Use Halo AI permission.
Let members connect their own AI tools is on.
Halo hasn't paused the organization, its Admins haven't paused the member, and Halo's own switch for AI tools is on.
The member is active and meets your organization's sign-in and two-factor rules.
Connect a tool
Apps that sign in
Claude, Cursor and other apps that support MCP sign-in use OAuth. There's no token to copy.
In the app, add Halo as a custom connector with the address above. You'll find it to copy in Account, under AI tools.
The app sends you to Halo. Sign in if you need to.
On Connect … to Halo, read the warning: the name is what the tool calls itself, and Halo hasn't verified it. The warning also says which host you're sent back to.
Pick one Organization, and what It may do.
Press Allow.
The connection lasts up to 90 days. Then you approve it again.
Tools that take a header
Claude Code and scripts use a personal token.
Go to Account, AI tools, and press New token.
Give it a Name, choose what It may do, and pick when it Expires after: 7 days, 30 days, 90 days or a year.
Press Make token, then copy it. Halo keeps only a hash, so you won't see it again.
Anyone with the token acts as you. Keep it out of chats, code and screenshots.
claude mcp add --transport http halo https://mcp.usehalo.net/mcp --header "Authorization: Bearer hpat_…"Tokens work in one organization: the one you made them in. Send the token in the Authorization header. Halo refuses it in the address.
What a tool can do
A connection has some of three permissions, which only narrow what the person's role allows.
| On the consent page | Tools |
|---|---|
| See datasets and their fields | list_datasets, describe_dataset |
| Run read-only queries | query_dataset, get_chart_data, list_goals, read_goal, list_insights |
| See charts, reports, websites and the directory | list_charts, read_chart, list_reports, read_report, list_websites, read_website, list_listings, read_listing, list_businesses, read_business |
Every connection also has whoami. A tool lists only what its permissions allow, and every tool is read-only.
What it can see
A tool sees what its person can, and no more. A role change applies on the next call.
Access. Workspaces, folders and grants apply. Anything else comes back as not found.
Rows. Row policies apply to every query, and so do your plan's row caps and query time limits.
Fields. A query that names a hidden field is refused, though a calculated field may still use one.
Row caps. 200 rows a query, or 1,000 a page if the organization has Let Halo AI read individual rows on. Paging is refused otherwise.
Drafts. Viewers get a report's published version. Drafts need edit access.
SQL. Custom SQL is never returned.
Source errors. Errors from your database appear only for people who can see connections. Everyone else gets a general message.
Results are wrapped and marked as data from your organization, not instructions. What a person's own tool then does with them is up to that tool. See What Halo AI can see.
Limits
| Limit | Amount |
|---|---|
| Data rows read a day | 20,000 per person in each organization, across their connections |
| Tool calls | 120 a minute per connection, 300 a minute per person |
| Calls running at once | 4 per connection |
| Requests | 240 a minute per connection, 600 a minute per address |
| Request size | 1 MB, one call at a time |
These tools don't use your AI credits, because they run on their own AI provider. Your organization's query limits still apply.
See and end connections
Your own. Account, AI tools lists your connections with when each was last used. Disconnect stops one at once.
Everyone's. In Settings, Halo AI, under AI tools, Owners and Admins see Connected AI tools, and can disconnect any of them, even with the switch off.
Activity. Under the same tab, Recent AI tool activity shows the latest 50 calls by anyone, with what each asked for and how it went. Halo keeps calls for 90 days, along with their arguments, which may include filter values.
The audit log records tokens made and revoked, connections approved, and every data read, by the person, marked as coming from an AI tool.
A connection also ends by itself when:
it reaches its expiry;
the person changes their password, resets their two-factor or starts setting it up, or their account is deleted;
they're suspended or removed from the organization;
a refresh token is used twice, which means it was copied.