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 and, for writes, an idempotency key. 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.

The server is open source: github.com/tickiti/tickiti-mcp.

What you can do

The server publishes named tools for the everyday work, with 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.

Tickets

Settings, templates, mail, administration

For anything beyond the named tools — mailbox and workflow configuration, administration, supervisor — the assistant uses list_endpoints to discover the action, then tickiti_call to run it. list_endpoints takes an optional family filter and shows, for each endpoint, its action key, required abilities, role, plan gates, path parameters and the body parameters it takes, so the assistant can build the call without guessing field names. The full endpoint set is the same one described in the API overview.

Creating tickets

create_ticket requires is_public on every call: true makes the opening response customer-visible, false makes it a staff-only internal note. Alongside it, give originator_email_address and exactly one payload shape — subject + content, template_identifier + data, or intervention + data + uid. See the Create ticket API for the fields behind it.

Long bodies, files and images

Anything large goes by path to a local file on the machine running the MCP server. The server reads or writes the file itself, so the bytes never pass through the assistant.

Long bodies — create_ticket, respond_to_ticket, edit_response and send_email accept content_path, a file holding the HTML body, in place of content. Give one or the other.

Inline images — the attachments list on create_ticket and respond_to_ticket 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.

Template and stock-response images — upload_template_image takes the image’s path and returns an <img> tag to place in the content with update_template or update_stock_response.

Downloads and exports — download_attachment and export_responses write to the path you give and return a short manifest (path, size or record count) rather than the content.

Referring to a ticket by number or id

Anywhere a ticket is identified — get_ticket, list_responses, get_attachment, respond_to_ticket, close_ticket and the other ticket tools — 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

1. Node.js 20 or newer.
2. A Tickiti API token, minted from Administration → API keys, scoped to the abilities you want the assistant to have. See Authentication and tokens.
3. 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 is configured through environment variables:

The server checks its configuration on start-up and stops with a clear message if no instance is configured or an instance is missing its address or token.

More than one instance

One server can reach several Tickiti installs — production and staging, say. Set TICKITI_INSTANCES to JSON, or to the path of a JSON file, mapping each instance’s name to its base and token:

{
  "staging": {
    "base": "https://staging.sole-trader.example",
    "token": "YOUR_STAGING_TOKEN"
  }
}

The TICKITI_API_BASE / TICKITI_API_TOKEN pair remains the default instance, named by TICKITI_INSTANCE_NAME. With more than one instance configured, every tool takes an optional instance argument naming the one to call; without it, the call goes to the default. list_instances shows each instance’s name and address — never its token — and which one is the default. A file keeps the tokens out of your client’s configuration.

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 /absolute/path/to/tickiti-mcp/dist/server.js

With a second instance, name the default and point at the instances file:

claude mcp add tickiti \
  --env TICKITI_API_BASE=https://support.sole-trader.example \
  --env TICKITI_API_TOKEN=YOUR_TICKITI_API_TOKEN \
  --env TICKITI_INSTANCE_NAME=production \
  --env TICKITI_INSTANCES=/absolute/path/to/tickiti-instances.json \
  -- node /absolute/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 /absolute/path/to/tickiti-mcp/dist/server.js as a stdio server, with TICKITI_API_BASE and TICKITI_API_TOKEN (and any of the optional variables) 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:

1. “Open a ticket from [email protected] in the Sales queue about a cracked carbon plate.” → create_ticket
2. “Reply to ticket 709383 to say the replacement is on its way.” → respond_to_ticket
3. “Show me the open tickets in the All perspective.” → query_tickets
4. “Show me what the order-dispatched email looks like for order TB-10442.” → render_template
5. “Run the volumes report for May grouped by week.” → run_report
6. “List the open tickets on staging.” → query_tickets with instance
7. “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:

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

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

Where to go next

1. API overview — the REST endpoints the tools map to.
2. Authentication and tokens — mint, scope and rotate the token the server uses.
3. Templates API, Settings API and Mail API — the endpoints behind the template, stock-response and mail tools.