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.

Copy for your AI agent

Paste into Claude, ChatGPT, Cursor or Copilot — endpoint, parameters, response fields and a curl example in Markdown.

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 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 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 →
1

Get your API key

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.

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

After installing, replace YOUR_API_KEY in Cursor's MCP settings with your real key. Or 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.
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.
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_idExtract 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_detailsRead 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_photosRead KAYAK property photos by url with image URLs, thumbnails, categories, and attribution. No pagination or size controls.
kayak_hotel_amenitiesRead top amenities and categorized amenity entries by KAYAK property url. total counts categorized entries, excluding highlights.
kayak_hotel_reviewsRead 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_destinationFind city IDs by query (2–100 trimmed characters), with limit 1–50 (default 10). Pass city_id to the buzz calendar.
kayak_hotel_lookupFind 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_calendarRead 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-32001Free-plan credits are used up, or a paid subscription is overdueerror.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-32001A paid plan's quota is used uperror.data.code: "quota_exceeded", plus limit, remaining_quota, tier and reset_at; Retry-After and X-RateLimit-* headers
429-32002Your key is sending requests faster than its rate limiterror.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_inputMissing or bad parameter{error, message, field}
url_resolution_failedCouldn't extract an ID from your URL{error, message, provider, outcome}outcome (when present) is not_found, unavailable or overloaded
upstream_errorThe upstream hotel provider returned an error{error, message, provider}
no_resultsQuery was valid but nothing matched{error, message, provider}
rate_limitedService 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.

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.

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

Questions? Email info@stayapi.com.
Browse documentation