MCP Server

The Helmdesk MCP server lets AI assistants (Claude Desktop, Cursor, Windsurf, or any MCP-compatible client) interact with your helpdesk using natural language. Your agent can triage tickets, draft replies, search articles, and send emails — no code required.

Setup

1. Create a scoped API key

Go to your project's API Keys page in the dashboard and create a key with the MCP / AI assistant preset. This grants tickets:read, tickets:write, articles:read, and ai:use — enough for support triage without email or admin access.

2. Add to your MCP client

Claude Desktop

Add this to your claude_desktop_config.json:

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

Cursor / VS Code

Add to your .cursor/mcp.json or VS Code MCP settings:

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

Claude Code (CLI)

claude mcp add helmdesk -- npx -y @helmdesk/mcp
# Then set the env var:
export HELMDESK_API_KEY="sk_live_your_key_here"

Codex CLI

Add the server to your ~/.codex/config.toml (note: Codex uses TOML, and the key is mcp_servers with an underscore):

[mcp_servers.helmdesk]
command = "npx"
args = ["-y", "@helmdesk/mcp"]
env = { HELMDESK_API_KEY = "sk_live_your_key_here" }

Or add it from the terminal:

codex mcp add helmdesk --env HELMDESK_API_KEY=sk_live_your_key_here -- npx -y @helmdesk/mcp

3. Start asking

Once connected, just ask your AI assistant to work with your helpdesk. It will call the right tools automatically.

Example prompts

These are real things you can say. The MCP server translates each into the right API calls.

Triage open tickets

"Show me all open tickets sorted by oldest first. For any waiting more than 24 hours, draft a reply and set them to pending."

list_ticketsget_ticketreply_to_ticketupdate_ticket

Answer with knowledge base

"A customer is asking about file upload limits. Find the relevant KB article and reply with a link."

get_ticketsearch_articlesreply_to_ticket

Classify and prioritize

"Go through all new tickets. Anything mentioning 'down', 'broken', or 'outage' should be urgent. Everything else medium."

list_ticketsupdate_ticket

Send an email

"Send a welcome email to jane@acme.com using the welcome template with her name."

get_template_schemasend_email

Daily summary

"Summarize my support queue: how many open tickets, what's the oldest, any urgent ones?"

list_tickets

Bulk resolution

"Find all tickets tagged 'known-issue' that are still open, reply with the fix from our KB, and resolve them."

list_ticketsget_ticketsearch_articlesreply_to_ticketupdate_ticket

Tool reference

The MCP server exposes these tools. Your AI assistant discovers them automatically — you don't need to call them directly.

list_tickets

List support tickets with optional filters.

statusstring?— new, open, pending, resolved, closed

prioritystring?— low, medium, high, urgent

searchstring?— Search by subject or email

pagenumber?— Page number (default: 1)

limitnumber?— Results per page (max: 100)

get_ticket

Get a ticket with its full message thread, tags, and customer info.

ticketIdstring— The ticket UUID

create_ticket

Create a new ticket on behalf of a customer.

subjectstring— Ticket subject

bodystring— Initial message body

customerEmailstring— Customer email

customerNamestring?— Customer name

prioritystring?— low, medium, high, urgent

categorystring?— bug, feature_request, billing, howto, other

update_ticket

Update a ticket's status, priority, category, or assignee.

ticketIdstring— The ticket UUID

statusstring?— New status

prioritystring?— New priority

categorystring?— New category

assignedTostring?— User UUID to assign, or null to unassign

reply_to_ticket

Send a staff reply to a ticket. The reply is emailed to the customer.

ticketIdstring— The ticket UUID

bodystring— Reply message

send_email

Send a transactional email using a template.

templateKeystring— Template key (e.g. "welcome")

toobject— { email, name? }

variablesobject?— Template variables

preview_email

Preview a rendered email without sending it.

templateKeystring— Template key

variablesobject?— Template variables

get_template_schema

Get the variable schema for a template, so you know what variables to pass.

templateKeystring— Template key

search_articles

Search the knowledge base for articles matching a query.

querystring?— Search query

categorystring?— Filter by category

Resources

MCP resources provide read-only data snapshots that AI assistants can access directly without calling a tool.

helmdesk://tickets/open

All open tickets — gives the AI instant context about your queue.

helmdesk://tickets/pending

Tickets waiting on a customer reply — useful for follow-up workflows.

helmdesk://articles

Published knowledge base articles — the AI uses these to find answers before drafting replies.

API key scopes

For MCP use, we recommend creating a scoped API key that only grants the permissions your AI assistant needs. The MCP / AI assistant preset in the dashboard is a good starting point.

Scope	Grants	MCP preset
`tickets:read`	List and view tickets	Included
`tickets:write`	Create, update, and reply to tickets	Included
`articles:read`	Search knowledge base	Included
`articles:write`	Create/edit articles	—
`emails:send`	Send transactional emails	—
`emails:manage`	Manage email templates	—
`ai:use`	AI features (suggest, classify)	Included
`webhooks:manage`	Manage webhook endpoints	—

You can also restrict keys by IP address. See the IP Allowlist section when creating a key.

Troubleshooting

"API key lacks the required scope"

The key you're using doesn't have permission for the operation your AI tried. Go to the API Keys page in your dashboard, click the settings icon on the key, and add the missing scope.

"IP address is not allowed"

The request came from an IP not in the key's allowlist. Either add the IP to the key, or remove the allowlist to allow all IPs.

MCP server not connecting

Make sure you have Node.js 18+ installed and npx available in your PATH. You can test the server manually:

HELMDESK_API_KEY=sk_live_... npx @helmdesk/mcp

If the server starts, the issue is in your MCP client config. Check that the JSON is valid and the env var is set correctly.