XP MCP Documentation — Public (anonymous)

Back to landing

Overview — mode: `public`

XP MCP exposes event discovery, ticket listing, and marketplace actions for AI agents over Streamable HTTP.

Search events and venues, then inspect details and ticket listings.
Create price alerts and manage authenticated marketplace offer flows.
Use widgets/resources for richer host rendering where supported.

Connection Details

Endpoint: POST http://mcp-store.xp.tickets/mcp (Public (anonymous))
Transport: Streamable HTTP / SSE. Auth posture is set per deploy via MCP_AUTH_REQUIRED.
Auth: OAuth 2.1 + PKCE (S256) when gated. MCP clients identify themselves via OpenID Connect Discovery, Dynamic Client Registration, or a Client Identifier Metadata Document (CIMD).
Auth-error contract: tools may return error_code: "AUTH_REQUIRED" or "SESSION_EXPIRED" — clients should reconnect / re-authorise XP.
Health check: GET /health
Privacy policy: https://xp-metadata.s3.amazonaws.com/privacy-policy.pdf
Support: support@xp.tickets

Client config — start here

Drop these into the matching MCP host config to connect.

Claude (web + desktop)

Settings > Integrations > Add custom connector. Paste the URL; Claude completes the OAuth handshake on first protected call.

Public read-only

http://mcp-store.xp.tickets/mcp

Cursor

// ~/.cursor/mcp.json — Cursor reads this on launch.
{
  "mcpServers": {
    "xp": {
      "url": "http://mcp-store.xp.tickets/mcp"
    }
  }
}

ChatGPT

Apps SDK / custom connector. ChatGPT triggers OAuth automatically off the 401 + WWW-Authenticate challenge.

Public read-only

http://mcp-store.xp.tickets/mcp

VS Code (Copilot Chat)

// VS Code (Copilot Chat) — settings.json or .vscode/mcp.json
{
  "mcp": {
    "servers": {
      "xp": {
        "type": "http",
        "url": "http://mcp-store.xp.tickets/mcp"
      }
    }
  }
}

Quickstart (cURL)

Copy-paste recipes. Keep $SESSION = the Mcp-Session-Id response header from initialize; reuse it on every follow-up call in the same session.

Public — anonymous, open-world only

# 1. Open a session. Server returns ``Mcp-Session-Id`` header.
curl -i -X POST http://mcp-store.xp.tickets/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"demo","version":"1.0"}}}'

# 2. List visible tools (open-world only).
curl -X POST http://mcp-store.xp.tickets/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Call an open-world tool. No bearer required.
curl -X POST http://mcp-store.xp.tickets/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_events","arguments":{"query":"taylor swift"}}}'

Streamable HTTP rules: every request must include Accept: application/json, text/event-stream. Capture the Mcp-Session-Id response header from initialize and echo it on every subsequent call in the same session.

Conventions and gotchas

Money units

USD inputs are integer cents (5000 = $50.00). Multiply dollars by 100. Applies to: get_ticket_listings.min_price_cents/max_price_cents, make_offer_on_listing.amount_cents, create_price_alert.max_price_cents, get_price_alert_link.max_price_cents.
USDC amounts are 6-decimal raw units (4_000_000 = $4.00). Multiply dollars by 1_000_000. Applies to list_open_listings.min_amount/max_amount and response amount_raw fields.
Display fields (amount_display, *_usd) are human-readable strings — never re-parse.

Dates and timezones

For relative dates ("this weekend", "next month"), anchor on _meta.context.today from the most recent tool response instead of guessing. _meta.context.tz_offset is the server's UTC offset; resolve against the user's timezone when known.

Public (anonymous) — 9 tools, 7 prompts, 8 docs, 6 widgets

Anonymous callers can initialize and call any open-world tool. authenticated and Waitlist Approval tools are not part of this surface.

WWW-Authenticate / PRM: http://mcp-store.xp.tickets/.well-known/oauth-protected-resource/mcp

Tools

