# MCP connection

Connect a client that supports Streamable HTTP and bearer headers. The endpoint is `https://www.hoteluse.dev/mcp`. Use the same HotelUse account API key as HTTP.



```json
{
  "mcpServers": {
    "hoteluse": {
      "url": "https://www.hoteluse.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_HOTELUSE_API_KEY"
      }
    }
  }
}
```



This developer connection uses an API key and the account's normal usage billing. Enter the key through your client's secret settings; header/environment syntax varies by client. The consumer search connector below uses a separate no-authentication endpoint.

## Consumer search connector

[Connect Claude](/docs/mcp/claude.html) · [Connect ChatGPT](/docs/mcp/chatgpt.html) · [Build with AI agents](/docs/mcp/ai-agents.html).

Connect ChatGPT, Claude or another MCP Apps host to `https://www.hoteluse.dev/mcp/search` with **No authentication**. It exposes three tools: `search_hotels`, `get_room_rates` and `get_hotel`, returning structured multi-provider prices and an interactive comparison UI. It does not require a HotelUse account, API key, prepaid credit or per-user free allowance. Provider links first use a signed HotelUse /go/ URL, then redirect to the provider with affiliate tracking preserved. Links expire with the 10-minute quote. A booking may earn HotelUse a commission. Booking and payment happen at the provider.



```json
{
  "mcpServers": {
    "hoteluse": {
      "type": "streamable-http",
      "url": "https://www.hoteluse.dev/mcp/search"
    }
  }
}
```



Example consumer search arguments: `destination` is a place name, with hotel-local `check_in` and `check_out` (today or later), or `date_intent: "tonight"` without explicit dates. Optional `country` disambiguates the destination. Omitted `rooms` means two adults in one room. The consumer connector accepts one to three rooms so its booking handoff matches provider support.



```json
{
  "destination": "Bellevue, Washington, US",
  "check_in": "2026-11-12",
  "check_out": "2026-11-14",
  "currency": "USD",
  "locale": "en-US",
  "rooms": [
    {
      "adults": 2,
      "children_ages": []
    }
  ]
}
```



For tonight, send `{ "destination": "Bellevue, Washington", "country": "US", "date_intent": "tonight", "rooms": [{ "adults": 1, "children_ages": [] }], "hotel_filters": { "star_ratings": [4, 5] } }`. The server resolves the destination local date, including after UTC midnight. It never moves tonight to tomorrow merely because UTC advanced. The returned `data.context.check_in`, `check_out` and `date_context` show the actual itinerary and local time zone. The same `date_intent` option is available for room queries. New tonight searches resolve again after local midnight; quote pagination retains its original dates until expiry.

Use a returned `hotel_id` with `get_room_rates` and the same returned dates, currency and occupancy. Returned offers include a `booking_url` when a safe provider link is available. A Brek link resolves the B2B hotel to Brek's distinct inventory ID before handoff. Search/room pagination uses `quote_session_id` and `cursor`; quote sessions expire after 10 minutes. The consumer response has `channel: "consumer_connector"` and `billing.model: "affiliate"`, rather than a developer usage receipt.

The portable [plugin package](/downloads/hoteluse-plugin.zip) is prepared for host installation and platform review. This endpoint is available independently; it is not evidence of an approved listing in either platform's directory. Hosts without MCP Apps UI can use the structured results and links.

Consumer traffic has separate, configurable service capacity and upstream protections; it does not use developer account rate limits or credit allowances. Developer API usage is billed separately from the consumer connector.

## Search filters

Consumer search accepts the same hotel_filters and rate_filters as the HTTP API. Star classification, normalized guest score, review count, facilities, property types, distance and whole-stay budgets have explicit fields. Hotel star classifications use Expedia metadata when one unambiguous Expedia mapping is available; other hotels retain the catalog classification. `star_classification` reports the source, verification status and check time. Provider classifications may differ. Missing provider classifications stay unknown, and guest-review scores never fill a missing star rating. HotelUse caches classification facts for up to seven days independently of live prices; it never changes source B2B records. Read [Filters & sorting](/docs/filters.html) before constructing a request. Preserve desired rate_filters in room follow-ups; search_quote_session_id inherits omitted dates, occupancy, currency, language, residency, providers and rate_filters from the exact search; explicit arguments override inherited values, except device must remain unchanged. Send rate_filters: {} to clear inherited rate constraints.

## Device and mobile rates

Developer price calls accept `context.device`; consumer MCP price tools accept flat `device`. Allowed values are `desktop` (default), `mobile_web` and `mobile_app`. Device selection is automatic for consumer MCP clients. ChatGPT's optional `_meta["openai/userAgent"]` supplies a best-effort traveler hint, like the existing country/locale metadata. A recognized client hint takes priority over a model-supplied desktop/mobile-web guess. If tool metadata is absent, the embedded app can use MCP Apps `hostContext.platform` / `userAgent` or the actual browser user agent. A late mobile hint refreshes an initial unknown-device quote at most once and updates model context. Missing or unrecognized signals default to desktop. Server HTTP headers, window width and destination are not device signals. Users are never asked to select a device. These hints do not authorize restricted rates, and a native ChatGPT/Claude mobile app does not automatically qualify as an approved HotelUse native-app integration. Native-app rates require an approved app integration. Mobile rates are not always cheaper and are only for eligible travelers.



