How the MCP server works

What Halo's MCP server is, its endpoint, tools and scopes, how it runs, its limits, and when to use it rather than the REST API.

The Halo MCP server lets an AI tool read an organization's datasets, charts, reports, websites and directory as the person who connected it. It speaks the Model Context Protocol, so any MCP client can use it. Every tool is read-only.

https://mcp.usehalo.net/mcp

This section is for people building on it. The MCP server for members and admins covers turning it on and connecting a tool as a person.

How it runs

• Streamable HTTP, stateless. Each POST to /mcp carries one JSON-RPC message and is authenticated on its own. There are no sessions, and nothing about one request carries into another. Answers are JSON, not event streams.

• No GET or DELETE. With a valid token they answer 405, which MCP clients expect from a server that doesn't stream. Without one they get the usual 401, since the token is checked first.

• One message per request. Batches get 400, so one request can't carry many calls past the limits.

• Scoped listing. tools/list shows only the tools a connection's scopes allow, and each call checks the scope again.

• The person, live. Every request loads the person's account, membership and role again, so a change applies on the next call. Tools run through the same services as Halo Data, with the person's access levels and row policies.

The MCP protocol has the details, with cURL.

Tools and scopes

A connection carries some of three scopes, which only narrow what the person's role allows. A token has the same three names as an API key, but they aren't interchangeable.

Each tool is marked readOnlyHint and idempotentHint. The full input schemas are at dev.usehalo.net/reference/mcp.

query_dataset takes a query much like the REST body, with the dataset's id inside it:

{
  "query": {
    "datasetId": "0195f3a2-…",
    "dimensions": [{ "field": "region" }],
    "measures": [{ "field": "revenue" }],
    "limit": 50
  }
}

Its schema also lists specVersion, which Halo fills in if you leave it out.

What comes back

A tool's answer is text for a model to read, wrapped in a <halo-data> fence that says the content is data, not instructions. See the fence. Treat what's inside as untrusted: Build an agent shows how.

Limits

Paging (offset, keyset and cursor) is refused unless the organization allows individual rows, so paging can't walk past the row cap. Rows of Marketplace data are refused too, though their fields can be read. These tools run on your own AI provider and don't use Halo's AI credits.

Before it works

It's off until an Admin turns it on. Then, for every request, all of these must hold:

• Halo AI is on for the organization, and its plan includes it.

• The person's role has ai.use.

• An Admin has turned on Let members connect their own AI tools.

• Halo hasn't paused the organization or its tools, and its Admins haven't paused the member.

• The member is active, and meets the organization's sign-in and two-factor rules.

What a tool reads goes to that tool and its AI provider, outside Halo. The admin guide has the steps.

The Halo MCP server or REST

Use the Halo MCP server when a model decides what to ask. Use REST when your code does, or when you need many rows. Both read as a person and both are read-only, so neither widens what that person can see.