MCP Server

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

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:

• 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

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

• 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

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