API / MCP docs

Property Passports for your AI service

Search public Property Passports. Retrieve the facts. Send guests to the property's published website or booking route.

Ordinary read-only access is free and keyless. Use MCP, REST, JSON, Markdown or JSON-LD. No account or developer key is needed to get started.

Try REST search View OpenAPI

Connect with MCP

Endpoint: https://openstays.ai/api/mcp

Transport: Streamable HTTP. Supports modern MCP 2026-07-28 and initialization-based MCP 2025-11-25, 2025-06-18 and 2025-03-26.

Two read-only tools: search_stays and get_property_passport.

Modern clients use standard per-request metadata. Initialization-based clients use initialize followed by notifications/initialized. No OpenStays-specific handshake is needed.

Claude Code

Add the remote HTTP server:

claude mcp add --transport http openstays https://openstays.ai/api/mcp

Check the connection with /mcp in Claude Code.

Gemini CLI

Add this entry to your Gemini CLI settings.json:

{
  "mcpServers": {
    "openstays": {
      "httpUrl": "https://openstays.ai/api/mcp"
    }
  }
}

Merge it with any existing mcpServers entries. Check the connection with gemini mcp list.

OpenAI Responses API

Include this tool in your Responses API request:

{
  "type": "mcp",
  "server_label": "openstays",
  "server_url": "https://openstays.ai/api/mcp",
  "allowed_tools": ["search_stays", "get_property_passport"],
  "require_approval": "always"
}

Keep your application's approval controls. OpenStays access is free; your AI provider's usual usage charges may apply.

Compatibility checks

We test the official MCP TypeScript clients against both supported protocol eras. These setup examples follow provider documentation. SDK checks are not proof that every Claude, OpenAI or Gemini product has been tested. We do not claim universal compatibility.

Search, retrieve, follow the published route

1. Search within one country

Choose one country. Town, region, bedrooms, guest capacity and property type are optional refinements.

Search public Property Passports within one country or territory. Country alone is enough. Town, region, bedrooms, guest capacity and property type are optional refinements. Returns up to 10 matching accommodation units, preferring different Property Passports. No catalogue export, total count or pagination. These tools do not check live prices or availability.

curl --fail-with-body 'https://openstays.ai/api/v1/properties?q=Portugal'

REST returns matching units in data. Each result includes profile_url and unit_id. MCP search_stays uses destination instead of q:

{
  "name": "search_stays",
  "arguments": {"destination": "Portugal"}
}

Results are limited to 10 accommodation units, not necessarily 10 different properties. If refine_search is true in REST, or refineSearch is true in MCP, narrow your criteria.

2. Retrieve one Property Passport

Take a profile_url from your search result. For example, this public Property Passport is available as JSON:

curl --fail-with-body 'https://openstays.ai/stays/portugal/azenhas-do-mar/chalet-o-amorzinho/profile.json'

Or call get_property_passport with the exact canonical URL returned by search:

{
  "name": "get_property_passport",
  "arguments": {
    "profileUrl": "https://openstays.ai/stays/portugal/azenhas-do-mar/chalet-o-amorzinho"
  }
}

The JSON includes property_profile, accommodation_units, canonical_facts, fact_provenance, contact_routes and contact_route_states. Check the returned fields rather than assuming missing details.

3. Use the published website or booking route

Read contact_routes. Use only a returned public route and respect its routeType, contactPolicy and verificationStatus. A website route is not a confirmed booking or a live availability check. If no suitable public route is returned, do not invent one.

Prices are not live quotes. Dates and availability are not checked by these tools. Confirm them with the property through its published route.

Choose the format your agent needs

Append these paths to the canonical Property Passport URL:

/profile.json: application/json
/briefing.md: text/markdown
/schema.jsonld: application/ld+json

OpenAPI llms.txt Public Passport schema

Small searches. Public facts. Clear limits.

One country or territory is the broadest search scope. Worldwide, continent-wide, multi-country and wildcard searches are not supported. If a location is ambiguous, specify the country.

REST accepts country and q; MCP accepts country and destination. Supply a country or a destination that identifies one country among public Passport locations. Use country to disambiguate a town or region. minBedrooms accepts whole numbers from 0 to 100; minGuests accepts whole numbers from 1 to 200. These are minimums, not exact counts. A zero-bedroom minimum is not a studios-only filter. Unknown or duplicate REST parameters are rejected.

Request, burst and cumulative discovery limits apply across MCP and REST searches and Passport retrieval. Changing country, filters or client session does not reset these limits. Anonymous clients on the same network share an allowance. These safeguards limit bulk harvesting but cannot prevent all copying of public information.

There is no list-all tool, bulk export or recently-updated feed. Ordinary requests are anonymously metered. Optional developer keys provide higher quotas; searches stay bounded.

HTTP 400 means the request needs correcting. HTTP 401 means a supplied developer key is invalid. HTTP 429 means the rate limit has been reached. Back off rather than retrying in a tight loop.

MCP tool errors return isError: true. Read the text content for the reason. A missing Property Passport is not permission to use private or unpublished data.

Public access is not a blanket licence to republish customer content. Do not treat photos, descriptions or other customer material as OpenStays-owned content.