# MCP Server

Connect StayAPI to Claude, Claude Code, Cursor, and other Model Context Protocol clients. Your AI agent queries hotel data directly from natural-language prompts — no glue code.

User:

"Get me the latest reviews for booking.com/hotel/th/baan-coconut.html"

Agent:

→ calls booking\_hotel\_reviews(url=…) → returns structured reviews

## What you get

- **No new credentials.** Sign in with your StayAPI account from Claude or ChatGPT, or use your existing `X-API-Key`.
- **Same quota and billing** as the REST API — one tool call = one API request.
- **Same SLA** — calls run on the same infrastructure as the REST API.
- Works in **Claude (web, desktop & mobile), Claude Code, Cursor** out of the box.
- Works in **ChatGPT** as an MCP app in developer mode (setup below).

## Quick Start

### Fastest: let your agent install it

Paste the prompt into the agent you already have open. It reads [stayapi.com/install](/install) and sets up the connector itself.

 Paste into Claude Code

```
Read https://stayapi.com/install and set up the StayAPI MCP server for me.
```

Then open a **new** session and run `claude mcp list`: `stayapi` should read `✓ Connected`.

**No key yet?** [Sign up](/users/sign_up) for 50 free requests. The agent asks you for it.

**Claude on the web, desktop, or mobile** doesn't need this prompt: add StayAPI under Settings → Connectors and sign in. **ChatGPT** : add it as an MCP app in developer mode and sign in. Other clients: manual setup below.

Rather do it by hand? The full walkthrough follows.

#### Have an account? Use the pre-filled setup

 Skip the placeholder below — your dashboard has a "MCP Setup" page with the snippets ready to copy. [Open MCP Setup →](/user/mcp)

1

### Get your API key

[Sign up](/users/sign_up) for a free StayAPI account (no credit card required), then copy your API key from the dashboard.

Already have an account? [Sign in](/users/sign_in).

2

### Add the MCP server to your agent

#### Pick the snippet for your AI client

**Claude Code** , **Cursor** , and **Claude Desktop** are three separate products with three different config systems. The snippets below look similar but aren't interchangeable — Claude Desktop in particular needs the `mcp-remote` bridge because its JSON config doesn't accept HTTP servers directly. 

#### Claude (web, desktop & mobile)

No API key needed — you sign in to StayAPI instead. Custom connectors sync across Claude on the web, desktop, and mobile.

1. In Claude, open **Settings → Connectors → Add custom connector**.
2. Name it `StayAPI` and set the URL to `https://api.stayapi.com/mcp`. Leave the advanced OAuth fields empty.
3. Click **Connect** , sign in to StayAPI, and choose **Allow**.

#### ChatGPT (developer mode)

No API key needed — you sign in to StayAPI instead. StayAPI isn't in ChatGPT's plugin directory yet, so you add it yourself in developer mode (Plus, Pro, Business, Enterprise, or Edu, on the web).

1. In ChatGPT, turn on **Settings → Security and login → Developer mode**.
2. Open `chatgpt.com/plugins`, click **+** , and choose **Create MCP app**.
3. Name it `StayAPI`, set the URL to `https://api.stayapi.com/mcp`, and pick **OAuth**. Leave the client ID and secret blank.
4. Sign in to StayAPI and choose **Allow** , then install StayAPI from your personal plugins (`chatgpt.com/plugins?view=personal`).
5. In a **Work** chat, type `@StayAPI` and ask.

ChatGPT can show results as hotel cards (the free `show_hotels` tool). Data tool calls use your plan's credits, like API-key calls.

#### Claude Code

Run from your terminal:

```
claude mcp add --scope user --transport http stayapi https://api.stayapi.com/mcp --header "X-API-Key: YOUR_API_KEY"
```

