Tool Reference

The Swarmtix MCP server exposes 24 tools: 17 that read your data and 7 that make safe changes. This page is the index — every tool, the permission it needs, whether it only looks or also writes, and a link to its own page.

Quick Start

You do not call these by name. Ask your assistant for what you want and it picks the tool:

How did ticket sales go for spring-summit-2026?

Add a $45 early-bird ticket to the spring showcase, capped at 100.

To see exactly which tools your connection holds, ask your client to list them — Claude Code shows them under /mcp, VS Code in the tool picker, and a raw client gets them from tools/list. Each entry carries its own JSON Schema, so the exact parameter names and types always come from the live server rather than from a page that can drift.

Reads

Seventeen tools. None of them change anything. All are marked read-only, non-destructive and idempotent, so a client is free to retry one safely.

The order and attendee tools return your buyers' names and email addresses. They never return a ticket's barcode or security code — that is the credential that admits someone to an event, and no tool produces one.

Safe Writes

Seven tools. Each one creates or edits something, and none of them can publish, delete, charge, refund or send.

The Repeatable column says whether calling the tool twice with the same arguments leaves you in the same place. Yes means a retry is safe. No means a second call creates a second thing — a duplicate draft event, a duplicate ticket type — so a client should not retry blindly.

Not Tools, But Next to Them

Two of these tools have a second way in, and four ready-made requests are built on top of the catalog.

• Resources — swarmtix://events/{idOrSlug} and swarmtix://events/{idOrSlug}/analytics return exactly what swarmtix_events_get and swarmtix_analytics_event return, addressed by URI so an assistant can attach an event as context instead of spending a call. Same scopes, same ownership check. They are listed by resources/templates/list, not resources/list.
• Prompts — four workflow requests covering a readiness check, a sales review, an orders-against-attendees reconciliation and a post-event write-up. Each is offered only when every scope its work touches was granted.

What Is Not Here

There is no tool for refunds or charges, publishing or unpublishing, check-in or barcode scanning, bulk attendee email, guest-list import, deleting anything, closing an account, changing a subscription, injecting tracking scripts, or registering a webhook.

These are absent by design, not pending. The reasoning is on the overview page. The short version: the catalog stays honestly labelled — no tool mixes a safe operation with a dangerous one — and the worst case of a misread instruction stays "a draft was edited".

How the Tools Behave

Naming

Every tool is swarmtix_<resource>_<action>. The prefix is redundant inside a server that is already namespaced, but some clients flatten tool names into a single list, and there the prefix is what keeps events_list from colliding with another connector's.

Each tool's page on this site drops the prefix and swaps underscores for dashes, so swarmtix_events_list is documented at /docs/mcp/tools/events-list.

Identifiers

Where something has a human-readable identifier, tools accept it. Events have a URL slug, so spring-summit-2026 works anywhere an event id works. You do not have to look up an id to ask a question about an event you can name.

Everything else is addressed by the id a read tool gave you. Scheduled dates come from swarmtix_event_dates_list, ticket types from swarmtix_ticket_types_list, orders from swarmtix_orders_list.

Paging

Every list tool pages, and every one of them spells it the same way: limit for the page size, cursor for where to resume. The default page size is 50 and the maximum is 200.

Asking for more than 200 is refused rather than quietly reduced:

limit is not valid: it was 500. Expected a whole number from 1 to 200, or nothing for 50.

Silently returning 200 rows to a caller who asked for 5,000 looks exactly like the list ending.

Paging is cursor-based, not offset-based. A page that does not cover everything ends with a continuation line naming the cursor for the next call:

Showing 50 of 1284. Call again with cursor "NGUxYzhhOTMtNzdmMi00YjVkLTljMDYtMmE4ZTVkMWYzYjc0" for the rest.

The line sits after the JSON, separated by a blank line. Pass the quoted string back as cursor on the next call and you get the rows after it.

Offsets were not an option: ticket sales insert rows while you are reading, so "rows 51 to 100" means something different each time you ask, and records get skipped or repeated. A cursor names a row, so it does not drift.

You never need to construct or interpret a cursor. It is opaque; pass back exactly what you were given. One tool, swarmtix_attendees_search, uses a positional cursor instead, because the data it reads carries no stable key — its page explains the difference and when it matters.

Response size

A single tool result is capped at 60,000 characters. That is roughly a quarter of the 25,000-token ceiling Claude Code puts on a tool response, which leaves room for the client's own framing around it.

The cap applies to the JSON only. The continuation line is appended afterwards, so a full page plus its line can never push past it.

Truncation is never silent, and the two cases read differently:

