Nomad Stays MCP Server - API Documentation

📖 Overview

The Nomad Stays MCP Server provides access to a curated database of remote-work-friendly accommodations around the world via the Model Context Protocol (MCP), for use with AI assistants like Claude and ChatGPT.

New: Trusted Stay Partners can now connect their own AI assistant (see Setting Up Your AI Assistant as a Trusted Stay Partner below) so it can look up and update their Stay listings, rooms, pricing packages, organisational data, business profile, and photos on their behalf. See the 🔐 Owner-Scoped Lookup Tools and ✏️ Owner-Scoped Write Tools sections below.

🤖 MCP Protocol

Use with AI assistants like Claude

💡 Examples

See sample requests and responses

🆘 Help Center

Access help articles and support via MCP tools

📊 Data Model

Understand the stay object structure

🏨 Supplier Integration

Push your availability to NomadStays in real time

🤖 Model Context Protocol (MCP)

This server implements the MCP specification, allowing AI assistants to discover and use stays data naturally in conversation. Now includes Help Center tools for searching and retrieving support articles directly via MCP.

🚀 Quick Setup for Claude Desktop

Connect this server to Claude Desktop in a couple of clicks — no config file editing needed:

Step 1: In Claude Desktop, go to Settings → Connectors and click Add custom connector.

Step 2: Enter the server URL:

                https://mcp.nomadstays.com/mcp
            

Claude Desktop will open a sign-in prompt — log in with your NomadStays account and click Allow. You can then ask: "Find me remote work stays in Portugal"

For Claude.ai and ChatGPT Web Users

Go to Settings → Connectors (Claude.ai) or the equivalent connector/MCP settings in ChatGPT
Click "Add custom connector" / "Add Server"
Enter server URL: https://mcp.nomadstays.com/mcp
Complete the NomadStays sign-in prompt and click Allow, then start using it in conversations!

POST / MCP Protocol

MCP protocol endpoint for AI assistant integration.

Integration

To use this server with Claude or other MCP-compatible assistants, configure your MCP client with:

                    {
                    "mcpServers": {
                    "nomadstays": {
                    "url": "https://mcp.nomadstays.com/mcp"
                    }
                    }
                    }

🔑 Setting Up Your AI Assistant as a Trusted Stay Partner (Step-by-Step)

If you manage a Stay on NomadStays, you can let your own AI assistant read and update your listing, rooms, prices, and photos for you. You don't need to know how to code — it's a self-service connection using your NomadStays login, no waiting on the NomadStays team. This works with ChatGPT, Claude.ai, and Claude Desktop's Connectors.

Step 1 — Turn on two-factor authentication

Before you can connect an agent, your NomadStays account needs two-factor authentication (2FA) turned on. This protects your listing in case access is ever lost or shared. Go to Enable two-factor authentication and follow the on-screen instructions if you haven't already.

Step 2 — Add the connector in your AI assistant

In ChatGPT or Claude.ai, add a new connector/MCP server pointing at https://mcp.nomadstays.com/mcp. In Claude Desktop, add it under Settings → Connectors instead. Your assistant will open a NomadStays sign-in and authorization prompt — log in and click Allow. Access is granted immediately, and you can review or revoke connected agents any time from your Stay profile page.

Step 3 — Try it out

Start a new conversation and ask something like: "List my Stays" or "Show me the current price packages on my Stay." If your assistant responds with your real listing data, it's working.

Questions? Contact us.

Available Tools