Then open a **new** Claude Code session (already-running sessions won't see the new server). Confirm with `claude mcp list` — should show `stayapi: … (HTTP) - ✓ Connected`.

#### Cursor

One click installs the connector in Cursor:

[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=stayapi&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vYXBpLnN0YXlhcGkuY29tL21jcCIsImhlYWRlcnMiOnsiWC1BUEktS2V5IjoiWU9VUl9BUElfS0VZIn19)

After installing, replace `YOUR_API_KEY` in Cursor's MCP settings with your real key. Or [sign in](/users/sign_in) for a one-click button with your key already baked in.

Prefer to set it up by hand? Add to `~/.cursor/mcp.json` (create if missing), then restart Cursor:

```
{
  "mcpServers": {
    "stayapi": {
      "type": "http",
      "url": "https://api.stayapi.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}
```

#### Claude Desktop

Add to your `claude_desktop_config.json` (create if missing):

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

macOS / Linux:

```
{
  "mcpServers": {
    "stayapi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.1.18",
        "https://api.stayapi.com/mcp",
        "--header",
        "X-API-Key:YOUR_API_KEY"
      ]
    }
  }
}
```

Windows:

Claude Desktop doesn't inherit your shell `PATH`, so a bare `npx` throws `spawn npx ENOENT`. Point `command` at the absolute path to `npx.cmd`:

```
{
  "mcpServers": {
    "stayapi": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": [
        "-y",
        "mcp-remote@0.1.18",
        "https://api.stayapi.com/mcp",
        "--header",
        "X-API-Key:YOUR_API_KEY"
      ]
    }
  }
}
```

- Verify Node in **Command Prompt** (not the Node.js app / REPL) with `where npx`. If it points elsewhere, use that path; the default is `C:\Program Files\nodejs\npx.cmd`.
- Keep `mcp-remote@0.1.18` pinned — newer builds can throw `Unexpected content type: null`.

1. **Fully quit Claude Desktop with ⌘ Q** — closing the window leaves it running in the menu bar and the new server won't load.
2. Relaunch. **First launch may take ~30 seconds** while `npx` downloads `mcp-remote` from npm; subsequent launches are instant. On a fully locked-down machine, IT may need to allow `registry.npmjs.org`.
3. In a new conversation, click the 🔌 icon — `stayapi` should appear.

Why `mcp-remote`? Claude Desktop's JSON config doesn't natively support HTTP MCP servers yet — it requires stdio entries (`command`/`args`), and the `mcp-remote` adapter bridges the gap. Prefer not to edit JSON? Add StayAPI as a Claude connector instead (see above) — it signs in with OAuth and needs no key.

3

### Try it

Ask your agent something like:

- "What's the destination ID for Lisbon on Booking.com?"
- "Get me 10 of the most recent reviews for https://www.booking.com/hotel/th/baan-coconut.html"
- "Look up Google reviews for 'Bellagio Las Vegas'"
- "Get exact Radisson room rates in London for two nights and separate public from member offers"

## Available tools

Most agents will discover and call the right tool automatically based on your prompt — you don't need to memorize tool names.

| Tool | What it does |
| --- | --- |
| `booking_lookup_destination` | Free-form name (e.g., "Lisbon") → Booking.com `dest_id`. First step before `booking_search_hotels` when you only have a city name. |
| `booking_search_hotels` | List hotels in a destination for a stay window. Takes a `dest_id` (negative integers like `-3233180` are valid — preserve the sign). `country_market` (default `US`) sets the pricing market — Booking.com prices by the visitor's country. Optional market selects country and language/currency defaults (ES: es/EUR; US: en-us/USD); explicit overrides win. effective\_market reports best-effort targeting, not verified geography. Price objects include `labels`, `genius_discount_pct`, and `is_mobile_rate` for observed anonymous rate markers. |
| `booking_hotel_details` | Get one hotel's details — including description, check-in/check-out times, and top-level `property_type` (string or `null`; for example `HOTEL`, `APARTMENT`, `HOLIDAY_HOME`, or `CHALET`; new values may appear). The existing numeric `metadata.property_type` is unchanged. Look up details by `hotel_id` (fast) or canonical Booking URL (slower — the URL is resolved to an ID first). |
| `booking_hotel_room_types` | Get the static room-type catalog by hotel\_id or canonical Booking hotel URL, without dates or occupancy. Optional language defaults to en-us (it for Italian); translations may be unavailable. Returns descriptions, sizes, beds, photos, facilities, and source bathroom/smoking metadata. Beds contain bed\_type, count, and nullable name\_with\_count. name\_with\_count preserves localized text when available and is explicitly null otherwise. No prices, availability, physical stock counts, or inferred capacity. Use booking\_hotel\_rooms for dated availability and rates. [Room types documentation](/docs/endpoints/booking/room-types). |
| `booking_hotel_rooms` | Get room types and live availability for one hotel by `hotel_id` or URL, for a stay window. Returns listed rate blocks plus `availability_summary.total_available_rooms` — a deduplicated count across rate plans. Optional `market` sets country and language/currency defaults; explicit overrides win. `effective_market` reports unverified targeting. Pass the same `country_market` as the search for matching prices. `children_ages` is a comma-separated string of integer ages 0–17; its count must equal `children`. Rate price objects include `labels`, `genius_discount_pct`, and `is_mobile_rate`. inventory\_scope=recommended marks a limited selection; counts cover only returned offers. Rate price requires\_sign\_in is null unless a sign-in condition is explicitly observed; Genius/member labels alone do not establish eligibility. inventory\_scope=desktop\_listed identifies desktop-listed offers, without complete-inventory or bookability guarantees. Family and multiroom occupancy fit may be null. price.currency is authoritative; property currency may be null. Tax basis and included/excluded charges are preserved when supplied. Room facilities belong to the static room-type catalog. Preserve quoted amounts and tax fields; do not infer a public price. cancellation\_policy\_title is a localized plain-text policy summary, or null when unavailable. cancellation\_deadline\_date is the property-local calendar date of the free-cancellation deadline in YYYY-MM-DD format, or null when unavailable or not applicable. It does not specify an exact cutoff time or time zone and is not a promise that the whole day is refundable. Refer to the rate policy for conditions. refundable\_until remains an exact timestamp or null; cancellation\_policy is unchanged. |
| `booking_hotel_reviews` | Get reviews for a hotel by `hotel_id` or URL, with sort and pagination. Use `sort=recent_desc` for date-bounded backfills. Review IDs are opaque strings; deduplicate by ID. Reviewer IDs, travel purpose and selected room photos are omitted. Unknown incentive status and unavailable reviewer review counts are null. |
| `booking_hotel_photos` | Get a hotel's full photo gallery by `hotel_id` or URL. Returns signed, ready-to-use image URLs at thumbnail, medium, and large sizes. `limit` (default 20, `0` = all) and `size` (`thumbnail` / `medium` / `large` / `all`) keep responses compact; `metadata.photo_count` is always the full gallery size. |
| `airbnb_listing_details` | Get an Airbnb listing's details by a decimal-string `listing_id` or any Airbnb URL (URL→ID is instant). |
| `airbnb_listing_calendar` | Get calendar availability by integer `listing_id` or string `url`; provide at least one, with `listing_id` taking precedence. Integer `months` defaults to 12 (range 1–12). Returns `listing_id` and `months`, each with `month`, `year`, and `days` containing `date`, `available`, `available_for_checkin`, `bookable`, and `min_nights`. No nightly pricing. Each successful call costs one credit. |
| `airbnb_listing_reviews` | Get reviews for an Airbnb listing by a decimal-string `listing_id` or URL, with sort + pagination. |
| `google_reviews_for_place` | Get Google reviews for a place — by Google `data_id` or by `query` + optional `location`. The relative `date` is always present; `iso_date` may be null, and `iso_date_source` says whether it is the exact review time (`review`) or the reviewer's photo upload time (`photo`). Exact review dates are available on every page on a best-effort basis; individual dates may be photo-derived or null. Some places return only their first 5 reviews. |
| `google_travel_resolve` | Hotel name → Google Travel `entity_token` candidates. First step for the other `google_travel_*` tools. |
| `google_travel_search` | Free-text hotel search ("hotels in Lisbon") → ~20 hotel cards per `page`, each with rating, nightly and whole-stay price, star class, coordinates, check-in/out times, description, photos, amenity labels, deal note, location score, website, Google `hotel_id`, and an `entity_token` for drilldown; plus Google's `total_count`. Supports optional dates, adults, currency, and Google's `3.5+`, `4.0+`, or `4.5+` guest-rating filter. |
| `google_travel_summary` | A hotel's review summary by `entity_token`: overall rating, total count, star histogram, and review-topic sub-scores. |
| `google_travel_info` | A hotel's identity/metadata by `entity_token`: name, star class, coordinates, address, phone, check-in/out times, descriptions, website, location score, Maps ids, locality chain, and amenities (available, absent, and by section; English labels). |
| `google_travel_photos` | A hotel's photo gallery by `entity_token` (https URLs, dimensions, and occasional AI caption highlights). |
| `google_travel_prices` | A hotel's nightly rate, usual-price band, and partner booking offers by `entity_token`; optional paired YYYY-MM-DD dates plus adults target an explicit stay. Check-in must be today or later and check-out must be after check-in; otherwise Google chooses dates. `currency` shapes money fields. |
| `google_travel_rooms` | Room-level offers per booking site for one hotel and stay, by `entity_token`: each site's room types (name, photos, bed and view features) and, per rate, the nightly and whole-stay price, free cancellation (Google's text plus an ISO `free_cancellation_until` when unambiguous), and breakfast. `official: true` marks the hotel's own website. Only sites with a Google sponsored listing carry room detail, so expect a few, not every `google_travel_prices` offer. Same dates, adults, and currency as `google_travel_prices`. No booking links are returned; use the partner's offer in `google_travel_prices` for a link. |
| `google_travel_similar` | Similar hotels + vacation rentals near a hotel (`entity_token`), each with its own token to pivot to. |
| `google_travel_nearby` | Nearby points of interest (attractions, transit, airports, restaurants) with ratings and drive/walk times, by `entity_token`. |
| `google_travel_reviews` | A hotel's individual Google reviews by `entity_token` — rating, text, reviewer, owner response — with `sort` (most\_relevant / newest / highest\_rating / lowest\_rating) and cursor pagination. Exact creation and edit dates are available on every page on a best-effort basis; individual dates may be photo-derived or null. |
| `google_maps_search` | Search Google Maps for places of any kind (restaurants, cafes, attractions, shops, hotels) by free text, with an optional `location` (`lat,lng`). Up to 20 ranked places per `page` (1 to 10), each with `data_id`, name, categories, address, coordinates, rating, review count, phone, website, today's hours, and live open state. Sponsored results are excluded. |
| `google_maps_place` | Google Maps details for one place by `data_id`: identity ids and Maps link, categories, editorial summary, address and its parts, coordinates, time zone, phone, website, rating with star histogram, review topics, opening hours (plus delivery or takeout hours), attributes, order and reservation links, photos, the owner's name, places inside it, and hotel extras. Reviews come from `google_reviews_for_place` with the same `data_id`. |
| `accor_search` | Search Accor (ALL — Sofitel, Fairmont, Novotel, Ibis, etc.) hotels by `latitude`+`longitude` (+`radius_km`) or `destination_slug`, with each property's best available offer. |
| `accor_hotel_details` | Get an Accor property's public content by `hotel_id`: contact and location, descriptions, ratings, room names and features, facilities, payment methods, accessibility, and media previews. |
| `accor_hotel_amenities` | Get detailed amenity categories and services by `hotel_id`, including fee, coverage, and location metadata plus connecting and family room inventory. |
| `accor_hotel_reviews` | Get up to 20 Accor guest reviews by `hotel_id`, including ratings, text, trip type, dates, and hotel responses. |
| `accor_hotel_rooms` | Get bookable room offers for an Accor property by `hotel_id` (from `accor_search`), grouped into room types with rate plans, prices, and policies. |
| `accor_hotel_photos` | Get an Accor property's full photo/video gallery by `hotel_id`. Public image URLs at every published size. |
| `accor_price_calendar` | Get a per-date cheapest-offer calendar for an Accor property by `hotel_id` (window up to 60 days). |
| `radisson_search` | Search Radisson by destination or hotel name. Returns hotel ids and public property metadata; prices are not included. |
| `radisson_hotel_details` | Get identity, description, location, contact details, services, and status for one Radisson `hotel_id`. |
| `radisson_hotel_amenities` | Get structured services, property types, location types, and tags. |
| `radisson_hotel_reviews` | Get Radisson's TripAdvisor aggregate, ranking, traveler breakdowns, and published review sample. |
| `radisson_hotel_url_to_id` | Resolve a canonical `radissonhotels.com/.../hotels/{slug}` URL to its Radisson hotel code. |
| `radisson_hotel_rooms` | Get static room names, descriptions, capacity, services, and media. Live availability is deliberately excluded. |
| `radisson_hotel_photos` | Get the full categorized Radisson property gallery with public image URLs. |
| `radisson_price_calendar` | Get the lowest public price per arrival date across a window of up to 60 days. |
| `radisson_hotel_rates` | Get the live lowest available cash rate for one hotel and stay, with optional member pricing. |
| `radisson_hotel_room_rates` | Get raw public/member offers plus `normalized_rates` for single-room cash alternatives, nightly reward quotes, and `points_total`. Final redemption cash payable is unverified; mixed cash-and-points offers remain in raw data. |
| `tripadvisor_geo_search` | Free-form place name (e.g., "Paris") → TripAdvisor `geo_id`. **First step** before `tripadvisor_search_hotels` if you only have a place name. |
| `tripadvisor_search_hotels` | List TripAdvisor hotels in a `geo_id` area for an optional stay window. Each hotel carries a `location_id` for the other TripAdvisor tools. |
| `tripadvisor_hotel_details` | Get one TripAdvisor hotel's details by `location_id` or any TripAdvisor hotel URL (URL→ID is instant). |
| `tripadvisor_hotel_reviews` | Get reviews for a TripAdvisor hotel by `location_id` or URL, with `page`/`per_page` and `language`. At most 20 reviews per page; `per_page` above 20 is treated as 20. |
| `tripadvisor_hotel_prices` | Get live provider offers (Booking.com, Agoda, etc.) for a TripAdvisor hotel by `location_id` or URL for a required stay window. |
| `agoda_hotel_url_to_id` | An `agoda.com/<slug>/hotel/<city>-<country>.html` URL (an `/all/` segment is also accepted) → the numeric Agoda `hotel_id`. Use when you have a hotel URL; hotel-name lookup also returns hotel IDs. It fetches the hotel page, so it costs one quota unit. |
| `agoda_search_hotels` | Search by city\_id and required check\_in/check\_out dates. Optional adults (2), rooms (1), children (0), children\_ages (JSON integer array, up to nine ages 0–17), currency (USD), and page (1–1000). Ages override children; omit ages to use age 8 for each child. Returns hotel cards, nullable nightly and whole-booking prices, and pagination. Fixed requested page size 10; actual card count may differ. No URL argument, sort, or filters. |
| `agoda_hotel_details` | Date-free property metadata for a positive integer `hotel_id`: address, available amenities, selected photos, and useful\_information (nullable room count, opening year, check-in/check-out times, and ordered source groups). No URL, dates, locale, or currency parameters. [Hotel details docs](/docs/endpoints/agoda/hotel-details). |
| `agoda_hotel_lookup` | Find hotel suggestions with a query of 2–200 characters. Returns hotel IDs and location context in provider order, with duplicate IDs removed. No pagination, prices, or availability. Use the selected hotel\_id with hotel prices or reviews. |
| `agoda_hotel_prices` | Get live dated Agoda room availability by `hotel_id`, including the lowest all-inclusive stay price, per-night and whole-stay taxes/fees, breakfast, cancellation terms, and explicit sold-out status. Optional children\_ages is a JSON integer array of up to nine ages 0–17 and overrides children, including [] for adults only. Omit it to use age 8 for each child in children. |
| `agoda_hotel_reviews` | Get Agoda's own guest reviews for one Agoda hotel by `hotel_id`. The requested page size is 20; actual counts can differ. Agoda lists English-language reviews first (newest first with the default sort), then reviews in other languages, so for a complete date range, page until `has_more` is false. `sorting` is `7` = most recent (default), `6` = highest rating, `5` = lowest rating. |
| `agoda_hotel_review_comments` | Get Agoda's own guest reviews for one Agoda hotel; returns the same reviews, shape, and pagination as `agoda_hotel_reviews`. |
| `kayak_hotel_url_to_id` | Extract a hotel\_id and canonical URL from a KAYAK property url. existence\_checked is false. Pass hotel\_id to Reviews; Details, Photos, and Amenities require url. |
| `kayak_hotel_details` | Read published hotel content by KAYAK property url: name, plain-text description, address, coordinates, stars, and aggregate rating on a 0–10 scale. No live prices or availability. |
| `kayak_hotel_photos` | Read KAYAK property photos by url with image URLs, thumbnails, categories, and attribution. No pagination or size controls. |
| `kayak_hotel_amenities` | Read top amenities and categorized amenity entries by KAYAK property url. total counts categorized entries, excluding highlights. |
| `kayak_hotel_reviews` | Read KAYAK hotel reviews by hotel\_id and page (1–1000, default 1), up to 10 per page. Follow has\_more; scores use 0–100 and source labels are preserved. No sort selector. |
| `kayak_lookup_destination` | Find city IDs by query (2–100 trimmed characters), with limit 1–50 (default 10). Pass city\_id to the buzz calendar. |
| `kayak_hotel_lookup` | Find hotel IDs by hotel name (2–100 trimmed characters; include the city), with limit 1–50 (default 10). Pass hotel\_id to Reviews. Suggestions can include vacation-rental units listed as hotels. |
| `kayak_buzz_calendar` | Read LOW, MEDIUM, and HIGH daily relative price bands for a city\_id. No monetary prices, currency, or date-range controls. |
| `holidaycheck_hotels_search` | Find hotels by query (1–200 characters after trimming), with page default 1 and up to 10 matches per page. available\_count and has\_more describe the available result set, not a global total. Pass returned hotel\_id directly to details or reviews. No dates, prices, or destination search. |
| `holidaycheck_hotel_details` | Read hotel details by hotel\_id UUID: canonical URL, address, location, contact, descriptions, grouped amenities, and check-in/out wording. Star classification is separate from native six-point guest ratings. No prices or photo gallery. Each successful call costs one credit. |
| `holidaycheck_hotel_url_to_id` | Extract a lowercase hotel UUID from a supported HolidayCheck hotel or review-listing URL. Does not verify existence; individual /hrd/ review URLs are excluded. |
| `holidaycheck_hotel_reviews` | Read HolidayCheck reviews by hotel\_id UUID. Optional page defaults to 1; sort is most\_relevant (default) or recent\_desc. Returns up to 10 reviews per page with native six-point ratings, text sections, and recommendation percentage. No language control or owner responses. Each successful call costs one credit. |
| `tripcom_search_hotels` | Search Trip.com by positive city\_id and required check\_in/check\_out. USD default; adults 2 and rooms 1 (both 1–6), limit 10 (1–20). Optional hotel\_name is trimmed to 1–200 characters with no control characters and requests native name matching within the required city/stay; the response echoes normalized hotel\_name or null. First page only, no children. Nullable source advertised prices have unspecified tax inclusion; use source payment totals with their labels and additional-charge notes rather than multiplying rounded displays. Selected-room names, beds, displayed guests and source labels describe one offer, not inventory, capacity or policy guarantees. |
| `tripcom_hotel_reviews` | Get paginated Trip.com guest reviews by `hotel_id` — rating, text, stay date, room type, travel type, and the hotel's owner response. `page_size` is 1–50 (default 10); `currency` and `locale` only localize the response. Each review includes source: tripcom, ctrip, expedia, hotelscom, tripadvisor, or unknown. Attribution follows explicit review evidence; aggregate Expedia rating counts do not identify individual review origin. Token and signature fields are excluded; public aggregate rating metadata is retained. total\_reviews is the hotel aggregate; pageable\_reviews is the current feed count, not a guarantee that all aggregate reviews are retrievable. Complete zero-total and zero-feed pages are successful empty results. |
| `makemytrip_search_hotels` | Search MakeMyTrip hotels in India by city\_code, dates, and occupancy. Returns hotel IDs, INR listing prices, tax and coupon fields, photos, review summaries, and an opaque next\_cursor. |
| `makemytrip_get_hotel_details` | Get MakeMyTrip hotel descriptions, address, coordinates, amenities, arrival times, and photos. Supply hotel\_id, city\_code, check\_in, and check\_out. |
| `makemytrip_get_hotel_reviews` | Get MakeMyTrip review text, ratings, stay context, and source-aware pagination. Only Most relevant sorting is supported; stop automatic pagination when source\_changed is true and next\_start is null. |
| `hilton_rooms` | Get dated Hilton room types, starting cash offers, and standard or premium full-points rewards. Use hotel\_code, dates, 1–4 adults, and USD or GBP; one room with no children. Reward points include exact stay totals and dated nightly breakdowns. Confirmed unavailability is a successful result with availability\_status unavailable, room\_types [], and total 0; availability\_message explains the result. No Points & Money quotes. |
| `hilton_search` | Search undated Hilton hotel metadata in English by query or coordinates. Returns hotel\_code, photos, amenities, and opening status, without prices or stay availability. |
| `hilton_hotel_url_to_id` | Extract the seven-character Hilton hotel\_code (ctyhocn) from a canonical HTTPS Hilton hotel or reservation rooms URL without checking existence. |
| `bestwe_search_hotels` | Search dated WeHotel (Jin Jiang) inventory by `city_code`. Returns property IDs, public metadata, availability, and lowest visible CNY prices. |
| `bestwe_hotel_url_to_id` | Extract a WeHotel (Jin Jiang) `property_id` locally from a canonical `hotel.bestwehotel.com/HotelDetail?hotelId=...` URL. |
| `bestwe_hotel_details` | Get bilingual WeHotel (Jin Jiang) property content, policies, photos, facilities, services, and static room metadata. |
| `bestwe_hotel_reviews` | Get paginated WeHotel (Jin Jiang) guest reviews with scores, moderated photos, tags, room context, and hotel replies. |
| `bestwe_hotel_rooms` | Get dated WeHotel (Jin Jiang) room inventory and public or member rate plans with CNY prices, breakfast, and cancellation rules. |
| `expedia_hotel_rates` | Get Expedia room rates and availability by numeric property\_id and ordered nonpast stay dates. Adults 1–10; optional children\_ages is a JSON integer array of up to six ages 0–17. Omit it or use [] for adults-only rates. Supported currencies: USD, EUR, GBP, AUD, CAD, JPY, THB, SGD, HKD, INR, NZD, BRL, MXN, CHF, DKK, NOK, SEK, KRW, MYR, IDR, PHP, SAR, TWD, VND, AED, PEN, CLP, COP, EGP, ARS, CNY, ISK and ZAR; normalized to uppercase; default USD. Unsupported codes return invalid input. Prices are native regional quotes and can vary by market, not a fixed exchange-rate conversion. Property and room text may be localized for that market. Member offers have is\_member\_rate=true; null means unknown eligibility. requires\_sign\_in is nullable and a member badge alone does not establish a sign-in gate. Exclude known member offers using is\_member\_rate, not requires\_sign\_in alone. total\_price\_amount is the displayed whole-stay total and may be rounded. reservation\_amount may exclude mandatory property charges and is not the amount due now, including with PAY\_LATER. total\_with\_taxes\_and\_fees is its deprecated alias, not a guaranteed all-inclusive total. Nightly fields are null when not supplied; no tax breakdown is promised. Sold-out stays are valid results. Available results include at least one priced offer; malformed availability is an error. Expedia discovery and reviews use REST. |
| `marriott_bonvoy_search` | Search Marriott Bonvoy hotels near a `latitude`+`longitude` for a stay. Returns each property's `property_id`, brand, rating, distance, lowest cash price, and `points_per_night` when an award rate exists; up to 20 per page, optional corporate code. Add `corporate_only` with a code to return only hotels that have a rate under it, priced at that rate. |
| `marriott_bonvoy_rooms` | Get live room types and rate plans for a Marriott `property_id` and stay: cash `per_night` and `total`, plus Bonvoy award pricing with `points` (check-in night), `points_total` (whole stay), and a per-night `nightly_rates` breakdown. `source_of_rate` is `MARSHA` or `ACRS`; ACRS rates have no per-night breakdown and null per-night fields on multi-night stays. |
| `marriott_bonvoy_price_calendar` | Get the lowest rate for every check-in date at one Marriott `property_id`, for a window of up to 36 dates and 1–9 nights. Each date returns `available`, `per_night` and `stay_total` before taxes in the property's currency, or `points_total` with `use_points`. With `corporate_code`, only rates under that code are returned. |
| `opentable_search_restaurants` | Search OpenTable restaurants near a `latitude`+`longitude` for a `date`/`time`/`party_size`. Returns name, cuisine, price band, rating, address, phone, and photos. |
| `opentable_restaurant_url_to_id` | Resolve a full OpenTable `/r/{slug}` profile URL to its numeric `restaurant_id`, name, country, macro area, and neighborhood. |
| `opentable_restaurant_details` | Get one OpenTable restaurant profile by `restaurant_id`, including cuisine, ratings, address, coordinates, contact details, hours, photos, policies, dining areas, and feature flags. |
| `opentable_restaurant_menu` | Get an OpenTable restaurant's published menus by `restaurant_id`: menu and section names, item descriptions, prices, and portion variations. Prices are strings (restaurants can publish values like `MKT`); a restaurant with no structured menu returns an empty `menus` array. |
| `opentable_restaurant_reviews` | Get OpenTable reviews by `restaurant_id`, sorted by `newest`, `highest`, or `lowest`. Returns up to 25 reviews per page. |
| `opentable_restaurant_availability` | Check whether one exact reservation `time` is available for a restaurant, date, and party size. |
| `opentable_restaurant_availability_slots` | Return OpenTable's nearby bookable `HH:MM` slots around a `preferred_time`. |
| `opentable_private_dining_restaurants` | Search OpenTable **private-dining** venues near a `latitude`+`longitude`, with `cuisine_ids`/`instant_book`/`radius`/`min_capacity` filters. Returns the private-dining contact (name/phone/email), largest-space capacity, plus cuisine, rating, and photos. Pass `with_facets=true` to discover cuisine IDs. |
| `meta_coordinates_lookup` | Resolve a place name (e.g. "Manhattan") to coordinates. Returns matching locations with `latitude`/`longitude`, `type`, country, and `place_id` — use it to get the lat/lng the other tools need. |
| `airbnb_search_listings` | Airbnb destination listings by city, neighborhood or postal code, one page (1–15, 18 listings) per call with total\_pages and has\_next\_page; dedupe overlapping results by listing\_id. Optional paired dates and guest counts. Undated results omit prices; neither mode verifies availability. No property-name lookup. |

