Connecting AI Agents via MCP

The Helmdesk MCP (Model Context Protocol) server lets AI assistants like Claude Desktop, Cursor, Windsurf, and Claude Code interact with your helpdesk using natural language. Your AI agent can triage tickets, draft replies, search your knowledge base, and send emails — no code required.

What is MCP?

MCP is an open protocol that lets AI assistants connect to external tools and data sources. Instead of copying and pasting information between your helpdesk and your AI assistant, MCP gives the AI direct access to your support queue.

Prerequisites

Node.js 18 or later installed on your machine

A Helmdesk API key with the MCP / AI assistant scope preset

An MCP-compatible AI client (Claude Desktop, Cursor, VS Code, or Claude Code)

Step 1: Create a Scoped API Key

Go to your project's API Keys page in the Helmdesk dashboard

Click Create API Key

Select the MCP / AI assistant preset — this grants tickets:read, tickets:write, articles:read, and ai:use

Optionally add an IP allowlist to restrict where the key can be used from

Copy the key — you will not be able to see it again

Step 2: Configure Your AI 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"
      }
    }
  }
}

On macOS, the config file is at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, it is at %APPDATA%\Claude\claude_desktop_config.json.

Cursor / VS Code

Add the same block to your .cursor/mcp.json or VS Code MCP settings file.

Claude Code (CLI)

claude mcp add helmdesk -- npx -y @helmdesk/mcp
export HELMDESK_API_KEY="sk_live_your_key_here"

Step 3: Start Using It

Once connected, just talk to your AI assistant in natural language. Here are some things you can say:

"Show me all open tickets sorted by oldest first"

"Draft a reply to ticket #42 using info from our knowledge base"

"Classify all new tickets by priority — anything mentioning outage should be urgent"

"Summarize my support queue for a standup"

The AI assistant automatically discovers the available tools and calls them based on your request.

Available Tools

The MCP server provides 9 tools:

list_tickets — list and filter tickets by status, priority, or search query

get_ticket — read a ticket with its full message thread

create_ticket — create a new ticket on behalf of a customer

update_ticket — change a ticket's status, priority, or category

reply_to_ticket — send a staff reply (emailed to the customer)

send_email — send a transactional email using a template

preview_email — preview a rendered email without sending

get_template_schema — get the variable schema for an email template

search_articles — search the knowledge base

Troubleshooting

"API key lacks the required scope" — Your key does not have permission for the operation. Edit the key in your dashboard and add the missing scope.

"IP address is not allowed" — The request came from an IP not in the key's allowlist. Add the IP or remove the allowlist.

MCP server not connecting — Make sure Node.js 18+ is installed and npx is in your PATH. Test manually with HELMDESK_API_KEY=sk_live_... npx @helmdesk/mcp.