Tool Name	Description	Parameters
🆘 Help Center Tools
`searchHelpCenter`	Search help articles by keyword or question	query (string), category (optional string), limit (optional number)
`getHelpCenterArticle`	Retrieve a specific help article by ID	id (string)
`listHelpCenterCategories`	List all available help center categories	None
🔍 Search & Filter Tools
`getStaysByCountry`	Search stays by 2-letter country code or partial country name	countrycode (string), limit (number)
`getStaysByContinent`	Filter stays by continent (Europe, Asia, Africa, etc.)	continent (string), limit (number)
`getStaysByLocation`	Search across City, State, location name, country, and description	location (string), limit (number)
`getStaysByLifestyle`	Find stays by lifestyle category	lifestyle (string), limit (number)
`getStaysByBudget`	Search stays within budget and duration with FX conversion	durationDays, maxPrice, currency, countryCode (optional), checkInDate (optional), limit (optional)
`getStaysByAmenities`	Search stays by amenities with fuzzy matching	amenities (array), matchType (optional), minWifiSpeed (optional), limit (optional)
`getStaysByWiFiSpeed`	Find all stays with WiFi download speed greater than 10Mbps.	minWiFiDownloadSpeed (number), limit (number)
`getStayByID`	Get detailed information about a specific stay	id (number)
📅 Availability & Booking Tools
`checkStayAvailability`	Check room availability for specific dates	stayId, checkIn, checkOut, roomType (optional)
`findNearestAvailability`	Find nearest available dates near preferred check-in	stayId, preferredCheckIn, minLengthOfStay, maxLengthOfStay (optional), searchWindowDays (optional)
`getAvailabilityByMonth`	Get availability calendar for a specific month	stayId, year, month, minLengthOfStay
`getRoomAvailability`	Check availability for a specific room	roomId, checkIn, checkOut
📚 Reference & Metadata Tools
`getAllLifestyles`	Retrieve all available lifestyle categories	None
`getAllAmenities`	Retrieve all available amenities in the system	None
`getRoomAmenities`	Get amenities for a specific room	roomId
🔐 Owner-Scoped Lookup Tools (require an MCP agent token)
`getMyStays`	List all Stays owned by the account bound to the MCP agent token	None
`getMyStayDetail`	Get a Stay's current title, description, and listed status	stayId
`getMyStayRooms`	List all rooms configured on a Stay	stayId
`getMyStayPackages`	List all pricing packages and price tiers on a Stay	stayId
`getMyStayOrganisationalData`	Get a Stay's address, check-in/out policy, and cancellation policy	stayId
`getMyStayContacts`	Get a Stay's public-facing contact details	stayId
`getMyStayFacilities`	Get a Stay's facility checkboxes for a given facility group	stayId, group
`getMyStayPhotos`	List a Stay's photos by area (listing, main, workspace, host)	stayId
`getMyBusinessProfile`	Get the Trusted Stay Partner account's business profile (legal name, VAT/registration numbers)	None
`getRoomTypeOptions`	List valid room types for a Stay — boutique Stays get Boutique1–Boutique6 only, standard Stays get ordinary room types	stayId
`getRoomFacilityOptions`	List all room-level facility options	None
`getCurrencyOptions`	List valid currencies for package pricing	None
`getBusinessModelOptions`	List valid values for a Stay's business model — read-only (not editable via MCP or the host UI itself), but the value it holds determines the sellPrice formula and whether advertisingEndpoint applies to packages	None
`getFacilityGroups`	List all facility groups a Stay's facilities are organised into	None
`getStayTypeOptions`	List valid values for a Stay's main accommodation type	None
`getCountryOptions`	List valid countries, with names and 2-letter codes	None
`getCancellationPolicyOptions`	List valid cancellation policy values	None
`getAdditionalInformationOptions`	List valid values for a picklist field (e.g. Pets Allowed, Children Allowed, Parking) used in organisational data	filterName
✏️ Owner-Scoped Write Tools (require an MCP agent token)
`updateStayDetail`	Update a Stay's title and/or description	stayId, title (optional), description (optional)
`createStayRoom`	Create a new room on a Stay	stayId, roomTitle, roomDescription (optional), beds (optional), maxPerson (optional), and more
`updateStayRoom`	Update an existing room on a Stay	stayId, roomId, plus any room fields to change
`deleteStayRoom`	Soft-delete a room from a Stay	stayId, roomId
`createStayPackage`	Create a new pricing package on a Stay, optionally with initial price tiers	stayId, packageName, prices (optional array), and more
`updateStayPackage`	Update a pricing package. Supplying prices replaces ALL price rows for that package	stayId, packageId, plus any package/price fields to change
`deleteStayPackage`	Permanently delete a pricing package and all its price tiers (hard delete, unlike rooms)	stayId, packageId
`updateStayOrganisationalData`	Update a Stay's address, check-in/out policy, pets/children/parking, cancellation policy	stayId, plus any organisational fields to change
`updateStayContacts`	Update a Stay's public-facing contact details	stayId, plus any contact fields to change
`updateStayFacilities`	Set the full list of selected facility checkboxes for one facility group on a Stay. Anything not included is unchecked	stayId, group, facilityDetailIds (full replacement list)
`updateHostBusinessProfile`	Update the Trusted Stay Partner account's business profile. Never touches bank or tax-ID details	businessName, vatNumber, businessNumber, entityAccount — all optional
`uploadStayPhoto`	Upload a photo to a Stay's listing, main, workspace, host, or room photo area. Supply a public https:// URL or base64-encoded bytes. Every photo is validated for JPEG format, size, minimum resolution (1920×1080 landscape, or 1080×1920 portrait for the "host" area) and is re-encoded server-side before storage	stayId, area, url or base64, roomId (required when area is "room")
`deleteStayPhoto`	Delete a Stay-level photo by area and filename	stayId, area, fileName
`reorderStayPhotos`	Reorder a Stay's photos within a given area	stayId, area, fileNames (full ordered list)
`deleteRoomPhoto`	Delete a room-level photo by area and filename	stayId, roomId, roomArea, fileName
`reorderRoomPhotos`	Reorder a room's photos within a given area	stayId, roomId, roomArea, fileNames (full ordered list)

