Cursor

Cursor reads MCP servers from an mcp.json file, either in your home directory for every project or in the repository for one. Both work; the split is useful, because the key belongs in the first and the project slug belongs in the second.

Where the file lives

Scope	Path	Put this here
Every project	~/.cursor/mcp.json	Your API key.
One project	.cursor/mcp.json	The project slug, so this repo works on the right app. Committable.

Global config

~/.cursor/mcp.json

{
  "mcpServers": {
    "helmdesk": {
      "command": "npx",
      "args": ["-y", "@helmdesk/mcp"],
      "env": {
        "HELMDESK_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

That is the whole setup if your key reaches exactly one project. On a multi-project account, keep reading — otherwise the agent will ask which app you mean on every single call, which is safe but tedious.

Per-project config

Cursor supports interpolation, so a committed project file can reference the key from your environment instead of containing it:

.cursor/mcp.json

{
  "mcpServers": {
    "helmdesk": {
      "command": "npx",
      "args": ["-y", "@helmdesk/mcp"],
      "env": {
        "HELMDESK_API_KEY": "${env:HELMDESK_API_KEY}",
        "HELMDESK_PROJECT": "ledgerly"
      }
    }
  }
}

The slug is safe to commit, the key is not

HELMDESK_PROJECT is just a name and belongs in the repository — it is what makes a cloned repo come with an agent already pointed at the right app. HELMDESK_API_KEY is a bearer credential. If one ends up committed, revoke it in Admin Settings → API keys and mint another; there is no rotation-in-place.

Working in sandbox first

Add HELMDESK_ENVIRONMENT set to sandbox while you get a feel for what the agent does. Mail renders and is logged but never delivered, and tickets notify nobody:

"env": {
  "HELMDESK_API_KEY": "${env:HELMDESK_API_KEY}",
  "HELMDESK_PROJECT": "ledgerly",
  "HELMDESK_ENVIRONMENT": "sandbox"
}

Remove the line when you are ready for live. You can still send a single call to sandbox afterwards by asking for it in words — nearly every project-scoped tool takes an environment argument.

Check it connected

Open Settings → MCP. Helmdesk should be listed as connected with 73 tools. If it is not, the usual causes are a JSON syntax error in mcp.json, a missing HELMDESK_API_KEY (the server exits immediately without one), or npx not resolving in the environment Cursor launched from.

Toggling the server off and on in that panel reloads the config, which is quicker than restarting the editor after an edit.

Try it

What is in the Helmdesk queue for this project?

I just fixed the CSV export bug. Find any open ticket about it,
reply to each one telling them it shipped, and resolve them.
Show me the replies first.

The second prompt is the one that makes the editor the right place for this. You have the commit in front of you, so the reply can say what actually changed. Note that resolving also emails each customer a satisfaction survey — see Safety & approvals, and the prompt cookbook for more.