MCP Integration and Usage Examples

The Model Context Protocol (MCP) lets AI agents like Claude, Cursor, and Windsurf interact directly with your Helmdesk project. Instead of switching between your AI tool and the Helmdesk dashboard, the agent can read tickets, send replies, search articles, and manage your helpdesk — all from natural language prompts.

What Is MCP?

MCP is an open protocol that connects AI assistants to external tools and data sources. When you connect Helmdesk as an MCP server, your AI agent gains access to your helpdesk data and can perform actions on your behalf.

Think of it as giving your AI assistant a set of tools: it can list tickets, read ticket details, post replies, search your knowledge base, send emails, and more — without you having to copy and paste data between applications.

Setting Up the MCP Server

Installation

Install the Helmdesk MCP package globally:

npm install -g @helmdesk/mcp

Or use npx to run it without installing:

npx @helmdesk/mcp

Configuration

The MCP server needs two environment variables:

HELMDESK_API_KEY — Your Helmdesk API key (create one in Settings > API Keys)

HELMDESK_PROJECT_ID — Your project's UUID (found in the project settings URL)

Connecting to Claude Desktop

Add this to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "helmdesk": {
      "command": "npx",
      "args": ["-y", "@helmdesk/mcp"],
      "env": {
        "HELMDESK_API_KEY": "hd_your_api_key_here",
        "HELMDESK_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

Connecting to Cursor

In Cursor, go to Settings > MCP Servers and add a new server with the same command and environment variables.

Connecting to Claude Code

Add the MCP server to your project's .claude/mcp.json:

{
  "mcpServers": {
    "helmdesk": {
      "command": "npx",
      "args": ["-y", "@helmdesk/mcp"],
      "env": {
        "HELMDESK_API_KEY": "hd_your_api_key_here",
        "HELMDESK_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

Available Tools

Once connected, the MCP server exposes these tools to your AI agent:

Ticket Tools

list_tickets — List tickets with optional status and priority filters

get_ticket — Get full details of a specific ticket including replies

create_ticket — Create a new ticket

reply_to_ticket — Post a reply to an existing ticket

update_ticket — Change ticket status, priority, or assignee

Article Tools

search_articles — Search knowledge base articles by keyword

list_articles — List all published articles

Email Tools

send_email — Send a transactional email using a template or inline content

Usage Examples

Here are practical prompts you can use with your AI agent once the MCP connection is active.

Triage the Queue

Prompt your AI agent:

> "Show me all open tickets sorted by priority. Summarize each one in a sentence."

The agent will call list_tickets with status "open", read through the results, and give you a prioritized summary of what needs attention.

Find and Suggest Solutions

> "A customer is asking about password resets. Search our knowledge base for relevant articles and draft a reply."

The agent will:

Call search_articles with "password reset"

Read the matching articles

Draft a reply that references the relevant documentation

Post the reply using reply_to_ticket (with your approval)

Daily Summary

> "Give me a daily summary: how many tickets came in today, how many were resolved, and what are the top issues?"

The agent calls list_tickets, filters by today's date, categorizes by status, and produces a report.

Auto-Classify Tickets

> "Look at the 10 most recent open tickets. For each one, suggest a priority level and category based on the content."

The agent reads each ticket, analyzes the content, and recommends classifications. You can then approve and apply them.

Draft a Knowledge Base Article

> "We keep getting questions about setting up SSO. Draft a knowledge base article covering SAML and OAuth setup."

The agent uses its knowledge of your product (from existing articles and ticket context) to draft a comprehensive article. You can review and publish it through the dashboard.

Send a Welcome Email

> "Send a welcome email to new-customer@example.com using our welcome template. Their name is Alex Chen."

The agent calls send_email with the template ID and variables you specified.

Bulk Ticket Resolution

> "Find all tickets tagged 'billing' that are older than 30 days and still open. Draft a follow-up message asking if the issue is resolved."

The agent filters tickets, drafts an appropriate message, and can post replies to each one after your approval.

Customer Sentiment Analysis

> "Read the last 20 closed tickets. What are customers most frustrated about? What are they happiest with?"

The agent reads ticket threads, analyzes the sentiment and topics, and produces an actionable summary.

API Key Scopes for MCP

When creating an API key for MCP use, choose the Support agent preset or select these scopes:

tickets:read — Required for listing and reading tickets

tickets:write — Required for creating tickets and posting replies

articles:read — Required for searching the knowledge base

ai:use — Required for AI-powered features (classify, suggest reply)

emails:send — Optional, only if you want the agent to send emails

Do not grant emails:manage or webhooks:manage unless the agent specifically needs to configure email settings or webhooks.

Best Practices

Start with read-only. Give the MCP key only tickets:read and articles:read at first. Add write scopes once you are comfortable with the agent's behavior.

Review before sending. Ask the agent to "draft" replies rather than "send" them. Review the content before approving it.

Use IP allowlists. If the MCP server runs on a known machine, restrict the API key to that IP address.

Rotate keys regularly. Create dedicated API keys for MCP use and rotate them periodically.

Name keys descriptively. Use names like "MCP — Claude Desktop" or "MCP — Cursor" so you can identify and revoke specific keys.

Troubleshooting

"Connection refused" or "Server not found"

Verify the MCP server is running (npx @helmdesk/mcp)

Check that the environment variables are set correctly

Ensure your API key has not been revoked

"Unauthorized" errors

Verify your API key is valid and has not expired

Check that the key has the required scopes for the operation

Confirm the project ID matches the key's project

Agent cannot find tickets or articles

Ensure tickets exist in the project associated with your API key

Check that articles are published (draft articles are not returned by the API)

Verify the API key has tickets:read or articles:read scopes