# Book Hotels

> The booking layer for AI agents. Search, hold, and book hotels through one API.

Book Hotels lets AI agents search, hold, book, modify, and cancel real hotel stays.
An agent calls search_hotels (then get_hotel for photos), hold_offer, then book_hotel.
book_hotel returns a payment_url: the user pays there with their own card, Link, Apple Pay or
Google Pay, and get_booking then returns the confirmation number. Payment is the only step outside the chat.

## Endpoint
- MCP (Streamable HTTP): https://bookhotelsmcp.com/mcp
- Booking API: https://bookhotelsmcp.com/availability · https://bookhotelsmcp.com/bookings
- Manifest: https://bookhotelsmcp.com/.well-known/mcp.json
- Capabilities: https://bookhotelsmcp.com/agent.json

## Tools
- search_hotels: Find bookable hotel rooms with live prices, photos, star rating, and cancellation terms. Call first for any stay request. Returns offer_id, totals, photoUrl, amenities, and display_markdown for Muse. Next: get_hotel, hold_offer, or book_hotel.
- get_hotel: Load photos, amenities, description, and check-in times for one hotel_id from search_hotels. Call before quoting a stay so the user can see the property. Returns display_markdown Muse can render.
- get_offer: Re-check the current price and cancellation policy for one offer_id before quoting it to the user. Returns PRICE_CHANGED or OFFER_EXPIRED with alternates if anything moved.
- hold_offer: Lock an offer's price for 15 minutes and get a hold_id. Call this as soon as the user picks a room, before collecting guest details, so the price can't move while they decide. Returns hold_id and expires_at. Next step: book_hotel with hold_id.
- book_hotel: Reserve the room. Pass hold_id (preferred) or offer_id, guest name/email, and a unique idempotency_key. Returns a booking_id and a payment_url: show the link so the user pays securely with their own card (cards, Apple Pay, Google Pay). Never collect card numbers in chat. After the user pays, call get_booking for the confirmation number. Retries with the same key return the same booking.
- get_booking: Look up a reservation by booking_id: status, confirmation number, dates, total, and cancellation terms.
- modify_booking: Change a booking's guest name/email or stay dates. Date changes re-price at the same hotel; if the total moves, confirm with the user and call again with confirm_new_total. Returns the updated booking or PRICE_CHANGED / NOT_MODIFIABLE.
- cancel_booking: Cancel a reservation made through this connector. Returns the updated booking, or NOT_CANCELLABLE with exact instructions when the rate is non-refundable or the property must be contacted directly. Refunds a charged Shared Payment Token when the cancel succeeds.

## Guarantees
- Prices are re-checked before every booking; a changed price is returned as PRICE_CHANGED, never silently booked.
- Holds lock the quoted price for 15 minutes.
- book_hotel is idempotent on idempotency_key.
- The user pays on the hosted payment_url. Never collect card numbers in chat.
- Every failure is a structured error with a suggested next action.

## Example prompts
- "Book me a hotel in Boston Thursday to Saturday under $250 a night"
- "Find a refundable room near Acadia National Park for two nights in October"
- "I need somewhere to stay in Austin tonight, closest to the convention center"
- "Get me a hotel in Chicago for the 14th and 15th, two adults, and book it"
- "Cancel my hotel reservation"
- "What's the cheapest place with free cancellation in Portland Maine this weekend?"

## Legal
- Privacy: https://bookhotelsmcp.com/privacy
- Terms: https://bookhotelsmcp.com/terms
- Support: https://bookhotelsmcp.com/support
- Help: https://bookhotelsmcp.com/help
- Support email: support@bookhotelsmcp.com