## URL vs ID

For Booking, Airbnb, and TripAdvisor tools that fetch a single item, you can pass **either** an `id` **or** a `url`. For OpenTable, call `opentable_restaurant_url_to_id` once, then pass its `restaurant_id` to details, menus, reviews, or availability.

Radisson keeps resolution explicit. Call `radisson_hotel_url_to_id`, then pass the returned `hotel_id` to the content or pricing tool.

Agoda and WeHotel (Jin Jiang) do the same. Call `agoda_hotel_url_to_id` or `bestwe_hotel_url_to_id`, then pass the returned ID to the content, review, or room tools. Trip.com search returns hotel IDs; it has no URL resolver, so `tripcom_hotel_reviews` takes the numeric `hotel_id` only. Marriott Bonvoy has no URL resolver either: `marriott_bonvoy_search` returns the `property_id` codes that `marriott_bonvoy_rooms` takes. Google Maps keys on `data_id`: `google_maps_search` returns one per place for `google_maps_place` and `google_reviews_for_place`.

- **ID is faster** — no resolution step needed.
- **URL works too** — the server resolves it internally. Booking URLs are slower to resolve.
- **OpenTable URLs resolve exactly** — any valid `/r/{slug}` profile URL, including older slugs, via `opentable_restaurant_url_to_id`.

