Aller au contenu principal
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
  • check_pool_capacity
  • simulate_pool_pricing
  • configure_resource_pool_mode

Availability uses the same domain logic as public booking:

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

Pool-specific MCP additions:

  • check_pool_capacity evaluates a pool resource type and returns both availableResourceCount and availableQuantity
  • simulate_pool_pricing supports either startTime plus endTime or a direct durationHours input for quote-only scenarios
  • configure_resource_pool_mode lets an admin-scoped agent switch a resource type between SINGLE_RESOURCE, POOL, and BOTH

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

OrganisationUser requirement: primecal_reservations_create ultimately calls POST /api/reservations. The backend requires the authenticated user (the agent owner) to have an OrganisationUser record in the target organisation. Without it the call returns 403 Forbidden. The owner's activeOrganisationId must also match the organisation that owns the resource type being reserved. Ensure the agent owner has organisation membership before calling reservation-write tools.

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.