MCP Server

Give AI assistants native access to your help desk using the Model Context Protocol.

Go Help Desk includes a built-in Model Context Protocol (MCP) server mounted at /mcp/. MCP allows AI assistants — Claude, Cursor, VS Code with Continue, and others — to call help desk operations as structured tools, rather than trying to interact with the web UI.

With the MCP server connected, an AI assistant can:

• List open tickets and summarize them
• Look up the details and history of a specific ticket
• Create a ticket on behalf of a user
• Add a reply or internal note
• Change a ticket's status or assignee

The MCP server sits on top of the REST API — every operation goes through the same permission checks. An AI assistant using a Staff user's API key cannot do anything a Staff user couldn't do manually.

Available tools

Five tools, all requiring a Staff or Admin account. Identifiers are UUIDs.

get_ticket

Get a ticket by its UUID or tracking number.

list_tickets

List tickets assigned to a user.

This lists by assignee only. It does not filter by status, priority, category or free text — use the REST API for those.

create_ticket

Open a new ticket.

add_reply

Add a reply to a ticket, authored by the authenticated caller.

Replies posted through MCP are public and notify the reporter. There is no internal-note option here; use the REST API or the web UI for internal notes.

assign_ticket

Assign a ticket to a user or a group, performed as the authenticated caller.

Omitting both clears the assignment.

Connecting clients

Claude (claude.ai / Claude Code)

Add a server entry to your MCP configuration. In Claude Code, this lives in .claude/mcp.json (project-level) or ~/.claude/mcp.json (global).

{
  "mcpServers": {
    "helpdesk": {
      "type": "http",
      "url": "https://helpdesk.example.com/mcp/",
      "headers": {
        "Authorization": "ApiKey 3f8a…"
      }
    }
  }
}

After saving, Claude will have access to the help desk tools in any conversation where MCP is active.

VS Code with Continue

// .continue/config.json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "http",
          "url": "https://helpdesk.example.com/mcp/",
          "requestOptions": {
            "headers": {
              "Authorization": "ApiKey 3f8a…"
            }
          }
        }
      }
    ]
  }
}

Cursor

// cursor/mcp.json (in project root or ~/.cursor/mcp.json)
{
  "mcpServers": {
    "helpdesk": {
      "url": "https://helpdesk.example.com/mcp/",
      "headers": {
        "Authorization": "ApiKey 3f8a…"
      }
    }
  }
}

Any HTTP MCP client

The MCP server implements the standard Streamable HTTP transport. Point any compliant client at:

https://<BASE_URL>/mcp/

Include an Authorization header with either an API key or a JWT from the OAuth2 token endpoint.

Authentication

Since v1.1.1 the MCP server sits behind the same authentication middleware as the REST API, and accepts any of:

• API key (recommended for long-lived client configs) — Authorization: ApiKey <token> — 64 hex characters, no prefix, shown once when the key is created
• OAuth2 JWT (recommended for server-to-server) — obtain a token from POST /api/v1/auth/oauth/token and send it as Authorization: Bearer <jwt>.
• Session cookie — works, but is only useful from a browser context.

Unauthenticated requests receive 401. Requests from an account without the required role receive 403.

Permissions

The MCP server is restricted to Staff and Admin accounts. A reporting user receives 403 and cannot reach any tool, regardless of which ticket they are asking about.

That is deliberately stricter than the REST API, which lets a reporting user read their own tickets by applying a scope check in each handler. Duplicating those checks in a second surface is how the two drifted apart in the first place, so the MCP surface takes the narrower rule instead.

Identity comes from the request, never from a tool argument. Before v1.1.1, add_reply and assign_ticket accepted author_user_id and actor_user_id parameters — a caller named itself and the server believed it. Those parameters no longer exist. The one identity field that remains, reporter_user_id on create_ticket, names the subject of a ticket rather than the caller, because staff legitimately open tickets on someone's behalf.

MFA is enforced for parity with the ticket API, so MCP cannot be used to sidestep a TOTP challenge. API keys and bearer tokens are unaffected.

If a tool call fails a permission check, the MCP server returns a structured error and does not execute the operation. The assistant receives a description of the error and can inform the user.