# HotelOne

> HotelOne lists independent hotels, inns and motels with their own booking sites. AI assistants can search them, check live availability and prices, answer guests' questions and book — through an MCP server or a REST API. No sign-up or key is needed to search or to get a booking link.

The all-in-one platform for independent hotels: a white-labeled booking website, an AI agent that answers calls and chats like your best front-desk clerk, and one dashboard that keeps your booking channels in sync.

## Connect

- [MCP server (all hotels)](https://hotelone.site/api/mcp): Streamable HTTP, stateless JSON-RPC (protocol 2025-06-18, 2025-03-26, 2024-11-05). Add it as a custom connector or remote MCP server; no authentication needed.
- One hotel's own MCP server: https://hotelone.site/api/mcp/hotels/{propertyId} — the same tools for that hotel only (no hotel id needed).
- [REST API](https://hotelone.site/api/agents/v1) and its [OpenAPI 3.1 description](https://hotelone.site/openapi.json) — import as a GPT Action or any OpenAPI tool.
- [Agent card](https://hotelone.site/.well-known/agent-card.json) · [MCP manifest](https://hotelone.site/.well-known/mcp.json) · [Full details for models](https://hotelone.site/llms-full.txt)
- [How to connect ChatGPT, Claude, Grok, Le Chat and others](https://hotelone.site/assistants)

## Booking flow

1. search_hotels (GET /api/agents/v1/hotels) with a place and, if known, dates (YYYY-MM-DD), guests and rooms.
2. check_availability (GET /api/agents/v1/hotels/{propertyId}/availability) for the hotel the person picks.
3. get_booking_link (POST /api/agents/v1/booking-links): a checkout link with everything filled in — the person opens it and confirms in one tap. This is the default.
4. No screen? request_booking (POST /api/agents/v1/booking-requests): the hotel team confirms and sends a link.
5. With a hotel's API key ("book" scope): create_booking (POST /api/agents/v1/bookings) makes a confirmed booking, paid at the hotel.

One booking can mix room types (e.g. 1 King and 2 Doubles): pass items (each roomTypeId and its rooms) instead of roomTypeId. Always read back the hotel, room, dates, guests and total and get a clear yes before request_booking or create_booking. Quote prices only from tool results. Questions about a hotel: ask_hotel. Existing bookings: find_booking (code + last name).

## Limits

- 120 requests a minute per IP address (600 a minute with an API key).
- Booking requests: 10 an hour per IP (60 with a key). Bookings: 60 an hour per key.
- Booking lookups: 20 an hour per IP (200 with a key).
- With API keys, a hotel's keys together also share an hourly allowance (100 bookings, 100 booking requests, 300 lookups), and each hotel takes a limited number of booking requests an hour from callers without a key.
- Over the limit: HTTP 429 with Retry-After (MCP tool calls return an error result the model can explain).

## Optional

- [Hotel directory](https://hotelone.site/properties)
- Contact: hello@hotelone.site

---

# Details

## MCP server

- Endpoint: https://hotelone.site/api/mcp (all hotels) or https://hotelone.site/api/mcp/hotels/{propertyId} (one hotel: no search_hotels, no propertyId argument; ask_hotel lists that hotel's topics).
- Transport: Streamable HTTP, stateless. POST one JSON-RPC 2.0 message (or a batch) with `Content-Type: application/json`; answers are `application/json`. Notifications get 202. No SSE stream and no Mcp-Session-Id — GET returns 405.
- Protocol versions: 2025-06-18, 2025-03-26, 2024-11-05 (initialize negotiates; latest 2025-06-18). Server HotelOne 1.0.0.
- Methods: initialize, notifications/initialized, ping, tools/list, tools/call.
- Tool results carry `structuredContent` (the JSON result) and the same JSON as text; failures come back with `isError: true` and a message to relay.
- Errors: -32700 parse error, -32600 invalid request, -32601 unknown method, -32602 invalid params or unknown tool, -32001 bad API key (HTTP 401), -32003 origin not allowed (403), -32004 unknown hotel (404), -32029 rate limited (429).
- CORS is open to https sites (browser-based clients); server-to-server calls need no Origin.

## Authentication

Searching, details, availability, answers, booking links, booking requests and lookups are public. create_booking needs `Authorization: Bearer ho_live_…` — a key the hotel owner creates in the HotelOne console (AI assistants). A key for one hotel books only there. A bad or revoked key gets HTTP 401 on every call (it never silently falls back to public access).

## REST API

Base: https://hotelone.site/api/agents/v1 · OpenAPI 3.1 (1.0.0): https://hotelone.site/openapi.json
Errors are JSON: `{ "error": "…", "message": "…", "code": "…", "details": {…} }` with the matching HTTP status (400 rules and validation, 401/403 keys, 404 unknown hotel or booking, 409 just sold out, 429 rate limited).

## Conventions

- Dates YYYY-MM-DD (hotel time); stays up to 30 nights; 1–16 guests; 1–9 rooms.
- Money is USD numbers; `total` is the whole stay for all rooms; nightly prices are per room.
- Booking links don't hold the room; the price is confirmed at checkout.
- Free cancellation and date changes until 3:00 PM (hotel time) the day before arrival. Check-in from 3:00 PM, check-out by 11:00 AM.

## Tools

### search_hotels — Search hotels

Find HotelOne hotels by place (city, state, zip or area), by name, or by what the person wants (query: "ocean view", "sauna", "motel"). Pass checkIn and checkOut (YYYY-MM-DD) to get live availability and the cheapest price for the stay; guests and rooms default to 2 and 1. If the result has a note, pass it on: results may be the closest places, and with no hotels in the place, places lists where HotelOne has hotels. Start here, then call check_availability for the hotel the person picks. Each hotel has an id (propertyId) for the other tools.

- REST: GET /api/agents/v1/hotels?location=…&checkIn=…&checkOut=…&guests=…&rooms=…
- Hints: read-only
- Arguments:
  - `query` (string, optional) — A hotel name or what the guest wants, e.g. "saltwater inn", "ocean view", "sauna" or "motel". Ranks hotels by matching words in name, type, description and amenities; small typos are fine
  - `location` (string, optional) — Where the guest wants to stay: city, state, zip or area, e.g. "Santa Cruz, CA"
  - `checkIn` (string, optional) — Arrival date (YYYY-MM-DD). With checkOut, results carry live availability and prices
  - `checkOut` (string, optional) — Departure date (YYYY-MM-DD), after checkIn; at most 30 nights
  - `guests` (integer, optional, default 2) — Total guests in the party (1–16)
  - `rooms` (integer, optional, default 1) — Rooms needed (1–9)
  - `limit` (integer, optional, default 8) — Maximum hotels to return (1–20)

### get_hotel — Hotel details

Everything about one hotel: description, address, phone, amenities, check-in and check-out times, cancellation policy, room types with starting prices, photos, and the hotel’s own answers to common questions. Use when the person wants to know more about a hotel.

- REST: GET /api/agents/v1/hotels/{propertyId}
- Hints: read-only
- Arguments:
  - `propertyId` (string, required) — Hotel id from searchHotels

### check_availability — Check availability

Live availability and exact prices (in the hotel’s currency, taxes and fees included) for every room type at one hotel for given dates and party. Suggest an option that is available and fits the party (fits_party), then use its room_type_id with get_booking_link. A party that wants different room types together (say a King and a Twin) can book them as one booking with items.

- REST: GET /api/agents/v1/hotels/{propertyId}/availability?checkIn=…&checkOut=…&guests=…&rooms=…
- Hints: read-only
- Arguments:
  - `propertyId` (string, required) — Hotel id from searchHotels
  - `checkIn` (string, required) — Arrival date (YYYY-MM-DD)
  - `checkOut` (string, required) — Departure date (YYYY-MM-DD), after checkIn; stays are at most 30 nights
  - `guests` (integer, optional, default 2) — Total guests in the party (1–16)
  - `rooms` (integer, optional, default 1) — Rooms needed (1–9)

### get_booking_link — Get a booking link

The fastest way to book a room: returns a checkout link with the hotel, room, dates and party filled in (and the guest’s name, email and phone if you pass them), plus a summary with the total. Give the person the link and the summary — they open it, check the details and confirm in one tap. The link doesn’t hold the room or charge anything by itself. Use this by default. For different room types in one booking (e.g. 1 King and 2 Doubles), pass items (each roomTypeId and its rooms) instead of roomTypeId; guests is the whole party.

- REST: POST /api/agents/v1/booking-links (JSON body)
- Hints: read-only
- Arguments:
  - `propertyId` (string, required) — Hotel id from searchHotels
  - `roomTypeId` (string, optional) — room_type_id from checkAvailability (or use items for several room types)
  - `checkIn` (string, required) — Arrival date (YYYY-MM-DD)
  - `checkOut` (string, required) — Departure date (YYYY-MM-DD), after checkIn; stays are at most 30 nights
  - `guests` (integer, optional, default 2) — Total guests in the party (1–16)
  - `rooms` (integer, optional, default 1) — Rooms needed (1–9)
  - `items` (array, optional) — To book several room types together (for example 2 King rooms and a Twin), list each with its room count instead of roomTypeId and rooms. The party (guests) is shared across them. At most 4 room types and 9 rooms in all.
  - `guest` (object, optional) — Optional details the checkout page pre-fills
    - `name` (string | null, optional) — Guest’s full name, to pre-fill checkout
    - `email` (string | null, optional) — Guest’s email, to pre-fill checkout
    - `phone` (string | null, optional) — Guest’s phone, to pre-fill checkout

### request_booking — Send a booking request

For people who can’t open a link (for example on a voice call): sends a booking request to the hotel’s team, who confirm with the guest and send a link to finish booking. Nothing is booked until then. Needs the guest’s full name and an email or phone number. For different room types in one booking (e.g. 1 King and 2 Doubles), pass items (each roomTypeId and its rooms) instead of roomTypeId; guests is the whole party. Before calling, read back the hotel, room, dates, number of guests and the total, and only call it after the person clearly says yes.

- REST: POST /api/agents/v1/booking-requests (JSON body) → 201
- Hints: changes something (needs the person’s clear yes)
- Arguments:
  - `propertyId` (string, required) — Hotel id from searchHotels
  - `roomTypeId` (string, optional) — room_type_id from checkAvailability (or use items for several room types)
  - `checkIn` (string, required) — Arrival date (YYYY-MM-DD)
  - `checkOut` (string, required) — Departure date (YYYY-MM-DD), after checkIn; stays are at most 30 nights
  - `guests` (integer, optional, default 2) — Total guests in the party (1–16)
  - `rooms` (integer, optional, default 1) — Rooms needed (1–9)
  - `items` (array, optional) — To book several room types together (for example 2 King rooms and a Twin), list each with its room count instead of roomTypeId and rooms. The party (guests) is shared across them. At most 4 room types and 9 rooms in all.
  - `name` (string, required) — Guest’s full name
  - `email` (string | null, optional) — Email for the booking link (email or phone is required)
  - `phone` (string | null, optional) — Callback number (email or phone is required)
  - `notes` (string | null, optional) — Special requests, if any

### create_booking — Book now (pay at the hotel) (API key with the "book" scope)

Makes a confirmed booking at any HotelOne hotel, paid at the hotel on arrival, and emails the guest a confirmation. Needs the guest’s first and last name and their own email. For different room types in one booking (e.g. 1 King and 2 Doubles), pass items (each roomTypeId and its rooms) instead of roomTypeId; guests is the whole party. Before calling, read back the hotel, room, dates, number of guests and the total, and only call it after the person clearly says yes. Returns a confirmation code to give the guest (one code for the whole booking, even with several room types).

- REST: POST /api/agents/v1/bookings (JSON body, Authorization: Bearer ho_live_…) → 201
- Hints: changes something (needs the person’s clear yes)
- Arguments:
  - `propertyId` (string, required) — Hotel id from searchHotels
  - `roomTypeId` (string, optional) — room_type_id from checkAvailability (or use items for several room types)
  - `checkIn` (string, required) — Arrival date (YYYY-MM-DD)
  - `checkOut` (string, required) — Departure date (YYYY-MM-DD), after checkIn; stays are at most 30 nights
  - `guests` (integer, optional, default 2) — Total guests in the party (1–16)
  - `rooms` (integer, optional, default 1) — Rooms needed (1–9)
  - `items` (array, optional) — To book several room types together (for example 2 King rooms and a Twin), list each with its room count instead of roomTypeId and rooms. The party (guests) is shared across them. At most 4 room types and 9 rooms in all.
  - `guest` (object, required) — The guest the booking is for
    - `name` (string, required) — Guest’s first and last name
    - `email` (string, required) — Guest’s own email: the confirmation goes there
    - `phone` (string | null, optional) — Guest’s phone, if given
  - `notes` (string | null, optional) — Special requests, passed to the hotel

### find_booking — Find a booking

Look up an existing booking by its confirmation code and the guest’s last name: status, hotel, room, dates, until when changes are free, and how to change or cancel.

- REST: GET /api/agents/v1/bookings/{code}?lastName=… (404 when nothing matches)
- Hints: read-only
- Arguments:
  - `code` (string, required) — Confirmation code from the booking confirmation
  - `lastName` (string, required) — Guest’s last name as booked

### ask_hotel — Ask the hotel

Answer a guest’s question about a hotel — parking, pets, breakfast, Wi-Fi, check-in times, cancellation, getting there and more — from the hotel’s own saved answers. Pass the question in the guest’s words, or a topic key. If nothing matches, say you’re not sure and share the hotel’s phone number; never guess.

- REST: GET /api/agents/v1/hotels/{propertyId}/answers?question=…
- Hints: read-only
- Arguments:
  - `propertyId` (string, required) — Hotel id from searchHotels
  - `question` (string, optional) — The guest’s question in their own words, e.g. "Is parking free?" or "can I bring my dog"
  - `topic` (string, optional) — A topic key from the hotel’s answers (e.g. "policies", "amenities", "contact") to get that answer directly

## Example requests from people

- "Find me a room in Santa Cruz next weekend for two and book it."
- "Is parking free at The Saltwater Inn?"
- "Something in Monterey for 3 nights from November 12, under $250 a night."
- "Find my booking — code ABC123, last name Smith."

## Example MCP call

```http
POST https://hotelone.site/api/mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_hotels","arguments":{"location":"Santa Cruz, CA","checkIn":"2026-11-30","checkOut":"2026-12-02","guests":2}}}
```