📊 Data Model

Stay Object

Field	Type	Description
`id`	string	Unique identifier for the stay
`name`	string	Name of the accommodation
`description`	string	Short description of the stay
`country`	string	Full country name
`countryCode`	string	ISO 3166-1 alpha-2 country code
`city`	string	City name
`priceRange`	string	Weekly price range (e.g., "From EUR 250 per week")
`priceCurrency`	string	Currency code (e.g., EUR, USD)
`amenities`	array	List of available amenities
`WiFiDownloadSpeed`	number	WiFi download speed in Mbps (optional)
`WiFiUploadSpeed`	number	WiFi upload speed in Mbps (optional)
`location_name`	string	Location name from Location table
`location_country`	string	Location country from Location table
`PetsAllowed`	boolean	Whether pets are allowed
`coordinates`	object	GeoLat and GeoLng coordinates
`bookingUrl`	string	URL to book the stay

Common Amenities

Standard amenity identifiers used in the API:

high_speed_wifi - High-speed internet connection
dedicated_desk - Dedicated workspace
kitchen - Full kitchen access
coworking_space - On-site coworking space
gym - Fitness facilities
pool - Swimming pool
parking - Parking available
pet_friendly - Pets allowed

💡 Usage Examples

Find stays in Portugal

curl "https://mcp.nomadstays.com/api/stays?countrycode=PT&limit=10"

Search the Help Center for WiFi questions

                    # Using MCP tool: searchHelpCenter
                    # Example: Find help articles about WiFi
                    {
                        "tool": "searchHelpCenter",
                        "parameters": {
                            "query": "WiFi"
                        }
                    }
                

Find stays in Europe

                    # Using MCP tool: getStaysByContinent
                    # Searches by continent name

Find stays in Paris or near beaches

                    # Using MCP tool: getStaysByLocation
                    # Searches across city, state, location name, and descriptions

Get all stays (no filter)

curl "https://mcp.nomadstays.com/api/stays?limit=50"

Get specific stay details

curl "https://mcp.nomadstays.com/api/stays/stay_001"

Using with Claude (MCP)

Once configured, simply ask Claude naturally:

"Can you help me find remote work accommodations in Thailand?"

"Show me stays in Paris with good WiFi"

