Use Halo with coding agents

Point Cursor or Claude Code at these docs with llms.txt, connect the Halo MCP server so they can see your data, and keep keys out of prompts and repositories.

This page gives a coding agent these docs and your real field names, and keeps your keys out of what it reads.

Give it the docs

Three files are written for tools to read:

Tell your agent about them in the file it reads for each project.

## Halo

This project reads data from Halo's Developer API.

- Guides: https://dev.usehalo.net/llms.txt
- API: https://dev.usehalo.net/openapi.json
- Read the key from the HALO_API_KEY environment variable. Never write a key in code, a URL, browser code or a log.
- Make requests from the server, never the browser.

Add three rules, because agents often assume otherwise:

• A query's body has no specVersion or datasetId, and no pivot, groupRows or parameters.

• limit is at most 1,000. Page with keyset, cursor and offset.

• Column keys change with grains and aggregates, such as order_date__month. Read them from columns rather than assuming.

Give it your data's shape

Connect the MCP server so the agent can look up datasets and field names rather than guess them. Connecting is the same as for any client:

claude mcp add --transport http halo https://mcp.usehalo.net/mcp

Cursor and the others are in Connect a client. An Admin has to turn this on first.

For writing code, the agent mostly needs datasets.read: list_datasets and describe_dataset give it names and types without reading rows. Add data.query when you want it to check real numbers. It reads as you, and what it reads goes to its AI provider.

Keep the two credentials apart. An MCP token (hpat_… or hmat_…) is what the agent uses to look things up, and an API key (hak_…) is what the code it writes uses when it runs. Neither opens the other's routes.

Keep keys out of prompts and repositories

Treat a key like a password. Anything an agent reads may go to its AI provider, and may end up in a commit it writes.

• Don't paste a key into a chat. If you have, treat it as leaked: see If a key leaks.

• Use the environment. Set the key in your shell, or in a file your agent doesn't read. Have the agent write process.env.HALO_API_KEY, never the value.

• Stop the agent reading secrets. Keep them in a .env file that's ignored by git, and exclude it from the agent too: .cursorignore for Cursor, and permissions.deny for Claude Code.

• Reference tokens in shared config. .mcp.json can hold ${HALO_MCP_TOKEN}, and Cursor's mcp.json can hold ${env:HALO_MCP_TOKEN}, so the file you commit has no secret. See Connect a client.

• Scan before you push. Secrets are recognizable by their prefixes: hak_, hpat_, hmat_, hmrt_ and hes_. Add them to a pre-commit hook.

• Make a key only for development. Give it narrow scopes and a short expiry, so a slip costs little. Revoke it when you're done.

Try before you run

The playground's sample mode needs no key at all, so an agent's first draft of a request can be checked there. Real data can wait until the request looks right.