• A list is shortened. Fewer rows come back than the limit asked for, the continuation line says how many were sent, and the cursor points at the last row that actually made it into the result rather than at the one the tool intended to send.
• A single record that will not fit is cut and labelled. The notice is prose rather than another JSON field, because a record cut at 60,000 characters no longer parses and the reason has to survive that:

-- Truncated. This record is 74210 characters and the response budget is 60000, so the last 14210 characters of the JSON above were cut and it will not parse. Open the record in the Swarmtix dashboard for the full version.

A silent cut-off is worse than a stated one, because an assistant that does not know it is looking at part of the data will answer confidently from the part it has.

Errors

When a tool cannot do what was asked, it says why in a sentence — which argument was wrong, what it expected, what to try instead. Not a numeric code and not a stack trace. Every message opens with a stable phrase, so both you and your assistant can recognise the case:

The last two rows are the ones worth reading twice. Swarmtix could not complete this request. Nothing was changed. promises a clean slate, so a retry is safe. Swarmtix applied part of this request and then stopped. promises the opposite, and it names what landed so you can look before trying again. Only swarmtix_event_dates_set can produce it.

Two write refusals have wording of their own rather than the shapes above, because neither is an argument problem:

• swarmtix_ticket_types_update refuses a price change once tickets of that type have sold.
• The creating tools refuse to report an event as a draft if the stored row says otherwise.

Both pages quote the exact sentence.

Rate limits

60 requests per minute per organisation, on a sliding window, counted across every credential that organisation has — two assistants and a Zapier integration share one budget, they do not each get their own.

Going over returns 429 with Retry-After in seconds, and the tool message Rate limit reached. Retry in <n> seconds. The number in the sentence is the same integer as the header. Most clients wait and retry without being told.

This limit is separate from, and on top of, the site-wide per-IP limit that applies to all Swarmtix traffic. Staying under one does not exempt you from the other.

Annotations

Every tool declares all four MCP annotations explicitly, so your client can show you accurate warnings before it runs anything:

openWorldHint is false across the board: every tool works against Swarmtix data only, and none reaches out to a third-party service.

Troubleshooting

"This connection is not authorized for analytics:read. Reconnect and grant it to use this tool."

The message names the scope the tool needs. Find that tool in the tables above to confirm, then revoke the connection and authorize it again with that permission approved.

The assistant says a tool does not exist, and there is no error at all

Same underlying cause, but silent. A tool your connection has no scope for is removed from the list rather than refused on call, so there is nothing for the assistant to report — it simply cannot see the capability. Look the tool up in the tables above and re-authorize with its scope.

"This connection cannot use the tool swarmtix_events_update. List the available tools to see what it is authorized for."

The name does not exist in this catalog. Editing an existing event's own details is not available through MCP yet — see the note under Safe Writes. Ask your client to list the tools rather than guessing a name.

"Event not found, or this connection does not have access to it."

Either the event does not exist, it belongs to a different organisation than this connection covers, or it belongs to a team the authorizing organizer is not on. Every tool verifies ownership before doing anything else, and every one of those cases returns this same sentence on purpose — see the note under Errors.

If the event is sitting in your dashboard, check which organisation the connection was granted, in Settings → Developers → Connections, and which account authorized it.

"Showing 50 of 1284. Call again with cursor … for the rest."

Nothing is wrong. The list was longer than one page, and the result is telling your assistant how to fetch the next 50. Ask it to continue, or narrow the request — one event rather than all of them, one date rather than every date.

Raising the page size helps up to a point: 200 is the maximum, and a result is still capped at 60,000 characters regardless.

"cursor is not valid: it was not issued by this server."

The cursor was made up, edited, or taken from a different tool. Drop it and start the list again from the beginning.

A different sentence — cursor is not valid: the <thing> it points at is no longer in this list. — means the cursor was genuine but the row it named has gone, usually because a filter changed between the two calls or the row was refunded or deactivated. Resuming from the top would silently repeat rows you already have, so the tool refuses instead. Start the list again.

"limit is not valid: it was 500. Expected a whole number from 1 to 200, or nothing for 50."

An argument was out of range or the wrong shape. The message names the parameter, what was wrong with it, and what the tool expected. Assistants usually correct this and retry on their own.

"Rate limit reached. Retry in 24 seconds."

Your organisation went past 60 requests a minute, counted across all its credentials. Wait the number of seconds given. Most clients do this without help. If it keeps happening, something is polling in a loop — check Settings → Developers → Usage to see which tool.

"Swarmtix could not complete this request. Nothing was changed."

A failure on our side. The second sentence is the useful one: nothing partly applied, so a retry will not leave you with a duplicate. If it persists, contact support with the time, so the call can be found in Settings → Developers → Logs.

A write succeeded but nothing is public

That is the expected outcome. Created events are drafts. Open the event in the dashboard, check it, and publish it yourself.