MCP & SDK (AI-native access)
The MCP server and SDK are in early access, delivered with AI booking agent enablements. The tool catalog below is the committed contract — build your agent designs against it and confirm activation for your tenant with your implementation team.
HTTP is the right interface for a frontend. For AI agents — a conversational booking assistant, an in-house agent ecosystem, an operations copilot — the right interface is tools. The Journeys MCP server packages the booking API as Model Context Protocol tools, so any MCP-capable model or framework can discover, plan against, and execute bookings without HTTP glue code.
The design goal: an agent should be able to complete the same flow as the quickstart — browse, basket, select, price, pay, book — from tool descriptions alone.
Tool catalog
Tools map 1:1 onto the Journeys API, with descriptions written for model consumption (when to call, what the parameters mean, what to do with the result).
Discovery
| Tool | Backed by | Purpose |
|---|---|---|
search_voyages | GET /catalog/trips | Find trips by region, dates, duration, budget. The tool name remains backward-compatible. |
get_cabin_categories | GET /catalog/categories | Room/cabin category tiers, with solo/popular flags |
get_cabins | GET /catalog/rooms | Live room-option availability and pricing. The tool name remains backward-compatible. |
get_activities | GET /catalog/activities | Optional package add-ons for a trip |
Availability & pricing
| Tool | Backed by | Purpose |
|---|---|---|
create_basket | POST /baskets | Start a booking session for a departure and party |
select_cabin | PATCH /baskets/:id/components | Add a room/cabin (or activity) using selection context. The tool name remains backward-compatible. |
get_price | GET /baskets/:id/prices | Pricing breakdown — totals, deposit, balance, and optional aggregate reseller commission |
apply_promotion | POST /baskets/:id/promotions | Validate and apply a promotion code |
get_payment_options | GET /baskets/:id/payment-schedules | Deposit/balance schedule options |
Booking creation
| Tool | Backed by | Purpose |
|---|---|---|
add_travellers | PUT /baskets/:id/travellers | Set passenger details |
request_payment | POST /baskets/:id/payment-requests | Create a payment request; returns the hosted payment URL to hand to the guest |
create_booking | POST /baskets/:id/bookings | Convert the basket to a booking; returns the booking reference |
Basket session management
| Tool | Backed by | Purpose |
|---|---|---|
get_basket | GET /baskets/:id | Inspect current session state (agent memory across turns) |
remove_promotion | DELETE /baskets/:id/promotions/:code | Remove a code |
reset_selection | component reset extension | Clear a component's selections and re-select when that extension is enabled |
abandon_basket | DELETE /baskets/:id | End the session |
Guardrails
Agent-driven commerce needs harder edges than a human UI:
| Guardrail | Behaviour |
|---|---|
| Tenant scoping | The MCP server is provisioned per tenant; tools cannot reach another tenant's catalog or baskets |
| No payment execution | Agents request payments (request_payment returns a hosted payment URL); card collection always happens on the PCI-scoped payment page, never through a tool |
| Basket expiry | The 15-minute basket lifecycle applies — agents re-create expired sessions rather than resurrecting them |
| Booking finality | create_booking is guarded by basket status — an agent retrying a tool call cannot create a duplicate itinerary |
| Rate limits | Per-tenant tool-call budgets, consistent with the API's rate limiting |
The catalog aliases are intentionally neutral at HTTP level, while existing MCP tool names remain stable for client compatibility.
The current MCP surface creates new bookings and manages the basket that precedes them. It does not execute amendments, existing-booking cancellations, or refunds. Underlying platform calculations or orchestration primitives do not become MCP tools until a corresponding Journeys route and schema are published.
SDK
For teams building agents in code rather than wiring MCP directly, the SDK wraps the same surface with typed clients (TypeScript and Python), handling auth, retries, basket session state, and webhook verification. The SDK and MCP server share the same contract — the OpenAPI specification — so nothing is available in one and missing from the other.
Where this fits
Your agent ecosystem owns the conversation, the model choice, and the guest relationship. The platform provides the rails: catalog truth, live inventory, pricing, promotions, holds, payments, and new booking creation in Salesforce. That separation means the same MCP toolset serves a website chatbot, a messaging-platform integration, or a call-centre copilot without implying unsupported post-booking execution.