Give each agent a key for one project, with only the permissions it needs.
HAL's MCP server lets AI agents such as Claude, Cursor or your own bot work in HAL. A project MCP key limits an agent to one project and to the tools you allow.
Create a key
- Go to Settings → API → Project MCP keys. Only account owners and admins can create keys.
- Pick the project, give the key a name (for example the bot's name) and tick the permissions it needs.
- Copy the key. It's shown once; HAL stores only a hash of it.
The list shows each key's permissions, when it was created and when it was last used. Revoke a key there at any time; it stops working on the next request.
Permissions you can grant
| Permission | What the agent can do |
|---|---|
| Conversations: read | List and read conversations, messages, images, macros and message tags |
| Conversations: reply | Reply, show typing, tag messages, and change a conversation's status, assignee or snooze |
| Articles: read | Read help articles and groups, and find articles that match a question |
| Articles: write | Create and edit help articles and groups |
| Contacts: read | Read contacts, companies, CRM stages and deals |
| Contacts: write | Create and edit contacts, companies and deals |
Write permissions don't include read, so grant both when the agent needs both.
Never available to a project key
Admin and settings, billing, team members, webhooks, broadcasts and email campaigns, email templates and sender domains, workflows and automations, imports, and every other project. A call to another project, or to a tool the key doesn't allow, gets a clear error.
Account key
The older account MCP key still works and has full access to every project in the account. Use project keys for bots and integrations, and keep the account key for yourself.
Setup details for developers: MCP documentation.