@quick-desk/mcp

Let an AI agent work your QuickDesk support desk — read tickets, triage them, leave internal notes, manage tasks.

Get a key

In QuickDesk, go to Settings → Developers and create a key. Pick the role the agent should have: the key can do exactly what that role allows and nothing more, so start narrow. You'll see the key once.

Connect it

There is nothing to install. Every client below runs the server with npx, which fetches this package on demand.

Settings → Developers in QuickDesk shows these same snippets with your key already filled in, which is the quickest route if you have the portal open.

Claude Code

claude mcp add quickdesk --env QUICKDESK_API_KEY=qd_live_... -- npx -y @quick-desk/mcp

Check it with claude mcp list.

Codex

codex mcp add quickdesk --env QUICKDESK_API_KEY=qd_live_... -- npx -y @quick-desk/mcp

That writes to ~/.codex/config.toml. To edit it by hand instead:

[mcp_servers.quickdesk]
command = "npx"
args = ["-y", "@quick-desk/mcp"]

[mcp_servers.quickdesk.env]
QUICKDESK_API_KEY = "qd_live_..."

VS Code

code --add-mcp '{"name":"quickdesk","command":"npx","args":["-y","@quick-desk/mcp"],"env":{"QUICKDESK_API_KEY":"qd_live_..."}}'

Then open Copilot chat in agent mode.

Claude Desktop, Cursor, Windsurf, Zed, Gemini CLI

These take the same block. Only the file it goes in changes: Claude Desktop uses claude_desktop_config.json (Settings → Developer → Edit config), Cursor uses ~/.cursor/mcp.json or a per-project .cursor/mcp.json, and Gemini CLI uses ~/.gemini/settings.json.

{
  "mcpServers": {
    "quickdesk": {
      "command": "npx",
      "args": ["-y", "@quick-desk/mcp"],
      "env": { "QUICKDESK_API_KEY": "qd_live_..." }
    }
  }
}

Then ask your agent something like "What QuickDesk tickets are waiting on us, and which look urgent?"

Replying to customers is off by default

The server will not expose quickdesk_reply_to_ticket unless you start it with QUICKDESK_MCP_ALLOW_SEND=1. A public reply emails your customer and cannot be undone, so it is opt-in rather than something an agent can reach for by accident. Everything else — reading, triaging, assigning, internal notes — works without it.

When the tool is withheld it is absent from the tool list entirely, so an agent plans around it instead of trying and failing.

"env": {
  "QUICKDESK_API_KEY": "qd_live_...",
  "QUICKDESK_MCP_ALLOW_SEND": "1"
}

Tools

Tickets — search_tickets, get_ticket, get_ticket_timeline, update_ticket, claim_ticket, add_internal_note, link_tickets, get_ticket_links, merge_tickets, get_ticket_ai_context, and reply_to_ticket (gated).

Workspace — whoami, search_customers, update_customer, list_team, list_saved_replies, list_conversations, get_ticket_sla.

Tasks — list_tasks, get_task, create_task, update_task, delete_task, list_task_lists, link_task_to_ticket.

All names are prefixed quickdesk_. List results come back compact and paginated — follow nextCursor until it is null.

Settings

| Variable | Default | What it does | |---|---|---| | QUICKDESK_API_KEY | — | Required. Your key from Settings → Developers. | | QUICKDESK_API_BASE | https://api.quickdesk.co.uk | Point at a self-hosted or local API. | | QUICKDESK_MCP_ALLOW_SEND | unset | Set to 1 to allow replying to customers. |

When something is refused

Errors say what to do rather than restating a status code:

• Invalid key → the key is wrong or revoked; make a new one.
• Not allowed → the key's role lacks that capability. Call quickdesk_whoami to see what it holds, then widen the role or make a key on a different one.
• Billing limit → a plan or add-on issue, not permissions. Widening the role will not help. Note the API answers a plan gate with the same 403 it uses for a role gate, so the two are told apart by the error code, not the status.
• Rate limited → keys allow 120 requests a minute.
• No answer → requests give up after 30 seconds rather than hanging the agent, and say so. A broad search is the usual cause; narrow it and retry.

Licence

MIT