Agents & MCP

Helmdesk speaks the Model Context Protocol, so the agent you already code with can run your support desk. Not a chatbot bolted onto a helpdesk — 73 tools covering every part of the platform, in the editor where you are already working.

You do not learn an API. You say what you want:

Go through the tickets that came in overnight. Anything mentioning
"charged twice" is urgent — tag it billing and draft a reply from the
refund policy article. Show me the drafts before anything goes out.

Connect in three steps

1. Create a key

In the dashboard, go to Admin Settings → API keys → Create key. Choose All projects and the MCP / AI assistant preset, which grants tickets, articles, feedback, customers, email sending and template management, log read and write, and project reads.

Two scopes are deliberately outside that preset: webhooks:manage and api_keys:manage. Add them if you want an agent registering webhooks or minting keys for apps it scaffolds. If you would rather start smaller, a read-only key is a good first week — see Safety & approvals.

2. Add the server to your client

The server runs over stdio and needs no install — npx fetches it. Pick your client:

All of them come down to the same three environment variables:

3. Ask for something

A good first sentence, because it reads everything and changes nothing:

Give me today's picture: what needs a reply, and is anything on fire?

The prompt cookbook has the rest, grouped by what you are trying to get done.

Which project the agent works on

An all-projects key reaches everything, so the server has to decide which project a request acts on. In order: the project argument on the call, then HELMDESK_PROJECT, then the key itself if it reaches exactly one project.

If none of those settles it, the API refuses and returns the list of projects instead of guessing. That refusal is the feature. It is why an agent holding one key across eight apps cannot quietly email the wrong customer base, and it is why every response object carries projectId and projectSlug — so the agent can always tell you what it was looking at.

Put HELMDESK_PROJECT in the repo's .env and the question answers itself: whichever codebase you open, the agent works on that app.

Try it without touching a customer

Every project has a sandbox plane. Mail is rendered and logged but never delivered, tickets notify nobody, and webhooks only reach sandbox endpoints. Set HELMDESK_ENVIRONMENT=sandbox and the whole platform behaves normally with the outside world disconnected.

You can also stay live and send one call to sandbox — "render that in sandbox and show me" — because nearly every project-scoped tool takes an environment argument. The downgrade runs one way only: a sandbox key can never reach live data.

Where to go next

• Prompt cookbook — what to say, which tools it calls, what comes back.
• Scaffold an app with support — project, scoped key, templates, and widget from one prompt.
• Tool reference — all 73, with the scope each needs.
• Safety & approvals — what can reach a customer, and how to bound it.
• Automations — the agents Helmdesk runs on its own, and the queue they file into.

Troubleshooting

The server does not start

It needs Node 18 or newer, and it exits immediately without HELMDESK_API_KEY— check your client's MCP log for the usage message it prints on the way out. On a machine where npxis not on the client's PATH, use an absolute path to it.

"API key lacks the required scope"

A 403 naming the scope it wanted. Add it in Admin Settings → API keys; the tool reference lists what each one needs. Retrying will not help.

The agent asks which project every time

Your key reaches several projects and no default is set. Add HELMDESK_PROJECT to the MCP config or the repo's .env.

"IP address is not allowed"

The key has an IP allowlist that does not include the machine you are on. Clear it, or add the address.