Tickiti

tickiti-mcp

An MCP (Model Context Protocol) server that exposes the Tickiti helpdesk API to AI assistants such as Claude. It is a thin shim over the Tickiti Public API v1 (/api/v1/...): each MCP tool forwards to a v1 endpoint, adding your bearer token and — for writes — an idempotency key. The token's abilities are the security boundary: the server only relays calls, it never widens them, so a read-only token gives a read-only assistant.

📖 Full documentation: https://www.tickiti.com/docs/topic/mcp_server/

Tools

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

Tickets

Tool	Ability	Purpose
create_ticket	tickets:write	Open a ticket (subject+content, template, or intervention), with assignee, priority, status and participants; is_public is required
respond_to_ticket	tickets:write	Post a response; change status, hold, assignee, priority, queue, subject, participants; send_full_email for the whole reply by email
close_ticket	tickets:write	Close, optionally with a final reply and a resolution
edit_response	tickets:write	Change a response in place (whole body, find/replace, visibility) with no notification — or publish an internal note and notify
delete_response	tickets:write	Soft-delete a response
add_participants / remove_participants	tickets:write	Change participants
delete_tickets / restore_ticket	tickets:write	Delete tickets (by number, or everything from one sender) and undo it
merge_tickets	tickets:write	Merge two tickets (the older survives)
link_tickets / unlink_tickets / list_linked_tickets	tickets:write / read	The Linked panel
move_responses / copy_responses / split_ticket	tickets:write	Repair a thread: move or copy responses, or split them off into a new linked ticket
change_originator	tickets:write	Change who raised a ticket
delete_attachment	tickets:write	Remove one attachment (a malicious file, say), keeping a record of it
get_ticket / list_responses	tickets:read	A ticket's thread, participants and links; fields / max_body_chars keep long email threads small
get_response	tickets:read	One response by id
query_tickets	tickets:read	Search tickets
query_responses / export_responses	tickets:read	Responses across tickets; counts and group-by tallies; NDJSON export to disk
get_attachment / download_attachment	tickets:read	Attachment bytes (download streams any size to a file)
list_queues / list_teams / list_staff / list_resolutions / get_search_modes	tickets:read	Queue names and settings, team keys, staff addresses, resolution categories, the search vocabulary

Settings, templates, mail, administration

Tool	Ability	Purpose
list_perspectives / get_perspective	settings:read	Saved views, with conditions and sort orders
list_watchlists	settings:read	Watchlists
list_stock_responses / get_stock_response	settings:read	Stock responses (search, bodies)
create_stock_response / update_stock_response / delete_stock_response	settings:write	Edit stock responses
get_template / search_templates / render_template	templates:read	Templates and FAQs; render one against data without sending
create_template / update_template	templates:write	Edit templates (updates change only the fields given)
upload_template_image	templates:write / settings:write	Upload an image for a template or stock response
send_email / search_sent_mail	mail:write / mail:read	Send mail; search what was sent
list_api_tokens / create_api_token / update_api_token / revoke_api_token	administration:*	API keys (a token only grants abilities it holds)
list_workflow	workflow:read	Resolution categories, interventions, escalations
run_report	reports:read	Analytics reports
get_token_info	any	What this token can do: abilities, owner roles, plan
list_instances	—	The Tickiti instances configured (see below)
list_endpoints	—	Every API endpoint, with abilities, path and body 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 — covering all of the v1 API.

Requirements

• Node.js 20 or newer
• A Tickiti API token, minted from Administration → API keys, scoped to the abilities you want the assistant to have
• An MCP-capable client — e.g. Claude Code or the Claude desktop app

Install

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 (it fails fast on startup if either is missing):

Variable	Purpose
TICKITI_API_BASE	Your Tickiti install's public address, no trailing slash — e.g. https://support.example.com. The server appends /api/v1/….
TICKITI_API_TOKEN	The bearer token. Its abilities determine what the assistant can do.

More than one instance

To reach several Tickiti installs from one server (production and staging, say), add TICKITI_INSTANCES: JSON, or the path of a JSON file, mapping a name to { "base", "token" }. The TICKITI_API_BASE / TICKITI_API_TOKEN pair stays the default instance, named by TICKITI_INSTANCE_NAME (default default).

TICKITI_INSTANCE_NAME=production
TICKITI_INSTANCES='{"staging": {"base": "https://staging.example.com", "token": "…"}}'

Every tool then takes an optional instance argument; list_instances shows the names.

Use with Claude Code

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

Confirm with claude mcp list (or /mcp in a session). Remove with claude mcp remove tickiti.

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

Permissions & security

The 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 read-only token (e.g. 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 (missing ability, role or plan).

The ticket-writing tools send an idempotency key with every call, so a retried request never creates a duplicate ticket or response.

Long bodies can be given as content_path (a local file) instead of content, and files and images always go by path: the server reads them, so their bytes never pass through the model.

How it works

File	Role
src/client.ts	Request core: base URL, bearer auth, idempotency, error normalisation
src/result.ts	Maps an API result into the MCP tool-result envelope
src/manifest.ts	Helpers over the generated route manifest (lookup, path building)
src/generated/manifest.ts	Auto-generated route table (do not edit)
src/tools/tickets.ts	Ticket writes — verified input schemas
src/tools/ticket-reads.ts	Ticket, response and attachment reads
src/tools/ticket-operations.ts	Delete, merge, link, move, originator, attachment delete, lookups
src/tools/settings-writes.ts	Stock responses and templates
src/tools/admin.ts	Mail, template rendering and images, perspectives, API keys, instances
src/tools/reads.ts	Named read tools (settings / workflow / reports)
src/tools/generic.ts	list_endpoints + tickiti_call
src/param-hints.ts	Body parameters list_endpoints shows for endpoints without a dedicated tool
src/server.ts	Entry point: registers tools, connects the stdio transport
scripts/build-manifest.mjs	Regenerates the manifest from the Tickiti route table

Maintainers

src/generated/manifest.ts is generated from Tickiti's own route table (php artisan route:list --json), so abilities, roles, plan gates and path params are never hand-maintained. Regenerate against a Tickiti checkout after the API changes:

TICKITI_DIR=/path/to/tickiti npm run manifest

There is an end-to-end sweep over every endpoint in tests/all-paths.mjs (npm run test:paths, needs a base URL and a full-ability token against a scratch instance), and an offline check of the tool registration in tests/smoke-tools.mjs (npm run build && node tests/smoke-tools.mjs).

Several tools call endpoints added to Tickiti in October 2026. Against an older install they return 404; list_endpoints describes the newest API.

License

MIT © Oxenic