tickiti-mcp
Officialtickiti-mcp is an MCP server that lets an AI assistant read and act on a Tickiti helpdesk through the Tickiti Public API v1, limited by the API token’s abilities.
Create tickets and add responses, including internal notes.
Query tickets, saved perspectives/views, watchlists, queues, stock responses, workflow configuration, and analytics reports.
Use
list_endpointsto discover any v1 endpoint, thentickiti_callto invoke it.The README documents broader coverage: ticket edits/deletes/merges/links/splits, attachments, checklists, reminders, tags, templates, mail, administration/API keys, automations, SLA, and Axial AI features.
Supports multiple Tickiti instances, idempotency keys for writes, and token-scoped permissions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tickiti-mcp create a ticket about network latency in the office"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
|
| Open a ticket (subject+content, template, or intervention), with assignee, priority, status and participants, and a contact form's |
|
| Post a response; change status, hold, assignee, priority, queue, subject, participants; |
|
| Close, optionally with a final reply (and its signature) and a resolution |
|
| Change a response in place (whole body, find/replace, visibility) with no notification — or publish an internal note and notify |
|
| Soft-delete a response |
|
| Change participants |
|
| Delete tickets (by number, or everything from one sender) and undo it |
|
| Merge two tickets (the older survives) |
|
| The Linked panel |
|
| Repair a thread: move or copy responses, or split them off into a new linked ticket |
|
| Change who raised a ticket |
|
| Remove one attachment (a malicious file, say), keeping a record of it |
|
| A ticket's thread, participants, links and waiting interventions; |
|
| One response by id, with |
|
| Search tickets |
|
| Responses across tickets; counts and group-by tallies; NDJSON export to disk |
|
| Attachment bytes (download streams any size to a file) |
|
| Queue names and settings, team keys, staff addresses, resolution categories, the search vocabulary |
|
| The ticket browser's Save over up to 100 tickets (status, hold, queue, assignee, priority, resolution, start/due dates), each judged on its own under the queue/assignee rule; |
|
| A ticket's checklist: get, add (text, items or a template), tick / edit, reorder, delete |
|
| A ticket's reminders: list, add (one-off or repeating), delete (the owner's, or an admin of at least their rank) |
|
| Pin or unpin a response; undo a response's deletion (an admin or a manager of the ticket's queue) |
|
| @tag staff on a response (notifies them), list a ticket's tags, acknowledge your own |
|
| The token owner's own bump, read / unread and private note on tickets |
|
| A ticket's permanent share link (created on first request) |
|
| The owner's replies held with Send later: list, cancel, send now, reschedule |
|
| Inbound emails held for review (sender not a participant, duplicate, already has a ticket): keep or merge |
Settings, templates, mail, administration
Tool | Ability | Purpose |
|
| Saved views, with conditions and sort orders |
|
| Watchlists, filtered by id, name, owner or shared, with their tickets |
|
| Create, change or delete a watch list; add, remove or reorder its tickets (on a private list, only its owner) |
|
| The token owner's own out-of-office periods and email signature |
|
| Stock responses (search, bodies) |
|
| Edit stock responses |
|
| Templates and FAQs; render one against data without sending |
|
| Edit templates, with category, subcategory and keywords (updates send, and change, only the fields given) |
|
| Upload an image for a template or stock response |
|
| A template's translation into one language: get, save, delete |
|
| Send mail; search what was sent |
|
| A sent message exactly as sent, saved as an .eml file |
|
| Inbound attachments by extension: always allowed, hard blocked, or held for review |
|
| A user's email address change (request, resend, cancel) and WhatsApp (start, status, quiet hours, remove) |
|
| API keys (a token only grants abilities it holds) |
|
| Resolution categories, interventions, escalations |
|
| Move every ticket in one queue to another through the ticket engine (history, perspectives, open views); repeat while |
|
| Automation rules: list (with the editor's vocabulary), create, update, enable, reorder, delete, dry-run test ( |
|
| SLA policies: list, create, update, reorder, delete |
|
| Recurring tasks: list, create, update, run now, delete |
|
| Checklist templates; business-hours holidays; intervention definitions (update merges; |
|
| Analytics reports, the SLA and satisfaction reports, Axial usage and Axial ratings |
|
| Confirm a latched health alert |
| any | What this token can do: abilities, owner roles, plan |
| — | The Tickiti instances configured (see below) |
| — | Every API endpoint: abilities, role, plan, path params, required body fields, an upload's file field; filtered by family or action, every body field with its validation rules. Marks endpoints the instance lacks, where it lists its own |
| per endpoint | Call any |
Axial
Tool | Ability | Purpose |
|
| A ticket's Axial panel and runs |
|
| Talk to Axial on a ticket, answer its cards, rerun it |
|
| The panel's other buttons: approve or reject an action, a shared note's card, update the suggested response, respond again, add a note, cancel a queued request, give a task, investigate in depth, stop a task, choose the skill, turn back on, approve translations (also |
|
| The token owner's own conversations with Axial outside any ticket, and the cards Axial asks for in them ( |
|
| The Axial settings pages (including |
|
| Axial's skills |
A tool that covers a resource takes an action (list, create, update, delete ...). An
argument that belongs to another action of the tool is refused by name, as an unknown one is,
and so is a call missing what its action needs; nothing is sent.
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.
Arguments are checked
Every tool refuses an argument it does not list, before anything is sent, with an error that
names the argument and the ones the tool takes. A reply sent as html instead of content,
or a tickiti_call body sent as params instead of payload, used to be dropped without a
word, so the call went out without it and looked as if it had worked. The free-form fields
(payload, data, filters, search_object) are not checked key by key; Tickiti validates
what is in them. tickiti_call with no payload to an endpoint whose fields are required is
refused, naming them.
Related MCP server: Gorgias MCP Server
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 buildThe built server is dist/server.js.
Configure
The server reads two environment variables (it fails fast on startup if either is missing):
Variable | Purpose |
| Your Tickiti install's public address, no trailing slash — e.g. |
| The bearer token. Its abilities determine what the assistant can do. |
Optional:
Variable | Purpose |
| The directories, separated as |
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 takes an optional instance argument naming one of them (the first is the default);
list_instances shows the names. A server with one instance takes it too, but only naming that
one: a call that names it is accepted, and one that names any other instance is refused before
anything is sent.
A TICKITI_INSTANCES that cannot be read is refused at start with its length (and the path, when
it is a .json file's), never its text, so a mistyped value does not put its tokens in a log.
To keep the tokens out of any config file, have the launcher build TICKITI_INSTANCES in its own
environment from wherever the tokens are kept and then start the server, so the JSON only ever
exists in that process. On Windows, with the tokens in Credential Manager:
# $tokens: name -> token, read from Credential Manager by the launcher (not shown)
$env:TICKITI_INSTANCES = @{
staging = @{ base = 'https://staging.example.com'; token = $tokens['staging'] }
} | ConvertTo-Json -Compress
& node /absolute/path/to/tickiti-mcp/dist/server.jsOlder instances
The endpoint list is built from the Tickiti this release was made from, but an instance can run
another build (a hosted tenant can lag a version). A call to an endpoint the instance does not
have gets Laravel's "The route ... could not be found", and the server says that this is what it
means. If the instance lists its own endpoints in v1/token (data.endpoints: route names, or
{name, uri, method}; and data.version), list_endpoints marks the ones it lacks
(on_instance: false) and lists the ones only it has, and tickiti_call refuses the first with
the instance's version and can call the second. Tickiti does not report that list yet.
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.jsConfirm 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 |
| Request core: base URL, bearer auth, idempotency, error normalisation |
| Maps an API result into the MCP tool-result envelope |
| Helpers over the generated route manifest (lookup, path building) |
| Auto-generated route table (do not edit) |
| Ticket writes — verified input schemas |
| Ticket, response and attachment reads |
| Delete, merge, link, move, originator, attachment delete, lookups |
| Bulk update, checklist, reminders, pins, restore, tags, own state, share link, Send later, reviews |
| Queue moves, automations, SLA, recurring tasks, checklist templates, holidays, interventions, mail attachment rules |
| Axial panel actions, Axial conversations, Axial settings |
| Out of office, signature, user accounts, watch lists, translations, alerts, sent mail as .eml |
| One tool per resource with an |
| Stock responses and templates |
| Mail, template rendering and images, perspectives, API keys, instances |
| Named read tools (settings / workflow / reports) |
|
|
| Hand-kept notes on a body's shape and meaning, shown by |
| Auto-generated body fields and validation rules per endpoint (do not edit) |
| The instance's own endpoint list, where it gives one |
| Entry point: registers tools, connects the stdio transport |
| Regenerates the manifest from the Tickiti route table, and the body fields |
| Reads each endpoint's body fields from the controllers' validation (run by the above) |
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 manifestThe same run writes src/generated/body-fields.ts: scripts/body-fields.php follows each route's
action into the controller that validates it (through the v1 passthru controllers) and reads the
validate() / Validator::make() rules and the $request->input() reads. It needs php and the
Tickiti checkout's vendor/. --body-fields-only rewrites that file and leaves the manifest.
It reads the methods' source and calls none of them, but it does load the checkout's autoloader
(Composer's files autoloads run), its classes and their constants, so point TICKITI_DIR only at
a checkout you trust.
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). The other offline tests run the built server
against a local stand-in for Tickiti, or its helpers directly: strict-and-generic, new-endpoint-tools,
reply-attachments, axial-skill-questions, file-roots and inline-images
(node tests/<name>.mjs).
Several tools call endpoints added to Tickiti in October 2026 and later. Against an older install they get Laravel's route-not-found 404, which the server explains (see Older instances).
License
MIT © Oxenic
Available Tools
11 toolscreate_ticketCreate ticketA
Create a support ticket. Provide originator_email_address and EXACTLY ONE of: subject+content, OR template_identifier+data, OR intervention+data+uid. Omit queue_name to use the Inbox; queue_name is not allowed with intervention.
Inputs: originator_email_address (required), subject, content, template_identifier, +6 more.
list_endpointsList Tickiti API endpointsA
Discover available Tickiti v1 endpoints. Optionally filter by family (one of: administration, idempotency_key, mail, reports, settings, supervisor, templates, tickets, workflow). Returns each endpoint's action key, required abilities, role, plan gates and path params — use these with tickiti_call.
Inputs: family.
list_perspectivesList saved perspectives (views)D
List saved perspectives (views)
Inputs: filters.
list_queuesList ticket queuesD
List ticket queues
Inputs: filters.
list_stock_responsesList stock (canned) responsesD
List stock (canned) responses
Inputs: filters.
list_watchlistsList watchlistsD
List watchlists
Inputs: filters.
list_workflowList workflow configurationB
List a plan-gated workflow collection: resolution-categories, interventions, or escalations. Returns 403 if the instance's plan does not include the feature.
Inputs: kind (required), filters.
query_ticketsQuery ticketsA
List tickets for a perspective (saved view). Specify perspective_id or perspective_name; defaults to the 'All' perspective. Pass a ticket number via search_object for a direct lookup.
Inputs: perspective_id, perspective_name, search_object.
respond_to_ticketRespond to ticketA
Add a response to an existing ticket (reopens it if closed). Set is_internal=true for a staff-only note.
Inputs: ticket_number (required), from_email (required), content (required), is_internal.
run_reportRun an analytics reportA
Run a Tickiti analytics report (requires the reports plan + admin). 'meta' returns the filterable queues; the others accept date/queue filters via filters.
Inputs: report (required), filters.
tickiti_callCall any Tickiti v1 endpointA
Advanced escape hatch: invoke any Tickiti v1 endpoint not covered by a dedicated tool. Use list_endpoints first to find the family + action. payload becomes the JSON request body; for endpoints with path params (e.g. user, queue) include those keys in payload too.
Inputs: family (required), action (required), payload.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct operation: ticket creation, listing different resources, querying, responding, reporting, and an escape hatch. No overlapping purposes.
All tools follow a consistent verb_noun pattern using snake_case (e.g., create_ticket, list_endpoints, query_tickets). Even the generic 'tickiti_call' fits the pattern.
11 tools is well-scoped for a ticket management system, covering creation, listing, querying, responding, reporting, and advanced operations without unnecessary bloat.
The set covers the main ticket lifecycle (create, query, respond) and auxiliary lists. Minor gaps like explicit close or update are mitigated by the generic tickiti_call tool, so agents can work around them.
Maintenance
Related MCP Connectors
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Customer support for MCP servers: work your tickets from Claude or any MCP client. Service key auth.
Related MCP Servers
AlicenseAqualityDmaintenanceAn MCP server that lets AI assistants search and read support tickets from Jitbit Helpdesk. Works with both SaaS and on-premise installations.342 npm3MIT- AlicenseAqualityDmaintenanceAn MCP server that exposes the full Gorgias helpdesk API to AI assistants, enabling ticket management, analytics, and customer operations through natural language.100112 npm2MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that wraps the TeamDynamix Web API, enabling AI assistants to search tickets, manage assets, query the knowledge base, and look up people in your TDX instance.1-
- AlicenseAqualityCmaintenanceMCP server for the Ticksy support ticket API, enabling AI agents to read and write support tickets.16227 npmMIT