If you only have a URL, pass it. If you have the ID from a previous call, prefer it.

For Airbnb, send a positive decimal `listing_id` string, such as `"22120898"`. Responses also use decimal strings so long IDs stay exact. Safe JSON integers up to `9007199254740991` are accepted, but larger numeric IDs are rejected to prevent precision loss.

## Quota and billing

| Call type | Counts against your quota? |
| --- | --- |
| `initialize`, `tools/list`, notifications | No (free housekeeping) |
| `tools/call` returning successful data or a definitive no-results outcome | **Yes — 1 quota unit per completed call** |
| Invalid input, provider or operational failures, and protocol errors | No, including errors returned with HTTP 200 |
| `tools/call` on an unknown tool name | No |

Billing follows the tool outcome, not just the HTTP status. A completed lookup that confirms no results, such as no available rooms, still uses one quota unit.

Rate limits and monthly quotas are the same as the REST API — your tier dictates both. Both are checked before the tool runs, so a call over a limit gets a JSON-RPC error instead of a tool result:

| HTTP status | JSON-RPC error.code | When | What the error carries |
| --- | --- | --- | --- |
| `402` | `-32001` | Free-plan credits are used up, or a paid subscription is overdue | `error.message` explains what to do; `error.data.code` is `free_tier_limit_reached` or `subscription_payment_required`; `error.data.cta` has the upgrade/billing link (`label`, `url`) |
| `429` | `-32001` | A paid plan's quota is used up | `error.data.code: "quota_exceeded"`, plus `limit`, `remaining_quota`, `tier` and `reset_at`; `Retry-After` and `X-RateLimit-*` headers |
| `429` | `-32002` | Your key is sending requests faster than its rate limit | `error.data.code: "rate_limit_exceeded"` and `error.data.retry_after` (seconds); `Retry-After` and `X-RateLimit-*` headers |

