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., "@TicketSource MCP server What's on in the next two weeks?"
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.
An MCP server that lets Claude, ChatGPT and other MCP clients work with a TicketSource box office: events, performance dates, bookings, seats and customers. It is built on TicketSource's public API and its published OpenAPI spec.
Once it's connected, an organiser can ask things like:
"What's on in the next two weeks?"
"Who's booked for tomorrow's Macbeth, and how much have we taken after fees?"
"Find Sam Evans. What else has she booked this year, and are there notes on her record?"
"List everyone in row C for Friday with their booking references."
Tool | What it does | API calls |
| Events with category, published and archived status. Archived events are hidden unless requested. |
|
| One event with its venues and performance dates (upcoming only by default). |
|
| Performances across active events in the next N days, soonest first. |
|
| Bookings for one performance, with gross, net, fees, refunds and donations per booking and in total. Optionally seats and attendee names. |
|
| One booking with its totals and seats. |
|
| Search customers by name, email or phone (UK numbers match with 0 or +44). |
|
| Contact details, membership, marketing consent, staff notes and recent bookings. |
|
| Adds a staff note. Only registered when writes are enabled. |
|
Related MCP server: eventin-mcp-server
Requires Node 18 or later.
npm install
npm run buildCreate an API key in TicketSource under Settings > API.
Claude Desktop: add this to claude_desktop_config.json:
{
"mcpServers": {
"ticketsource": {
"command": "node",
"args": ["/absolute/path/to/ticketsource-mcp/dist/index.js"],
"env": { "TICKETSOURCE_API_KEY": "skl-your-key" }
}
}
}Claude Code:
claude mcp add ticketsource -e TICKETSOURCE_API_KEY=skl-your-key -- node /absolute/path/to/ticketsource-mcp/dist/index.jsVariable | Required | Meaning |
| yes | Your API key, sent as a Bearer token. |
| no |
|
| no | Defaults to |
Read-only unless TICKETSOURCE_ALLOW_WRITES=true. Read tools carry the MCP readOnlyHint annotation.
Attendee emails and phone numbers are only returned when the assistant explicitly asks for them (include_contact_details).
IDs are validated against the formats in your spec before any call is made.
Requests are spaced to stay under the 240 calls per minute limit, and 429 responses are retried using Retry-After.
A rejected API key produces a message that tells the user where to fix it.
npm testThe test suite:
Validates every fixture record against the component schemas in TicketSource's published OpenAPI spec. The spec is downloaded from github.com/ticketsource/openapi-spec to spec.yaml on the first run.
Starts a local mock of the API that serves those fixtures with JSON:API pagination, a 401 on a bad key, 404s, and a one-off 429.
Starts the built server and drives it over stdio with the official MCP client: 15 checks covering every tool, pagination, refunds and donations in totals, the 429 retry, the write gate, contact-detail redaction, and that every request used the Bearer key and a documented endpoint.
This is a working prototype. It has not yet been run against the live API, because it was built without a TicketSource account. Two things to confirm on a real account:
The body accepted by POST /customers/{id}/notes. The server sends {"data": {"type": "customer_note", "attributes": {"description": "..."}}} as documented.
The format of start on dates. It is parsed as ISO 8601; dates that can't be parsed are kept rather than dropped.
The API has no server-side customer search, so find_customers pages through the customer list (100 per call, 10 pages by default). On large accounts, a search parameter on GET /customers would make this much cheaper.
This version runs locally over stdio, with the organiser's own API key. For organisers to connect from claude.ai or ChatGPT without handling keys, the next step is a remote server (Streamable HTTP) behind OAuth, hosted by TicketSource, and then a listing in the Claude and ChatGPT connector directories.
MIT. Built by Claude, an AI model, working for Alexandru Dragoș (alexandru.dragos96@gmail.com).
Search customers by part of their name, email or phone number. The API has no server-side search, so this pages through the customer list (100 per call) up to max_pages.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Name, email or phone fragment | |
| max_pages | No | Pages of 100 customers to scan | |
| max_results | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld annotations, the description discloses a non-obvious implementation trait: there is no server-side search, so the tool pages through the customer list in chunks of 100 up to max_pages. This signals potential cost and limited scan depth. It does not explain how max_results interacts with paging, but annotations already cover the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences carry exactly the needed information: the search purpose first, then the important pagination caveat. No filler or redundant restatement of annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is mostly adequate, but max_results remains ambiguous: an agent cannot tell whether it caps returned matches after scanning or stops scanning early. Given there is no output schema, a one-sentence clarification about how max_results limits results would make the tool complete to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, with query and max_pages already described. The description adds slight value by clarifying query as a name/email/phone fragment and max_pages as scanning pages of 100 customers, but it says nothing about max_results, which has no schema description. There is a clear remaining gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence names a specific verb ('Search'), the resource ('customers'), and the matching rule ('by part of their name, email or phone number'). This clearly distinguishes find_customers from the exact-fetch sibling get_customer and from event/performance tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description communicates when to use the tool: partial-match search over customer name, email, or phone. It also explains why pagination is necessary ('The API has no server-side search'). It does not explicitly name get_customer as the alternative for exact lookups, so it lacks full sibling routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One booking with its totals, seats and attendee names, plus the customer ID.
| Name | Required | Description | Default |
|---|---|---|---|
| booking_id | Yes | Booking ID (bkg-...) | |
| include_contact_details | No | Include attendee email and phone |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds the return payload composition (totals, seats, attendee names, customer ID), which is useful. It does not disclose pagination, error behavior, or the effect of include_contact_details, but the annotations cover the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the resource and immediately states the key return fields. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with full schema coverage and readOnly/openWorld annotations, the description is nearly complete. It could mention that include_contact_details controls extra fields, but the schema already documents that parameter. The lack of an output schema is mitigated by the description listing the main return contents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds no parameter-specific meaning beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get a booking') and adds what the response includes: totals, seats, attendee names, and customer ID. It is clear enough to distinguish from siblings like get_performance_bookings, though it does not explicitly name the sibling it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a single-booking lookup by ID, which is clear context. It does not explicitly state when to use this tool versus alternatives like get_performance_bookings or list_events, nor does it mention exclusions. The sibling list provides some context, but the description itself offers no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A customer's contact details, membership and marketing consent, with their staff notes and most recent bookings.
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | Customer ID (cst-...) | |
| max_bookings | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds that it returns 'most recent bookings' but does not disclose that the max_bookings parameter controls the count or its default/range. This is a partial disclosure beyond annotations but leaves a gap in behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that front-loads the key content. No unnecessary words or repetition. It is efficient and readable, though it lacks a verb at the start.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only get operation with two parameters, the description is fairly complete in listing returned data, but it does not explain the effect of max_bookings (e.g., it limits the number of bookings returned, default 20, max 200). Since there is no output schema, this missing linkage is a notable gap that an agent would need to discover elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only customer_id has a description). The description mentions 'most recent bookings', which implicitly ties to the max_bookings parameter, giving it meaning beyond the bare schema (type, default, range). This partially compensates for the missing schema description, though it could be more explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what data is returned (contact details, membership, marketing consent, staff notes, recent bookings), which distinguishes it from siblings like find_customers (search) and get_booking (single booking). However, it lacks an explicit verb like 'retrieve' or 'fetch', relying on the name and title for the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not state that it is for fetching a single customer by ID, nor does it mention that find_customers is for searching. An agent must infer the appropriate use case from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one event with its venues and performance dates. By default only dates from today onwards are returned.
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes | Event ID (evt-...) | |
| upcoming_only | No | Only return dates from today onwards |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and openWorldHint=true, covering safety and schema extensibility. The description adds a valuable behavioral detail—the default filtering to dates from today onwards—which goes beyond the schema's default value by explaining the default behavior. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. The core purpose is front-loaded, and the behavioral default is stated in the second sentence. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two parameters and no output schema, the description covers the essential purpose, return contents, and a key default behavior. Nothing critical is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are fully documented in the input schema. The description adds minimal semantic value beyond reinforcing the upcoming_only default via the sentence about dates from today. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('get') and a precise resource ('one event with its venues and performance dates'), which clearly distinguishes it from list_events (plural) and list_upcoming_performances (performances only). The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates use for retrieving a single event (as opposed to listing), but it does not explicitly name alternatives or conditions for choosing this over sibling tools like list_events. No exclusions are provided, leaving the agent to infer based on the word 'one'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who is coming to one performance date: every booking with totals (gross, net, fees, refunds, donations) and an overall summary. Set include_attendees to also list seats and attendee names.
| Name | Required | Description | Default |
|---|---|---|---|
| date_id | Yes | Performance date ID (dat-...) | |
| max_bookings | No | ||
| include_attendees | No | Also fetch seats and attendee names (one extra call per booking, capped at 60 bookings) | |
| include_contact_details | No | Include attendee email and phone (only with include_attendees) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description is not required to restate safety. It adds behavioral context by describing the returned data (totals, summary) and the optional attendee expansion, which goes beyond the annotations. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff, front-loaded with the primary purpose and a clear optional parameter note. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description adequately conveys the return shape (bookings with totals and summary) and the optional include_attendees behavior. It omits include_contact_details and max_bookings, but these are optional and likely inferable from the schema. The overall purpose is well-covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75% (3 of 4 params documented), but the description only mentions include_attendees, duplicating the schema text. It does not clarify max_bookings, which lacks a schema description, leaving a gap for the agent. The description fails to compensate for the uncovered parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource: 'Who is coming to one performance date' and enumerates the output ('every booking with totals... and an overall summary'). This distinguishes it from siblings like get_booking (single booking) and list_upcoming_performances (future events).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes a clear context ('one performance date') and gives a usage hint for the include_attendees flag, but does not explicitly state when to prefer this tool over alternatives like get_booking. It provides enough context to infer the right use case without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the events on this TicketSource account (name, category, published and archived status). Archived events are skipped unless asked for.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of events to return | |
| include_archived | No | Include archived events |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal a read-only, open-world call; the description adds the non-obvious default that archived events are skipped unless include_archived is set. It also clarifies the published/archived status fields returned. This is consistent with the annotations and adds useful behavior beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with the main action first and the key filtering caveat second. No filler or repetition of schema defaults.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity read-only list with no required parameters and no output schema, the description covers the essential behavior and returned fields. It does not explain the relationship to list_upcoming_performances, so an agent might not know when this is the right list call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are already fully described in the schema, with limit range/default and include_archived boolean/default, and schema coverage is 100%. The description's archived-skipped sentence corroborates the include_archived default but adds no new parameter syntax or format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete operation ('List the events') against a specific resource ('this TicketSource account') and enumerates returned fields. It does not explicitly distinguish itself from sibling list_upcoming_performances, so it stops short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement about when to choose this tool over list_upcoming_performances, get_event, or the other siblings. The 'unless asked for' clause explains the archived filter but not selection criteria. This leaves the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What's on: performance dates across all active events in the next N days, soonest first, with the event name. Use the returned dat- id with get_performance_bookings.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| days_ahead | No | How many days ahead to look | |
| include_cancelled | No | Include cancelled performances |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows it's a safe read operation. The description adds behavioral context beyond the annotations: it specifies the scope ('across all active events'), the ordering ('soonest first'), and that it returns the event name. It also hints at a returned ID for subsequent calls. This adds useful behavior details without contradicting the annotations. The typo 'dat- id' slightly detracts but does not affect transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the primary purpose front-loaded in the first sentence. The second sentence provides a practical usage hint. It is concise and informative, though the typo 'dat- id' slightly reduces polish. Overall, it is appropriately sized and structured, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with three optional parameters and no output schema, the description provides sufficient context: it indicates the output includes performance dates and event names, the ordering, and hints at an ID for further actions. It does not explicitly list all return fields or describe edge cases (e.g., empty results, pagination), but given the tool's simplicity and the annotations covering safety, the description is reasonably complete. The mention of using the returned ID with get_performance_bookings is a valuable contextual detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for days_ahead ('How many days ahead to look') and include_cancelled ('Include cancelled performances'), but limit lacks a description. The tool description adds minimal parameter meaning: 'in the next N days' implies the days_ahead parameter, and the mention of 'active events' indirectly relates to include_cancelled (since cancelled performances might be excluded by default). However, it does not explain the limit parameter or clarify how include_cancelled behaves beyond the schema. Given moderate schema coverage (67%), the description adds some value but does not fully compensate for the missing limit description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists performance dates across all active events within a given number of days, sorted soonest first, and includes the event name. It specifies the resource (performances) and the scope (across all active events), which distinguishes it from sibling tools like list_events (which lists events) and get_performance_bookings (which targets a specific performance). The verb 'list' is concrete and the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear follow-up action: 'Use the returned dat- id with get_performance_bookings.' This hints at the typical workflow, implying the tool is a precursor to fetching bookings for a specific performance. However, it does not explicitly state when to choose this tool over alternatives like list_events or when not to use it. Still, the usage context is reasonably conveyed through the explicit follow-up hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0find_customersget_bookingget_customerget_eventget_performance_bookingslist_eventslist_upcoming_performancesScored across 7 tools
Each tool targets a distinct resource and action: events, performances, bookings, and customers are clearly separated. Even list_events and list_upcoming_performances differ in scope (all events vs. upcoming performance dates), eliminating ambiguity.
All tools follow the consistent verb_noun pattern in snake_case (list_*, get_*, find_*). The naming is uniform and predictable, with no mixed conventions or vague verbs.
Seven tools is well-scoped for a read-only ticketing information server. Each tool has a clear purpose and the count falls comfortably in the ideal 3-15 range.
The surface covers core retrieval workflows: events, performances, bookings, and customers. Minor gaps exist (e.g., no create/update operations, no direct booking-by-event search), but these align with a read-only information source and do not block typical usage.
Talk to your live-events CRM (campaigns, analytics, paid ads, segments) in Claude and ChatGPT.
Let AI agents query data and act across all your business apps via MCP.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