"I want to stay near a beach in Europe"

🆘 Help Center Integration

The MCP server now provides direct access to the Nomad Stays Help Center. You can search for help articles, retrieve specific articles by ID, and list available categories using the new MCP tools. This enables AI assistants and users to get support and answers to common questions programmatically.

Use searchHelpCenter to find articles by keyword or question.
Use getHelpCenterArticle to fetch a specific article by its ID.
Use listHelpCenterCategories to browse available help topics.

For manual browsing, visit the Nomad Stays Help Center.

🌍 Supported Countries

Currently available country codes (examples):

PT - Portugal

ES - Spain

TH - Thailand

MX - Mexico

CO - Colombia

ID - Indonesia

GR - Greece

IT - Italy

Note: Use the API to discover the complete list of available countries.

🏨 Supplier / PMS Integration

If you operate a property management system (PMS) or channel manager, you can sync your availability calendar directly with NomadStays. Two integration modes are available:

Option 1 — MCP Server (Pull)

Run your own MCP server that exposes a get_allocation tool. NomadStays polls it hourly and writes the returned availability into our booking system automatically.

Expose your server over HTTPS (Streamable HTTP POST /mcp preferred)
Implement the get_allocation tool — takes property_id, start_date, end_date
Return a ranges array with only reduced-allocation date periods
Secure with a Bearer token — NomadStays sends Authorization: Bearer <key> on every request

Option 2 — Webhook Push Recommended

Push availability changes to NomadStays the moment they occur — no waiting for the next poll cycle. When webhook push is enabled, NomadStays reduces polling to a once-daily safety check.

POST /api/mcp/availability-push/{stayId} Base: https://www.nomadstays.com

Authentication

Sign every request with HMAC-SHA256 using the shared secret NomadStays provisions during onboarding:

X-NomadStays-Signature: sha256=<lowercase-hex>

# Python example
import hmac, hashlib
sig = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()

Payload

{
  "room_id": "your-room-identifier",
  "ranges": [
    { "start_date": "2026-07-10", "end_date": "2026-07-15", "allocation": 0 },
    { "start_date": "2026-08-01", "end_date": "2026-08-05", "allocation": 1 }
  ]
}

Only include date ranges where availability is reduced from normal. Send "ranges": [] to clear all blocks.

Response Codes

Status	Meaning
`200 OK`	Accepted — `{"received": true, "reductions": N}`
`401`	Missing or incorrect signature
`404`	Stay or room not found

For the full integration specification including code examples in Python and Node.js, please contact us to begin onboarding.

⚡ Rate Limits & Best Practices

Rate limit: 100 requests per minute per IP
Use appropriate limit parameters to avoid over-fetching
Cache responses when possible to reduce API calls
Always check the health endpoint before making bulk requests

🆘 Support

For questions, issues, or feature requests:

Contact: Contact Page

🏡 Nomad Stays MCP Server

📖 Overview

🤖 MCP Protocol

💡 Examples

🆘 Help Center

📊 Data Model

🏨 Supplier Integration

🤖 Model Context Protocol (MCP)

🚀 Quick Setup for Claude Desktop

For Claude.ai and ChatGPT Web Users

Integration

🔑 Setting Up Your AI Assistant as a Trusted Stay Partner (Step-by-Step)

Step 1 — Turn on two-factor authentication

Step 2 — Add the connector in your AI assistant

Step 3 — Try it out

Available Tools

📊 Data Model

Stay Object

Common Amenities

💡 Usage Examples

Find stays in Portugal

Search the Help Center for WiFi questions

Find stays in Europe

Find stays in Paris or near beaches

Get all stays (no filter)

Get specific stay details

Using with Claude (MCP)

🆘 Help Center Integration

🌍 Supported Countries

🏨 Supplier / PMS Integration

Option 1 — MCP Server (Pull)

Option 2 — Webhook Push Recommended

Authentication

Payload

Response Codes

⚡ Rate Limits & Best Practices

🆘 Support