StayAPI MCP Server — Use StayAPI from Claude, Cursor, and Claude Code

What you get

No new credentials. Uses your existing StayAPI X-API-Key.
Same quota and billing as the REST API — one tool call = one API request.
Same SLA — calls go through the same scrapers and proxies as the REST API.
Works in Claude, Claude Code, Cursor out of the box.
ChatGPT custom connectors not supported in v1 — they require OAuth.

Quick Start

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

Claude Code

Run from your terminal, then restart Claude Code:

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

Cursor

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, then restart Claude Desktop:

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

Config file location depends on OS — see Anthropic's docs.

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/us/the-line-la.html"
"Look up Google reviews for 'Bellagio Las Vegas'"

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).
`booking_hotel_details`	Get one hotel's details by `hotel_id` (fast) or canonical Booking URL (slower — 5–40 s for URL→ID resolution).
`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.
`airbnb_listing_details`	Get an Airbnb listing's details by `listing_id` or any Airbnb URL (URL→ID is instant).
`airbnb_listing_reviews`	Get reviews for an Airbnb listing by `listing_id` or URL, with sort + pagination.
`google_hotels_search`	Search hotels via Google Hotels (SerpAPI-backed).
`google_reviews_for_place`	Get Google reviews for a place — by Google `data_id` or by `query` + optional `location`.
`airbnb_search_listings`	⚠️ Not yet available — returns a clear "feature unavailable" message with a request link to `info@stayapi.com`. Not billed.

URL vs ID

For Booking and Airbnb tools that fetch a single item, you can pass either an id or a url:

ID is faster — no resolution step needed.
URL works too — the server resolves it internally. Booking URLs are slower to resolve.

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

Quota and billing

Call type	Counts against your quota?
`initialize`, `tools/list`, notifications	No (free housekeeping)
`tools/call` on a supported tool	Yes — 1 quota unit per call
`tools/call` on `airbnb_search_listings` (stub)	No (not billed for unavailable features)
`tools/call` on an unknown tool name	No

Rate limits and monthly quotas are the same as the REST API — your tier dictates both. When you hit a quota limit, the tool returns a structured quota_exhausted error with retry_after and the reset time, so the agent can back off intelligently.

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}`
`upstream_error`	Provider (Booking, Airbnb, Google) returned an error	`{error, message, provider}`
`no_results`	Query was valid but nothing matched	`{error, message, provider}`
`rate_limited`	Internal scraper queue saturated	`{error, message, provider, retry_after}`
`quota_exhausted`	Monthly quota is used up	`{error, message, retry_after, reset_at, remaining_quota}`
`feature_unavailable`	Feature isn't built yet (see `airbnb_search_listings`)	`{error, message, support_email}`

Auth failures (missing or invalid key) come back as JSON-RPC error code -32001 with HTTP 401 or 403.

What's NOT supported in v1

Airbnb listing search by location/dates — only details and reviews work today. Email info@stayapi.com if you need search.
JSON-RPC batches — send one tool call at a time. Batched requests return JSON-RPC -32600.
ChatGPT custom connectors — they require OAuth, which v1 doesn't support. Use Claude / Claude Code / Cursor instead.
Google Hotels max-price filter — the underlying provider doesn't expose one. min_rating works; for price caps, your agent can 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

`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.

`403 Forbidden`

Your account is blocked or your IP isn't in your account's allowlist (Enterprise tier feature). Contact info@stayapi.com.

`quota_exhausted` on every tool call

You've used your monthly quota. The error includes reset_at — wait until then or upgrade your plan.

`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.

`feature_unavailable` from `airbnb_search_listings`

Airbnb search isn't built yet. Email info@stayapi.com to vote for it.

Tool calls take a long time

booking_hotel_details(url=…) and booking_hotel_reviews(url=…) resolve the URL via a real-browser fetch — 5–40 seconds worst case. Pass hotel_id directly if you have it. Other tools should respond in 1–5 seconds.

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.
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.

MCP Server