MCP Server

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.

Claude Code Cursor Codex Other agents

Paste into Claude Code Copy

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.

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

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

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

{
  "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"
      ]
    }
  }
}

Available tools

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

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

• 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

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

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

• JSON-RPC batches — send one tool call at a time. Batched requests return JSON-RPC -32600.
• Google Hotels 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

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\"}}}"

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
• • Authentication & API keys
• • Booking hotel reviews (REST)
• • Booking destinations lookup (REST)
• • Airbnb listing reviews (REST)
• • Google Hotels search (REST)
• • Google Travel hotel data (REST)