Tour Booking WebMCP Adapter

• 

  Booking Interface

• 

  Codex with WebMCP

Inspiration

Tour bookings are often controlled by large marketplaces that sit between travelers and local operators. These intermediaries can add commissions, weaken the direct customer relationship, and make small operators dependent on centralized platforms.

Our inspiration was to use WebMCP to create a more direct model. A traveler can ask an LLM what they want in natural language, and the agent can interact directly with tools published by the tour operator's own website—without scraping the page or routing the customer through a marketplace.

The agent automates repetitive steps such as discovering tours, comparing departures, checking current capacity, and preparing the visible cart. The operator retains ownership of its inventory, brand, and customer relationship, while the traveler remains in control of checkout, payment, and final confirmation.

What it does

Tours Booking WebMCP lets an AI agent work with the same inventory and cart that the traveler sees.

It exposes four WebMCP tools:

• search_departures searches the page's current inventory snapshot.
• get_departure refreshes and re-checks the capacity, price, and transfer options for a specific departure.
• prepare_booking validates a complete selection against refreshed capacity and atomically replaces the visible cart.
• get_booking_summary reports the cart contents, total price, estimated authorization amount, editability, and recommended next action.

An agent can help travelers discover suitable tours, verify that enough spaces remain, and prepare a cart for review. It cannot collect contact or billing details, handle cards, authorize payment, reserve inventory, or confirm a booking. Those actions remain human-controlled in the visible booking experience.

The normal interface continues to work when WebMCP is unavailable, making the integration a progressive enhancement.

How we built it

We built a framework-independent TypeScript adapter around WebMCP's imperative document.modelContext.registerTool() API.

The host booking page supplies normalized inventory and cart-state callbacks. The adapter owns the tool descriptions, strict JSON schemas, matching runtime validation, freshness rules, response formatting, cancellation, lifecycle cleanup, and safe cart-preparation protocol.

For an exact departure check or cart preparation, the adapter asks the host to refresh inventory instead of presenting cached data as current. prepare_booking validates the complete replacement cart, checks the page state before and after the asynchronous refresh, and performs exactly one atomic commit. If validation or a state check fails, the existing cart remains unchanged.

Inventory-derived results are marked as untrusted content. Read-only tools are annotated accordingly, while the cart-mutating tool is explicitly identified as non-read-only.

The repository also includes a backend-free Vite demo with deterministic in-memory inventory, a fake document.modelContext test harness, documentation, and agent-evaluation scenarios.

Challenges we ran into

One challenge was designing around an experimental browser API whose availability and behavior may change. The application still needed to remain usable in browsers without WebMCP.

Freshness was another major challenge. Availability can change between an agent's search and its attempt to prepare a cart, so saved inventory cannot be presented as current. We added explicit freshness metadata, forced refreshes for exact checks, and capacity validation immediately before committing cart state.

Asynchronous refreshes also introduced race conditions. Checkout could begin, another browser tab could become active, or an invocation could be cancelled while capacity was being refreshed. We addressed these cases with before-and-after state checks, serialized preparation, abort-signal propagation, and an atomic commit boundary.

Finally, we wanted useful agent capabilities without quietly turning a cart tool into a payment or reservation tool. Identity, billing, cards, payments, reservations, and confirmations therefore remain completely outside the tool contracts.

Accomplishments that we're proud of

• Built a coherent four-tool WebMCP experience rather than a single demonstration call.
• Connected agent actions to the same visible cart controlled by the traveler.
• Implemented fresh-capacity validation and all-or-nothing cart preparation.
• Preserved a strict human boundary around personal data, payment, reservation, and confirmation.
• Added 21 deterministic tests covering schemas, freshness, time zones, capacity, atomicity, concurrency, cancellation, lifecycle cleanup, and safety boundaries.
• Defined nine agent-evaluation scenarios covering tool selection, argument accuracy, ambiguity, unavailable data, and unsafe payment requests.
• Kept search responses within a compact 1,536-byte target.
• Created an independently runnable demo requiring no credentials, customer data, private API, or payment provider.
• Passed the complete formatting, testing, TypeScript build, demo build, and package-verification pipeline.

What we learned

We learned that designing WebMCP tools is as much a product and security exercise as it is an API exercise. Tool names, descriptions, schemas, annotations, and results collectively shape how reliably an agent behaves.

We also learned that freshness must be represented explicitly. "Available" is not meaningful unless the agent and traveler know whether the information came from a current refresh or a saved snapshot.

Most importantly, we learned that useful agent assistance does not require handing over the entire user journey. Agents can reduce discovery and coordination work while preserving meaningful human control over sensitive and consequential actions.

What's next for Tours Booking WebMCP

Next, we plan to:

• Deploy the demo with the browser headers and origin-trial configuration required by the active WebMCP implementation.
• Connect the adapter to normalized production inventory through the existing host callbacks without exposing private booking endpoints.
• Run the evaluation suite across additional WebMCP-capable agents and browsers.
• Add more inventory scenarios, accessibility testing, and localized user-facing explanations.
• Continue refining consent and review UX while keeping payment and confirmation human-controlled.

Built With

• bun
• css3
• html5
• javascript
• node.js
• openai
• typescript
• vite
• webmcp
• webmcp-types