Agentic Ventures Wiki

ticketpay

3 Min. Lesezeit

TicketPAY MCP

Eigener MCP-Server unter mcp-ticketpay. Read-only Zugriff auf TicketPAY Export-API (Base: https://tnapi.ticketpay.de).

Zweck: Vibe Factory. TicketPAY-Daten (Events, Orders, Tickets, Zahlungen) fuer Agent-Workflows und Reporting zugaenglich.

Tools (14 + Escape)

Umsatz & Zahlungen

  • list_orders → /exports/shop/orders (Quirk: /shop/ im Pfad — siehe unten)
  • list_transactions → /exports/transactions
  • list_cancellations, list_fees, list_donations

Events & Tickets

  • list_events, list_tickets, list_vouchers, list_event_campaigns, list_sold_articles (ein Wort)

Stammdaten

  • list_products, list_shops, list_employees, list_api_keys (Quirk: /api-key)

Escape: raw_get(path, params?)

Auth

TicketPAY erwartet API-Key im Authorization-Header ohne Bearer-Prefix — nur der Key-String. HTTPS-only.

Setup

cd ~/source/mcps/mcp-ticketpay
cp .env.local.example .env.local
# TICKETPAY_API_KEY=<key>
uv tool install --force --editable .
claude mcp add ticketpay -- ~/source/mcps/mcp-ticketpay/start.sh
# oder HTTP via http://127.0.0.1:8766/mcp

API-Key beim Kunden im TicketPAY-Backend anlegen (URL: https://<shop>.ticketpay.de/backend → API-Key-Management).

Quirks & Stolperfallen (sehr wichtig)

  • Auto-Compact bei Response > 50KB (eingebaut 2026-05-03 nach Andre-Live-Test): Tool-Output wird automatisch kompaktiert wenn JSON > 50 KB. Items werden auf Top-Level-Primitives + ID/Status-Felder reduziert (id, status, event_id, amount_cents, created_iso, ...), nested Dicts/Lists gedroppt, Strings > 200 Zeichen gecaped. Markiert mit _truncated: true. Hintergrund: TicketPAY-Tickets enthalten pro Item Personalisierungs-Daten + Adressen → 5 Tickets schnell 2 MB → Anthropic-Tool-Output-Limit ueberschritten. Volle Detail-Sicht: kleineres size= oder raw_get mit Field-Selection.

  • Filter-Params direkt in den Volumen-Tools (eingebaut 2026-05-03): list_tickets, list_transactions, list_fees, list_donations, list_sold_articles akzeptieren from_, to, filter_by (Default created_iso — fuer „wann gekauft”, nicht „wann zuletzt geaendert”), event_id, shop_id, status (bei list_fees: fee_type). Plus zwei Token-Spar-Modi: count_only=True returnt nur {total, page, size}; fields=["created_iso","price","status"] reduziert Items clientseitig. Hintergrund Q1-Vergleich am 2026-05-03: 6× ~1.5 MB pro Monatsblock nur um total rauszufischen — mit count_only jetzt 6× ~50 Bytes.

  • Authorization-Header ohne Bearer-Prefix — nur der rohe Key. Abweichend von OAuth-Standards.

  • /exports/shop/orders statt /exports/orders. Im MCP versteckt hinter list_orders.

  • page_size=1000 loest sporadisch 502 Bad Gateway aus (Lessons Learned 2026-04-25). Vermutlich Cloud-Frontend-Throttle bei Backend-Druck. Stabil ist page_size=500 und kleiner. Doku schweigt zu Limits.

  • total: 10000 Hard-Cap auf Volumen-Endpoints ohne Filter. Wer Tickets/Transactions/Fees ohne from/to zieht, bekommt nie mehr als 10.000 Records. Workaround: Date-Slicing in Monatsblöcken. Bei VF dadurch von 10k gecapt auf 38.501 Tickets, 13.452 Transactions, 68.265 Fees.

  • page_size-Parameter wird teilweise ignoriert — Server liefert oft 1000 obwohl 200 angefragt. Pagination-Stop nicht auf len(items) == requested_page_size aufbauen.

  • list_orders liefert {"errormessage": "Unknown index"} (re-verifiziert 2026-04-25). Sowohl mit size=100 als auch size=1000 reproduzierbar. Sieht nach server-seitig fehlendem Index aus, nicht Auth/Param. Workaround: Order-Daten ueber tp_transactions + tp_tickets rekonstruieren oder TicketPAY-Support fragen.

  • Sortier-Default ohne Filter ist chronologisch aufsteigend (aelteste zuerst). list_tickets(page=1) liefert Tickets aus Account-Historie (bei VF: April 2019). Wer „aktuelle Tickets” will und nur das 10k-Cap nutzt, landet maximal in der Mitte. Konsequenz: Fuer aktuelle Sicht ist Date-Filter (from/to + filter_by=created_iso) Pflicht, auch unterhalb des Caps. Sortier-Reverse-Param ist nicht dokumentiert.

  • Keine POST/PUT/DELETE — Export-API ist strikt read-only. Schreibendes muss ueber TicketPAY-Backend laufen.

Erweiterungen wenn gebraucht

  • CSV-Export: laut Doku liefern einige Endpoints .csv wenn Pfad entsprechend endet — bei Bedarf separates Tool ergaenzen.
  • Preregistration-API: derzeit nur via raw_get. Wenn haeufig genutzt → eigene Tools.

Graphansicht

Backlinks