Skip to main content
Was this helpful?

MCP Reservations Best Practices v2

Use reservations v2 as a two-step workflow: ask for bounded availability first, then create with the smallest set of fields needed for booking.

  1. Call primecal_reservations_availability_list_v2 with a narrow from / to window.
  2. Pick a slot from the returned UTC timestamps.
  3. Call primecal_reservations_create_v2.
  4. If PrimeCal returns RESERVATION_CONFLICT, retry with nextAvailableSlot.
  5. If PrimeCal returns PAYMENT_REQUIRED, hand the workflow off to a payment-capable channel.

Availability Patterns​

  • Prefer from / to when the agent already reasons in UTC.
  • Prefer date plus userTimezone when the user says things like “tomorrow morning in Budapest”.
  • Keep windows small. One day is the default and usually enough.

Conflict Handling​

  • Treat conflictingReservationId as diagnostic metadata, not as a retry target.
  • Use nextAvailableSlot directly when it is present.
  • Re-run availability if the agent needs more context before retrying.

Payment Handling​

  • Do not retry PAYMENT_REQUIRED blindly.
  • Surface paymentRequiredAmount and currency to the user or the calling orchestrator.
  • Keep MCP reservation create for free or internally-authorized booking flows.

Coordinating With Events v2​

  • Use event list/search v2 to reason about surrounding calendar context.
  • Use reservation availability v2 to reason about allocatable resources.
  • Keep both flows on UTC timestamps and rely on timezone only for local interpretation.

Screenshot Placeholder​

TODO: add Chrome MCP screenshots for an AI-assisted availability lookup and create-retry flow under docs/assets/agents/.