Skip to main content
Was this helpful?

Enterprise Reservation Tools For MCP

PrimeCal exposes organisation-aware reservation operations through MCP so agents can work with the enterprise reservation system without bypassing application rules.

What These Tools Are For​

Use these tools when an agent needs to:

  • discover which organisations it can access
  • switch the active organisation safely
  • list resource types and resources inside that organisation
  • calculate availability with the same blocking rules used by public booking
  • create or review reservations without handling Stripe directly

Tool Surface​

Organisation Context​

  • primecal.organisations.list
  • primecal.organisations.active.set
  • primecal.organisations.billing.status.get
  • primecal.organisations.billing.settings.update
  • primecal.organisations.stripe.onboardingLink.create
  • primecal.organisations.payments.debug.get

These tools let the agent discover and switch the active organisation. Later resource and reservation calls inherit that active organisation automatically.

The billing tools are admin-only and are intended for:

  • checking whether Stripe is connected and usable
  • updating billing-safe defaults such as the organisation currency
  • preparing a Stripe onboarding handoff URL
  • debugging payment-backed reservation state without exposing Stripe secrets

Reservation Catalog And Availability​

  • primecal.resourceTypes.list
  • primecal.resources.list
  • primecal.reservations.availability.list

Availability uses the same domain logic as public booking:

  • existing reservations
  • resource-type scoping
  • managed-user calendar blocking

Reservation Reads And Writes​

  • primecal.reservations.list
  • primecal.reservations.get
  • primecal.reservations.create

primecal.reservations.create is intentionally narrow:

  • it creates reservations only
  • it does not create Checkout sessions
  • it does not expose Stripe account identifiers or webhook state

Permission And Scope Model​

Agent access is constrained at multiple layers:

  1. the agent API key authenticates the call
  2. the agent permission model controls which action keys are allowed
  3. organisation and resource-type scopes reduce what each tool can target
  4. the underlying PrimeCal services still enforce owner and role boundaries

Supported enterprise reservation scopes:

  • organisationIds
  • resourceTypeIds

Payment Guardrails​

PrimeCal still keeps payment execution outside MCP.

Important behavior:

  • tools do not return Stripe secrets
  • tools do not start Checkout sessions, payment intents, or webhook flows
  • the onboarding helper returns a hosted Stripe onboarding URL only for admins in an explicitly scoped organisation
  • reservation creation is blocked for payment-required resource types unless the owner context is acting in an administrative organisation role

This keeps MCP useful for operational workflows without widening the payment surface.

Typical Agent Flow​

  1. Call primecal.organisations.list.
  2. Call primecal.organisations.active.set.
  3. Call primecal.resourceTypes.list.
  4. Call primecal.reservations.availability.list.
  5. Call primecal.reservations.create only when the target flow is allowed.

For billing support flows:

  1. Call primecal.organisations.active.set.
  2. Call primecal.organisations.billing.status.get.
  3. Call primecal.organisations.payments.debug.get.
  4. Call primecal.organisations.billing.settings.update or primecal.organisations.stripe.onboardingLink.create only when the owner is acting as an organisation admin.

Example Admin Prompts​

  • "Check whether the active organisation has Stripe connected and tell me why paid bookings are blocked."
  • "Update the active organisation billing currency to eur."
  • "Prepare the Stripe onboarding link for the active organisation."
  • "List the last 10 pending or failed payment-backed reservations for the active organisation."

Screenshot References​

CaptureFileCaption
Agent scope UIdocs/assets/agents/enterprise-reservations/mcp-agent-organisation-scope.pngScope the agent to only the organisations and resource types it needs.
Tools listdocs/assets/agents/enterprise-reservations/mcp-tools-list-organisations-and-reservations.pngThe MCP tool catalog should show organisation, availability, and reservation actions together.
Availability responsedocs/assets/agents/enterprise-reservations/mcp-availability-tool-response.pngAvailability responses should reflect reservation and own-calendar blocking, not only free inventory.
Non-payment create responsedocs/assets/agents/enterprise-reservations/mcp-create-reservation-non-payment-response.pngReservation creation succeeds for supported non-payment flows and returns the stored quote fields.
Payment-required denialdocs/assets/agents/enterprise-reservations/mcp-payment-required-denial.pngPayment handling stays outside MCP unless the owner context is acting in an administrative flow.