1Stay MCP Integration

Endpoint

Connecting

The server speaks HTTP transport. Clients that only speak stdio connect through the 1stay-mcp npm proxy. Connecting by URL runs an OAuth flow; direct HTTP calls authenticate with a bearer token instead.

Any MCP client — Cursor, Windsurf, Claude Desktop

{
  "mcpServers": {
    "1stay": {
      "url": "https://mcp.stayker.com/mcp"
    }
  }
}

Claude Code

$ claude mcp add 1stay --transport http https://mcp.stayker.com/mcp

stdio clients

$ npx 1stay-mcp

# or install it globally
$ npm install -g 1stay-mcp
$ 1stay-mcp

Direct HTTP

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sandbox keys begin sk_test_ and production keys begin sk_live_. Tool interfaces, response shapes, and error codes are identical between them — the key is the only difference.

Two clients have their own setup pages: Claude (connector directory, or a custom connector) and ChatGPT (Developer-mode custom connector; 1Stay is not in the ChatGPT app directory yet).

Tools

The eight tools

Required parameters are listed on each. Full parameter tables, response shapes, and error codes live in the API reference.

search_hotels check_in, check_out

Search one room by location and dates. location is required unless latitude and longitude are both given. Returns a search_id and ranked results carrying hotel_id. Check-in must fall within 340 days. Defaults: 4 results (max 15), 25-mile radius (max 100), USD.

get_hotel_details hotel_id, check_in, check_out

Rates and room detail for one hotel. The dates are required — rates cannot be priced without them. Returns room types, live rates, amenities, cancellation policies, and the rate_code values book_hotel requires. Pass accessible: true for ADA room types; the response reports accessible_rooms_available either way.

book_hotel hotel_id, rate_code, check_in, check_out, guests

Starts secure checkout for exactly one room and returns a checkout_url. Accepts no guest identity and no payment fields — name, email, phone and card are collected on the checkout page. Pass external_reference_id for idempotency and later retrieval by your own reference.

get_booking confirmation_number

Retrieves a reservation by the hotel confirmation number from the guest's email. Internal Stayker booking IDs are never accepted or disclosed. Anonymous callers additionally need a verification_token from lookup_booking, scoped to a single booking; a developer key is scoped to that developer's own bookings and needs no token. If the guest does not have the number, send them through resend_confirmation first rather than treating it as a dead end.

lookup_booking first_name, last_name

Finds a reservation by verifying identity, and returns the confirmation number in conversation. Needs the full name plus either the confirmation number or card last four together with the check-in date. An email address is not a verification factor — name plus email alone returns nothing.

resend_confirmation confirmation_number, or name + email

This is the recovery path — no guest is ever locked out of their own reservation. Given a confirmation number it resends. Given only a full name and email, it still resends, to the address already on the booking, and that email carries the confirmation number the guest then uses with lookup_booking or cancel_booking. There is no recipient override, and a recovery request never reveals whether a reservation matched — so it is safe to offer to anyone who asks. Email changes are handled at stayker.com/service.

cancel_booking first_name, last_name, confirmation_number

Returns the hotel's cancellation policy on file plus a first-party 1Stay URL. It does not cancel. The guest opens that page, reviews the policy, and confirms there; until the page reports success the reservation stands. 1Stay never estimates a refund, credit, penalty, or hotel charge.

search_tools —

Lists the available tools. Optional keyword filters by search, book, cancel, or details.

Behavioral contract

What an agent must not do

These are enforced server-side or are correctness requirements on the agent. Integrations that ignore them produce wrong answers for guests.

01 Do not announce a booking from a checkout_url. The reservation and the hotel confirmation number exist only after the guest completes checkout.
02 Do not request more than one room. rooms accepts only 1 across search, details, and booking. Multi-room is not in the first release.
03 Do not replay an expired rate_code. Codes hold for roughly 15 minutes and expired ones are rejected. Re-call get_hotel_details rather than substituting a changed price silently.
04 Do not pass card details to any tool. No tool accepts a card number or security code. Payment happens only on the first-party checkout page.
05 Do not claim a cancellation. cancel_booking is a handoff. Do not estimate what the hotel will charge, and do not report the reservation cancelled until the secure page confirms it.
06 Do not auto-retry a failed booking. A 500 from a booking call may have partially processed. Surface it, then check get_booking or contact support — never retry blind.

Limits

What each tier returns

Capability	Sandbox	Production	Enterprise
Key prefix	`sk_test_`	`sk_live_`	`sk_live_`
Hotels per search	5	15	Custom
Rate plans per hotel	2	All available	All available
Bookings	Simulated only	Live reservations	Live reservations
Searches	100 / day	50,000 / mo included	Custom
Search overage	—	$0.002 / search	Custom
Monthly fee	Free (30 days)	$99 / mo	Custom

Sandbox cannot create a real booking. Any book_hotel call on a sk_test_ key returns a simulated confirmation. No hotel is contacted, no guest is charged, no reservation exists. Enforced server-side. The per-search caps above are ours. Separately, the test inventory behind them holds fewer properties than production and does not cover every destination. Most major cities populate; secondary markets may return nothing, so an empty search_hotels result in sandbox is expected rather than an integration fault — retry a major metro before debugging. Sandbox exercises the integration; it does not represent the catalogue.

Where to go from here

Start here

One endpoint.
Eight tools.

Connecting

The eight tools

What an agent must not do

What each tier returns

Where to go from here

Quick start

Full API reference

Apply for a key

agents.md