Per-tool usage appears in your activity dashboard as `/mcp/tools/<tool_name>` — so you can see which tools your agents call most.

## Structured errors

When something goes wrong, tools return a structured dict your agent can read and react to, rather than a generic failure:

| Error | When | Shape |
| --- | --- | --- |
| `invalid_input` | Missing or bad parameter | `{error, message, field}` |
| `url_resolution_failed` | Couldn't extract an ID from your URL | `{error, message, provider, outcome}``outcome` (when present) is `not_found`, `unavailable` or `overloaded` |
| `upstream_error` | The upstream hotel provider returned an error | `{error, message, provider}` |
| `no_results` | Query was valid but nothing matched | `{error, message, provider}` |
| `rate_limited` | Service temporarily unavailable | `{error, message, provider, retry_after}` |

Auth failures come back as JSON-RPC error code `-32001`: HTTP 401 for a missing or invalid key, 403 for a blocked account, and 503 when sign-in is temporarily unavailable (retry shortly). Quota and rate-limit rejections are described under [Quota and billing](#quota-and-billing).

## What's NOT supported in v1

- **JSON-RPC batches** — send one tool call at a time. Batched requests return JSON-RPC `-32600`.
- **Google Travel search max-price filter** — the underlying provider doesn't expose one. `google_travel_search` supports Google's discrete `3.5`, `4.0`, and `4.5` guest-rating thresholds; for price caps, filter the response client-side.
- **Pagination on `google_reviews_for_place` by `query`** — `next_page_token` only works when you initially called with `data_id`. The query path returns the first page plus the resolved `data_id` so you can paginate from there.

## Troubleshooting

### Claude Desktop on Windows: `mcp-remote` won't start

The Windows failure ladder, in the order you'll hit it. All three are client-side — the server is fine.

| Symptom | Cause | Fix |
| --- | --- | --- |
| `spawn npx ENOENT` | Claude Desktop can't find `npx` on its PATH. | Use the absolute path to `npx.cmd` (see the Windows snippet above). Verify Node with `where npx` in **Command Prompt** — not the Node.js app / REPL. |
| `'npx' is not recognized` | Node isn't installed, or PATH was stripped by corporate policy. | Install Node LTS and restart the machine. If `where npx` is still blank in `cmd` but works elsewhere, use the absolute path. |
| `Unexpected content type: null` | A `mcp-remote` version regression. | Pin `mcp-remote@0.1.18`. |

### Check the server is reachable from your machine

Before blaming your client config, confirm the server answers from your network. Run this in **Command Prompt** (swap in your real key):

```
curl.exe -i -X POST https://api.stayapi.com/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "X-API-Key: YOUR_API_KEY" -d "{\"jsonrpc\":\"2.0\",\"id\":0,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-11-25\",\"capabilities\":{},\"clientInfo\":{\"name\":\"curl\",\"version\":\"1.0\"}}}"
```

If it returns `200` and `serverInfo: StayAPI`, the server is fine and the problem is your client config.

#### PowerShell users: use curl.exe, not curl

 In PowerShell, `curl` is an alias for `Invoke-WebRequest`, which silently ignores `-H`/`-d`. Use `curl.exe` (as above) or run the command from **Command Prompt**. 

### `401 Unauthorized` on initialize

Your `X-API-Key` header is missing or wrong. Sign in and copy your current key from the dashboard and re-add the connector. Connected through a Claude connector? Disconnect and connect it again.

### `403 Forbidden`

Your account is blocked. Contact [info@stayapi.com](mailto:info@stayapi.com).

### `402` or `429` with `quota_exceeded` on every tool call

Your quota is used up. A `402` (free plan or overdue subscription) carries an upgrade/billing link in `error.data.cta`; a `429` with `error.data.code: "quota_exceeded"` carries `reset_at` — wait until then or upgrade your plan. A `429` with `-32002` is a short-term rate limit, not your quota: wait `retry_after` seconds and retry.

### `url_resolution_failed` from Booking tools

The URL didn't resolve to a hotel. Use a canonical Booking URL (`https://www.booking.com/hotel/{cc}/{slug}.html`), not a search-results URL. Or pass `hotel_id` directly if you have it.

### Tool calls take a long time

`booking_hotel_details(url=…)` and `booking_hotel_reviews(url=…)` resolve the URL first, which adds latency. Pass `hotel_id` directly if you have it.

### My agent isn't using the StayAPI tools

Some agents need the tool descriptions to clearly match the request. Try mentioning a hotel name, URL, or the platform explicitly: "use StayAPI to find…".

## Privacy & security

- Your `X-API-Key` is sent on every request as a custom HTTP header. Treat it like any other API credential — don't paste it into shared chats or commit it to a repo.
- Claude connectors and the ChatGPT app sign in with OAuth and never see your API key. Their access tokens expire after an hour and are refreshed automatically; revoke a connection any time under **Connected apps** on your MCP setup page.
- Tool inputs (URLs, hotel IDs, queries) are logged for analytics and debugging, same as REST API calls.
- All connections to `https://api.stayapi.com/mcp` are TLS-encrypted.
- The MCP server runs on the same infrastructure as the REST API. Same SLA, same data residency, same incident response.

## Related docs

- • [API Documentation overview](/docs)
- • [Authentication & API keys](/docs/authentication)
- • [Booking hotel reviews (REST)](/docs/endpoints/booking/hotel-reviews)
- • [Booking destinations lookup (REST)](/docs/endpoints/booking/destinations-lookup)
- • [Airbnb listing reviews (REST)](/docs/endpoints/airbnb/reviews)
- • [Google Travel hotel search (REST)](/docs/endpoints/google-travel/search)
- • [Google Travel hotel data (REST)](/docs/endpoints/google-travel/resolve)
- • [Google Maps place search (REST)](/docs/endpoints/google-maps/search)

 Questions? Email [info@stayapi.com](mailto:info@stayapi.com).