| Device | Expedia source | Booking platform | Agoda platform |
| --- | --- | --- | --- |
| desktop | browser | desktop | Desktop |
| mobile_web | browser | mobile | MobileWeb |
| mobile_app | mobileapp | mobile | MobileApp |



For example, add `"device": "mobile_web"` inside a developer request's `context`, or to consumer tool arguments. Copy a consumer search's `search_session_id` into the room call's optional `search_quote_session_id`. The server inherits omitted dates, room occupancy, currency, language, residency, providers and rate filters from that exact search, even if current client metadata changes. For example, a 1-adult search stays 1 adult when the room call supplies only hotel_id and search_quote_session_id. Explicit arguments can change a new quote, except its device must remain unchanged. An explicit empty rate_filters object clears inherited rate constraints. The reference expires with the 10-minute quote; conflicting device changes are rejected. Otherwise reuse the returned device context for room queries and booking. Quote-session pagination preserves the original context and cannot switch devices. Cached desktop and mobile results are separate. Provider-generated booking links are preserved; their rates still require an eligible device at the provider. Do not present an app rate as universally bookable. Expedia mobile-web requests use browser rates, not app rates. Brek wholesale source selection and markup are unchanged.

## Currency and language

Explicit `context.currency`, `context.locale` and `context.market.residency_country` win on the developer tools. Consumer tools use flat `currency`, `locale` and `residency_country` arguments. When host metadata is absent, Claude may supply optional `user_locale` and `user_location_country` from its traveler context. Trusted host hints take priority over these fallback hints; explicit traveler choices still win. These fields never set the hotel destination or its local stay dates. For MCP calls, omitted preferences may be filled from client metadata: `openai/locale` (then `webplus/i18n`) and `openai/userLocation.country`. Currency follows visitor country, then locale region, then USD. Residency uses visitor country when provided, otherwise US. Do not infer traveler preferences from the hotel destination. HTTP requests without these fields continue to default to USD/US.

Booking and Agoda receive the requested currency. Our current Expedia key is bound to the US point of sale, so Expedia is queried and booked in USD. Other Expedia display currencies are reference estimates using a fresh exchange snapshot, with no added FX premium. Room links preserve the supplier-generated room/rate-plan URL. Brek is also queried and booked in USD; other display currencies use the fresh Brek exchange feed and its 1% FX premium on the prepaid amount. Local hotel fees retain their original amount and currency, without that premium. currency_conversion records the source currency, original full-stay total (source_stay_total), original prepaid amount (source_prepaid_total), reported pay-at-property amount (source_pay_at_property), booking_currency, rate, premium, timestamp and expiry. Converted amounts are reference estimates; they do not promise checkout or card settlement in that display currency. Local fees can still be collected in their original currency. Expired or missing FX fails the provider explicitly. No USD amount is relabeled as JPY. Provider content languages vary. Unsupported provider locales fall back to English; static records and room names can retain their source language. UI labels currently support English, Chinese, Japanese and Spanish, with localized amount formatting.

## Developer tools



| Tool | Reference |
| --- | --- |
| `search_hotels` | [Search hotels](/docs/api/search-hotels.html) |
| `get_hotel` | [Get hotel information](/docs/api/get-hotel.html) |
| `get_room_rates` | [Get room rates](/docs/api/get-room-rates.html) |



## Official JavaScript SDK example

Install `@modelcontextprotocol/sdk` from npm in your application. This example lists tools and reads a real hotel record; the tool call consumes the same account data units as HTTP.



```javascript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const client = new Client({ name: 'my-hotel-agent', version: '1.0.0' });
try {
  await client.connect(new StreamableHTTPClientTransport(new URL('https://www.hoteluse.dev/mcp'), {
    requestInit: { headers: { Authorization: 'Bearer ' + process.env.HOTELUSE_API_KEY } }
  }));
  console.log((await client.listTools()).tools.map(tool => tool.name));
  const result = await client.callTool({
    name: 'get_hotel', arguments: { hotel_id: 'hu_69450c903d9c06226f1ce17b' }
  });
  if (result.isError) throw new Error(JSON.stringify(result));
  console.log(result.structuredContent.data.hotel);
} finally { await client.close(); }
```



## MCP result envelope

Tool results include the HTTP result in `structuredContent` and a text representation in `content`. Protocol request IDs are separate from the HotelUse `request_id` in that structured envelope. Inspect `isError` before reading data. HTTP and MCP share pricing, access caps and rate limits. Result pages use the same tool with `quote_session_id` and `cursor`.

[Quickstart](/docs/quickstart.html) · [Agent setup guide](/agent.md).

---

Canonical: https://www.hoteluse.dev/docs/mcp.html
Source: https://www.hoteluse.dev/docs/mcp.md