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)
`respond_to_ticket`	tickets:write	Post a response to an existing ticket
`query_tickets`	tickets:read	List tickets for a perspective
`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.

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 marcus@trailblazers-club.example 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.