Tool	Name	Description	Auth required	Mode
`auth_status`	Auth Status	Use ONLY when the user explicitly asks whether they are signed in to the XP marketplace (e.g. 'am I logged in?', 'am I connected to my tickets?'), or after a protected tool already returned AUTH_REQUIRED and the user wants the current state re-checked. Do NOT call this as a preflight before account / my tickets / wallet / favorites / referral / price alert tools — calling auth_status first swallows the 401 those tools would emit on the connected order book and prevents the MCP client from triggering OAuth. Always call the requested protected tool directly; the client will start sign-in on 401. Read-only. Returns authenticated boolean, tier roles, and a wallet flag — never raw tokens.	No	Read
`get_event_details`	Get Event Details	Use when an event ID is in hand and the user wants the full event card before browsing tickets to that event — venue, performers, fee-inclusive price preview, images. Pulls from the XP marketplace catalog. Cache the result for the conversation rather than re-calling for the same event_id. Do not use to list ticket inventory; `get_ticket_listings` is the right tool for seat-level data.	No	Read
`get_price_alert_link`	Get Price Alert Link	Generate a link for the user to set up an instant price alert on an event in the XP marketplace. Use when the user says 'let me know when prices drop', 'I'm watching this', 'tell me if seats go below $X', 'waiting for a deal', or any signal that they want to be notified rather than buying right now. Instant price alerts are one of XP's core differentiators on the connected order book, so suggest one proactively when a user balks at current pricing. Safe before the user is signed in. When the user is already authenticated, prefer `create_price_alert` to make the alert directly. Do not use when the user is ready to buy now; `get_ticket_listings` is the next step.	No	Read
`get_ticket_listings`	Get Ticket Listings	Use when the user wants to see ticket options and fee-inclusive prices for a specific XP event after `search_events` (e.g. 'cheap seats', 'parking for the game'). Pulls the live offer book of resale + primary inventory. Do not use before an event has been resolved — call `search_events` or `get_event_details` first. Prices are integer cents.	No	Read
`get_venue_details`	Get Venue Details	Pull full venue info from XP plus the upcoming-events calendar at that venue, with live pricing from the connected order book of resale + primary inventory. Use after `search_venues`, or when the user asks 'what's coming up at the venue', 'what's playing at the Garden', 'shows at the venue this month'. Returns the upcoming-events feed so the agent can offer next-step `get_ticket_listings` calls. Do not use to fetch ticket inventory for a specific event; `get_ticket_listings` is the right tool for seat-level data.	No	Read
`list_price_alert_sections`	List Price Alert Sections	List the section raw_ids and human labels that `create_price_alert` will accept for a specific event. Call before `create_price_alert` so the alert targets a real section. Use when the user wants a section-specific price alert (e.g. 'price drop on lower bowl', 'lower bowl alert only'). Returns the section catalog from the XP marketplace ticket_sections table. Pass returned raw_id values straight through; do not invent section ids. Do not show the raw section IDs to the user; use the human labels in conversation.	No	Read
`search_events`	Search Events	Use when the user wants to find live events on XP — concerts, sports, theater — by performer, team, venue, city, or keyword (e.g. 'tickets to the season opener', 'shows near me this weekend'). Surfaces the connected order book of resale + primary inventory in one feed. Do not use for scores, news, standings, or non-ticketed listings; use a web tool for those.	No	Read
`search_performers`	Search Performers	Find a performer (artist, team, comedian) on the XP marketplace by name. Use when the user names a specific performer (e.g. 'tickets to Taylor Swift', 'Lakers season opener', 'Phish tour dates'). Returns performer cards from the XP catalog — not events. Pair with `search_events` once a performer is selected to surface their upcoming events on the connected order book. Do not use for general 'events near me' queries; `search_events` handles those better.	No	Read
`search_venues`	Search Venues	Use when the user wants to find a venue by name, city, or area on XP (e.g. 'venues near me', 'arenas in Brooklyn', 'what's at the venue level downtown'). Returns venue records from the XP marketplace catalog — not tickets. Do not use to answer ticket-price questions once the event is known; call `get_ticket_listings` instead.	No	Read

Prompts

Prompt	Category
`event_with_price_alert`	`open_world`
`find_tickets_by_section_and_budget`	`open_world`
`floor_and_vip_options`	`open_world`
`ga_vs_seated_tradeoff`	`open_world`
`parking_for_event`	`open_world`
`venue_events_and_tickets`	`open_world`
`weekend_deals_near_me`	`open_world`

Documentation resources — text://

URI	Name	Description
`text://instructions/ticket-agent`	Ticket Agent Instructions	Operational instructions for the ticket agent.
`text://instructions/ticket-verification`	Ticket Verification Instructions	Operational instructions for ticket verification mode.
`text://about/xp`	About XP	What XP is, what makes it different (connected order book, all-in pricing, price alerts, Quality XPerience Guarantee), when to use XP, and the voice the agent should adopt with users.
`text://about/catalog`	XP Catalog Coverage	High-level view of XP catalog: sports leagues, music genres, geographies, and primary/partner inventory sources.
`text://help/comparison`	XP vs Alternatives	Guidance for when an agent should route a user to XP vs the primary box office vs other secondary marketplaces.
`text://context/now`	Server Time Context	Authoritative server clock as JSON ({today, now_utc, tz_offset}); use for relative-date resolution and freshness checks. tz_offset shows the server UTC offset so agents can adjust to the user's timezone. Same source as _meta.context on every tool envelope.

Documentation resources — skill://

URI	Name	Description
`skill://instructions/ticket-agent`	Ticket Agent skill	Same markdown as text://instructions/ticket-agent; use this URI when the client surfaces skill-scoped resources.
`skill://about/xp`	About XP skill	Skill-loadable context on what XP is, the connected order book of resale + primary tickets, all-in pricing, price alerts, and the Quality XPerience Guarantee.

Widget resources

Patterns: ui://widget/{widget}.html, ui://widget/{widget}

Widget	Primary URI (.html)	Alias URI
`event-card`	`ui://widget/event-card.html`	`ui://widget/event-card`
`event-cards`	`ui://widget/event-cards.html`	`ui://widget/event-cards`
`search-results`	`ui://widget/search-results.html`	`ui://widget/search-results`
`ticket-carousel`	`ui://widget/ticket-carousel.html`	`ui://widget/ticket-carousel`
`venue-card`	`ui://widget/venue-card.html`	`ui://widget/venue-card`
`venue-cards`	`ui://widget/venue-cards.html`	`ui://widget/venue-cards`