--- title: "Ticket Fairy for AI Agents | MCP, A2A, NLWeb, WebMCP and Skills" description: "Connect an AI agent to live events, the how-to guides and ticket checkout. MCP servers, Agent2Agent, NLWeb, WebMCP, agent skills, Markdown pages and discovery files." canonical: "https://www.ticketfairy.com/developers/ai-agents" --- Ticket Fairy developer documentation # Connect any AI agent to Ticket Fairy Let an AI agent find live events, answer questions from the guides, buy tickets for a person or manage an organizer's events. This page lists every way an agent connects, with the address and limits of each. [Add the MCP servers](#mcp) [See the discovery files](#documents) Searching events and reading the guides need no account or key. Your AI client's config ``` { "mcpServers": { "ticketfairy-events": { "type": "http", "url": "https://www.ticketfairy.com/agentic/mcp" }, "ticketfairy-docs": { "type": "http", "url": "https://www.ticketfairy.com/docs/mcp" } } } ``` Both servers are hosted by Ticket Fairy. Nothing to install. ## Choose how your agent connects Start from what your agent needs to do. | What your agent does | What to use | Credential | | --- | --- | --- | | [Find events for a person](https://www.ticketfairy.com/developers#public-api) | The events MCP server, Agent2Agent, NLWeb or the event API | None | | [Answer how-to questions about Ticket Fairy](#mcp) | The guides MCP server | None | | [Buy tickets for a person](https://www.ticketfairy.com/developers/agent-checkout) | Agent checkout with the Agentic Commerce Protocol or the Universal Commerce Protocol | A buyer key your agent registers for itself, or its signed UCP profile | | [Act for an organizer](https://www.ticketfairy.com/developers/authentication) | The hosted organizer MCP server, the Ticket Fairy CLI and its MCP server, or the organizer API | A sign-in or a token the person approves | | [Sign up a new organizer](https://www.ticketfairy.com/developers/organiser-api#onboarding) | A guest event draft handoff, or the organizer onboarding API | None for a draft; an application credential for onboarding | ## MCP servers Ticket Fairy hosts two read-only Model Context Protocol servers for everyone and an organizer server that acts for a signed-in organizer, all over Streamable HTTP. The Ticket Fairy CLI includes a local server too. | Server | Address | Tools | Credential and limits | | --- | --- | --- | --- | | Events | `https://www.ticketfairy.com/agentic/mcp` | search\_events, get\_event, ask\_events | None. Each client address can send 120 requests a minute. | | Guides | `https://www.ticketfairy.com/docs/mcp` | search\_guides, get\_guide | None. Each client address can send 120 requests a minute. | | Organizer | `Listed in the official MCP registry` | The organizer tools that Fai uses: events, ticket types, orders, reports, promotions, team and more | The person signs in to Ticket Fairy and approves the assistant. It can do only what their team role allows. | | Your own account | `ticketfairy mcp, on your own computer` | Events, ticket types, orders, customers, promotions, check-in, webhooks, team and more | Your Ticket Fairy sign-in, through the CLI. | ### Events server `search_events` finds live public events by words, place and date. `get_event` reads one event from its link, and `ask_events` answers a question in plain language. Every tool is marked read-only and safe to repeat. In clients that support MCP Apps, the results show as event cards from the view at `ui://ticket-fairy/event-results.html`, the one resource the server lists. The server speaks protocol version 2025-11-25 and 2025-06-18. Call a tool without an MCP client ``` $ curl 'https://www.ticketfairy.com/agentic/mcp' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "search_events", "arguments": {"search": "jazz"}}}' ``` ### Guides server `search_guides` finds the [how-to guides](https://www.ticketfairy.com/guides) for a task, and `get_guide` reads one guide as plain text: who it is for, what to have ready, every step and the common questions. Use it to answer "how do I ... on Ticket Fairy?" from the published guides. ### Organizer server The organizer server at `https://www.theticketfairy.com/agentic/organizer/mcp` has the tools of the MCP server in the Ticket Fairy CLI for reading and changing events, tickets, orders and the team. The organizer adds that address, or adds the server from the official MCP registry, and signs in to Ticket Fairy in the browser. The assistant connects with OAuth, PKCE and a Client ID Metadata Document, so there is nothing to register. It acts as that organizer and can do only what their team role allows. A tool that changes something needs `confirm: true`. Refunds, deletions, sends and other actions that cannot be undone are not on this server: the organizer does them in the Ticket Fairy dashboard. ### Your own account, from the CLI An organizer can also run the [MCP server in the Ticket Fairy CLI](https://www.ticketfairy.com/mcp-server). It runs on their own computer, signs in as them and can start in a read-only mode. ### Registries The hosted servers are named `com.ticketfairy/organizer`, `com.ticketfairy/ticket-fairy-public-events` and `com.ticketfairy/ticket-fairy-docs` in their server cards. The servers are listed in the official MCP registry, and the events server is also on [Smithery](https://smithery.ai/servers/ticketfairy). ## Agent2Agent and A2UI Another agent can ask Ticket Fairy for events over the Agent2Agent protocol. It needs no credential. The [agent card](https://www.ticketfairy.com/.well-known/agent-card.json) describes the endpoint at `https://www.ticketfairy.com/agentic/a2a` and its one skill, `search_events`. Send a `SendMessage` request over JSON-RPC with what the person is looking for. When your agent declares the A2UI extension and accepts the A2UI media type in `acceptedOutputModes`, the answer also carries the results as A2UI event cards that your interface can draw, with an `open_event` action on each. ## NLWeb `https://www.ticketfairy.com/ask` answers a question about upcoming events as JSON or as a Server-Sent Events stream. The [developer documentation](https://www.ticketfairy.com/developers#nlweb) shows a request and a streamed answer. ## WebMCP in the browser When a browser agent opens a Ticket Fairy page, the page offers it tools through WebMCP, so the agent does not have to read the screen and guess where to click. | Tool | Pages | What it does | | --- | --- | --- | | `search_events` | The homepage, event pages and event search | Searches live public events, with the same results as the events MCP server. | | `read_ticket_checkout` | Ticket selection and checkout | Reads the checkout the person has open: tickets, fields, totals and the actions available. | | `enter_ticket_checkout_field` | Ticket selection and checkout | Enters a value in one checkout field, such as a ticket quantity or the buyer's name. | | `activate_ticket_checkout_action` | Ticket selection and checkout | Presses one checkout button. The tool is marked as consequential, so a browser that supports it can ask the person first. Controls such as the terms and marketing consent can be pressed only by the person. | The checkout tools work on the hosted checkout. On an organizer's own website, they are registered inside the embedded checkout frame, so an agent reaches them only where the browser gives it the frame's tools. The person still pays in their browser. ## Agent skills and plugins Skills are ready-made instructions that teach an agent one job on Ticket Fairy, such as finding tickets, connecting an organizer account or managing orders and refunds. ### Install the skills The [Ticket Fairy agent skills repository](https://github.com/theticketfairy/agent-skills) on GitHub holds one skill for each area of the guides, the organizer and buyer skills, and an AGENTS.md file for coding agents such as Claude Code, Cursor and Codex. Terminal ``` $ npx skills add theticketfairy/agent-skills ``` ### Add them to Claude Code as a plugin Claude Code ``` /plugin marketplace add theticketfairy/agent-skills /plugin install ticketfairy@ticketfairy ``` ### Read them from the website The same skills are published at [/.well-known/agent-skills/index.json](https://www.ticketfairy.com/.well-known/agent-skills/index.json), in the Agent Skills discovery format, each with the digest of its file. ## Read any page as Markdown Every page that Ticket Fairy renders on the server is also available as Markdown, which costs an agent far fewer tokens than the HTML. - Send `Accept: text/markdown` with the request. - Or add `.md` to the address, for example `/developers.md`. - Known AI crawlers and assistants get Markdown without asking. Terminal ``` $ curl -H 'Accept: text/markdown' 'https://www.ticketfairy.com/developers' ``` Each Markdown page starts with its title, description and canonical address. An HTML page names its Markdown version in a `Link` header. An address that does not exist answers with a short Markdown page that links to the homepage and llms.txt. ## Discovery files An agent that starts at the domain finds every capability from these files. - [`AI catalog`](https://www.ticketfairy.com/.well-known/ai-catalog.json) The Agentic Resource Discovery manifest of the main agent resources: the MCP servers and their cards, including the organizer server, the A2A card, the OpenAPI description, the commerce profiles, organizer onboarding, llms.txt and the organizer signup skill, each with its trust identity. The same file is at /.well-known/ard.json. - [`Events MCP server card`](https://www.ticketfairy.com/.well-known/mcp/server-card.json) The events MCP server, its tools and its event cards view. The server's own card is at /agentic/mcp/server-card. - [`Guides MCP server card`](https://www.ticketfairy.com/docs/mcp/server-card) The guides MCP server and its two tools. - [`A2A agent card`](https://www.ticketfairy.com/.well-known/agent-card.json) The Agent2Agent endpoint, its event search skill and the A2UI extension. - [`Agent skills index`](https://www.ticketfairy.com/.well-known/agent-skills/index.json) Every published skill with the SHA-256 digest of its file. - [`API catalog`](https://www.ticketfairy.com/.well-known/api-catalog) The RFC 9727 list of the APIs this site serves. - [`OpenAPI description`](https://www.ticketfairy.com/api/v1/openapi.json) The public event API, in OpenAPI 3.1. - [`auth.md`](https://www.ticketfairy.com/auth.md) How an agent gets a credential, step by step. - [`OAuth protected resource metadata`](https://www.ticketfairy.com/.well-known/oauth-protected-resource) The API, its authorization server and its scopes (RFC 9728). - [`OAuth authorization server metadata`](https://www.ticketfairy.com/.well-known/oauth-authorization-server) The sign-in, token and agent approval endpoints (RFC 8414). - [`Commerce profile (UCP)`](https://www.ticketfairy.com/.well-known/ucp) The Universal Commerce Protocol profile for ticket checkout. - [`Commerce profile (ACP)`](https://www.ticketfairy.com/.well-known/acp.json) The Agentic Commerce Protocol profile for ticket checkout. - [`llms.txt`](https://www.ticketfairy.com/llms.txt) A short index of the platform for language models. - [`llms-full.txt`](https://www.ticketfairy.com/llms-full.txt) The same index with every product area described. - [`Developer llms.txt`](https://www.ticketfairy.com/developers/llms.txt) The developer documents and agent protocols only. - [`API llms.txt`](https://www.ticketfairy.com/api/llms.txt) The REST APIs only. - [`pricing.md`](https://www.ticketfairy.com/pricing.md) The published pricing as one Markdown document. - [`NLWeb schema map`](https://www.ticketfairy.com/schemamap.xml) The structured-data feeds this site publishes. - [`Agent view of the homepage`](https://www.ticketfairy.com/?mode=agent) The API, authentication and capabilities on one page. Add &format=json for JSON. - [`Web Bot Auth key directory`](https://www.ticketfairy.com/.well-known/http-message-signatures-directory) The public keys that sign the requests Ticket Fairy sends. - [`robots.txt`](https://www.ticketfairy.com/robots.txt) The crawler rules, with the Agentmap and schemamap lines and the Content-Signal policy. ## Signed requests Webhook deliveries from Ticket Fairy to an HTTPS address carry an HTTP Message Signature (Web Bot Auth) made with an Ed25519 key, unless the webhook sends its own signature headers. To check that a request came from Ticket Fairy, read the key from the [key directory](https://www.ticketfairy.com/.well-known/http-message-signatures-directory) and verify the signature over the method, host, path and `Signature-Agent` header. The signature does not cover the body, and it is valid for at most five minutes. ### Requests your agent signs Your agent can sign its own requests the same way, with a `Signature-Agent` header that names your key directory. Ticket Fairy verifies the signature, records which agent made the request and, on the guest event draft and handoff requests, applies rate limits for your agent instead of for its network. A UCP agent can use this signature mode for its checkout requests. A signature identifies your agent; it does not give it more access. ## Questions about connecting an agent ### Do I need an account to connect an agent? No, not to search events, read the guides or ask questions. The events MCP server, the guides MCP server, Agent2Agent, NLWeb and the event API need no account or key. An agent needs a credential only to buy tickets or to act for an organizer. ### Which MCP server should I add? Add the events server to find events and send people to buy tickets. Add the guides server to answer questions about how to use Ticket Fairy. Organizers who want their assistant to manage their own events add the hosted organizer server from the official MCP registry and sign in, or use the MCP server in the Ticket Fairy CLI on their own computer. ### Can an agent change an event or an order without the organizer knowing? No. The events and guides servers only read. Changes go through the organizer server, the CLI or the organizer API, each with a sign-in or credential that the organizer approves, and each can do only what the organizer's team role allows. ### What happens when I go over a limit? The answer is 429 with a Retry-After header. Wait that many seconds, then send the request again. The MCP servers and NLWeb also send RateLimit-Policy and RateLimit headers on every answer, so you can slow down before you reach the limit. Ticket Fairy in full: [event ticketing platform](https://www.ticketfairy.com/event-ticketing/), with the features, pricing and support behind this page. ## Further Reading [**MCP server for your account** Let the AI assistant you use manage your own events.](https://www.ticketfairy.com/mcp-server) [**Agent checkout** Let a shopping agent sell tickets over ACP or UCP.](https://www.ticketfairy.com/developers/agent-checkout) [**Authentication** Personal Access Tokens, agent approval and OAuth.](https://www.ticketfairy.com/developers/authentication) ## Questions about connecting an agent? Email [support@theticketfairy.com](mailto:support@theticketfairy.com) with the request you sent and the answer you got. [Get a credential](https://www.ticketfairy.com/developers/authentication) [Read the organizer API](https://www.ticketfairy.com/developers/organiser-api) --- This page is on Ticket Fairy, a ticketing, marketing and operations platform for live events and the venues that host them: festivals, club nights, concerts, conferences and tours, and night clubs, beach clubs and concert venues. It grows revenue with fan rewards that turn an audience into a sales channel, and runs the money side with payments and payouts, Vault business banking, and working capital advanced against ticket sales. [How Ticket Fairy ticketing works](https://www.ticketfairy.com/event-ticketing) ยท [Ticket Fairy for AI assistants](https://www.ticketfairy.com/llms.txt)