MCP server

This article is written for a technical audience — integrators connecting an AI assistant to Tickiti. Familiarity with the command line, Node.js and bearer-token authentication is assumed.

The Tickiti MCP server exposes the Tickiti API to AI assistants that speak the Model Context Protocol (MCP) — such as Claude. It is a thin layer over the REST API: each MCP tool maps to a /api/v1 endpoint, forwarding the call with your bearer token. Once connected, you ask the assistant in plain language — “open a ticket for this customer”, “show me the open Sales tickets”, “run the volumes report for last month” — and it picks the right tool.

Because every call goes through the same API, the token’s abilities are the security boundary: the MCP server can never do more than the token allows. A read-only token gives a read-only assistant.

What you can do

The server publishes a focused set of tools. The ticket tools have full, validated inputs; the rest of the API is reachable through two general tools so the entire surface is available without a separate tool per endpoint.

Tool	Ability	Purpose
`create_ticket`	tickets:write	Open a ticket (subject+content, template, or intervention); attach inline images or downloadable files passed as local file paths
`respond_to_ticket`	tickets:write	Post a response to an existing ticket (by number or id); attach inline images or downloadable files passed as local file paths
`query_tickets`	tickets:read	List tickets for a perspective
`get_ticket`	tickets:read	Read one ticket with its full response thread (public + internal) and attachment metadata, by ticket number or id
`list_responses`	tickets:read	List a ticket’s responses (bodies, public/internal flag, attachment metadata), by ticket number or id
`get_attachment`	tickets:read	Download a response attachment’s bytes (returned as an embedded resource)
`query_responses`	tickets:read	Query responses across every ticket you can see, filtered by date range, queue or the internal/staff flags — the bulk counterpart to `list_responses`
`export_responses`	tickets:read	Dump matching responses to a local NDJSON file, paging server-side — for large date-range exports the bodies never pass through the assistant
`list_perspectives`	settings:read	List saved perspectives
`list_watchlists`	settings:read	List watchlists
`list_stock_responses`	settings:read	List stock responses
`list_queues`	workflow:read	List ticket queues
`list_workflow`	workflow:read	List resolution categories, interventions or escalations
`run_report`	reports:read	Run an analytics report
`list_endpoints`	—	Discover every available API endpoint, with its abilities and parameters
`tickiti_call`	per endpoint	Call any `/api/v1` endpoint by family and action

For anything beyond the named tools — mail, templates, workflow writes, administration, supervisor — the assistant uses list_endpoints to discover the action, then tickiti_call to run it. The full endpoint set is the same one described in the API overview.

Attachments

The create_ticket and respond_to_ticket tools attach files in two ways, and both take the path to a local file on the machine running the MCP server — the server reads the bytes itself, so the assistant never handles the file data directly.

Inline images — the attachments list embeds images (png, jpg, gif, webp, bmp or svg) within the message body. To control placement, put a {{attach:<name>}} token in content where the image should appear; otherwise it is added at the end. Tickiti stores each as an inline attachment and renders it in the thread.

Downloadable files — the files list attaches files of any type (a PDF, CSV, ZIP, log, or an image you want offered as a download rather than shown inline), up to 25 MB each. Each becomes a normal downloadable attachment on the response rather than being embedded in the body. Attachments are subject to your account’s file-type rules; a blocked type is refused with the reason.

Referring to a ticket by number or id

Anywhere a ticket is identified — get_ticket, list_responses, get_attachment and respond_to_ticket — you may give either its number (the short human reference) or its internal id. Supply one or the other. The id is handy when you already hold it from an earlier result, such as the ticket id returned when you post a response.

Prerequisites

Node.js 20 or newer.
A Tickiti API token, minted from Administration → API keys, scoped to the abilities you want the assistant to have. See Authentication and tokens.
An MCP-capable client — for example Claude Code or the Claude desktop app.

Install

Clone the repository, install dependencies and build:

git clone https://github.com/tickiti/tickiti-mcp.git
cd tickiti-mcp
npm install
npm run build

The built server is dist/server.js.

Configure

The server reads two environment variables:

Variable	Purpose
`TICKITI_API_BASE`	Your Tickiti install’s public address, with no trailing slash — for example `https://support.sole-trader.example`. The server appends `/api/v1/…`.
`TICKITI_API_TOKEN`	The bearer token minted above. Its abilities determine what the assistant can do.

The server fails fast on start-up if either is missing.

Register with your assistant

With Claude Code, add the server in one command — the token and base URL travel as environment variables:

claude mcp add tickiti \
  --env TICKITI_API_BASE=https://support.sole-trader.example \
  --env TICKITI_API_TOKEN=YOUR_TICKITI_API_TOKEN \
  -- node /path/to/tickiti-mcp/dist/server.js

Confirm it connected with claude mcp list (or /mcp inside a session) — tickiti should report as connected. To remove it later, use claude mcp remove tickiti.

Other MCP clients configure servers in their own settings file, but the shape is the same: run node /path/to/tickiti-mcp/dist/server.js as a stdio server, with TICKITI_API_BASE and TICKITI_API_TOKEN set in its environment.

Using it

You drive the server through the assistant in plain language; it chooses the tool and shows you the result. For example:

“Open a ticket from [email protected] in the Sales queue about a cracked carbon plate.” → create_ticket
“Reply to ticket 709383 to say the replacement is on its way.” → respond_to_ticket
“Show me the open tickets in the All perspective.” → query_tickets
“Run the volumes report for May grouped by week.” → run_report
“What can you do in Tickiti?” → list_endpoints

Permissions and safety

The MCP server adds no permissions of its own. Every call runs as the staff user the token belongs to, gated by the token’s abilities — exactly as a direct API call would be. To limit what an assistant can do, mint a narrowly-scoped token:

A token with only read abilities (for example tickets:read, reports:read) gives an assistant that can look but not change anything.
Grant write abilities only for the families the assistant needs to act on.
If a call is refused, the server reports the reason — the missing ability, role or plan — so you can adjust the token.

The two ticket-writing tools send an idempotency key with every call, so a retried request never creates a duplicate ticket or response. See Idempotency for the semantics.

Where to go next

API overview — the REST endpoints the tools map to.
Authentication and tokens — mint, scope and rotate the token the server uses.