Nomad Stays MCP Server - API Documentation

📖 Overview

The Nomad Stays MCP Server gives AI assistants like Claude and ChatGPT access to a curated database of remote-work-friendly and digital-nomad-friendly accommodations around the world via the Model Context Protocol (MCP) — and, for authenticated Trusted Stay Partners, lets their own AI assistant manage their listings directly.

Digital nomads and remote workers can also use their own AI assistant to explore Nomad Stays directly in conversation: create an account, then search for the right stay or experience by location, lifestyle, budget, amenities, or WiFi speed, and check room availability for their dates — then head to nomadstays.com to complete booking and payment.

Trusted Stay Partners can 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.

👥 Nomads & Stay Partners

What each type of user can do

🤖 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 Nomad Stays in real time

👥 What You Can Do

This MCP server serves two kinds of users. Pick the column that matches you:

🧳 Digital Nomads & Remote Workers

Anyone looking for a place to stay and work from.

Create a Nomad Stays account from within the conversation
Search stays by country, continent, city, lifestyle, budget, amenities, or WiFi speed
Check room availability for specific dates, or find the nearest available dates
Get a live price quote for a stay package, then book it and receive a hosted checkout link to pay
Check the payment status of a booking by PNR
List all of their own past and upcoming bookings
Search the Help Center for answers, or browse help categories

🏡 Trusted Stay Partners

Anyone who lists or wants to list a property with Nomad Stays.

Start, save, and submit a new Stay, Experience, or Coworking application
Pay the application fee and check its payment status
List their own Stays and check each one's listing-completion score
View and update Stay details, rooms, pricing packages, and organisational data
Manage Stay and room photos — upload, delete, and reorder
View and update their business profile
Look up reference data (room types, facilities, currencies, cancellation policies, etc.) needed to fill in the above

Trusted Stay Partner tools require connecting an AI assistant with a Nomad Stays login — see Setting Up Your AI Assistant as a Trusted Stay Partner below.

🤖 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 Nomad Stays 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 Nomad Stays 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 Nomad Stays, 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 Nomad Stays login, no waiting on the Nomad Stays 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 Nomad Stays 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 Nomad Stays 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 Operator Information 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)
👤 Account Tools
`signupNomadStaysAccount`	Create a new Nomad Stays account for someone who doesn't have one yet. Account stays inactive until the person clicks the confirmation link emailed to them — no session or token is returned	firstName, lastName, email, telephone, password, acceptGdpr
📅 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
🧳 Stay Booking Tools (require an MCP agent token with the "bookings" scope)
`quoteStayBooking`	Get a server-computed price and availability quote for booking a Stay package on the caller's own behalf. Price is always re-derived from the package's actual pricing tiers. Returns a quoteId valid for about 15 minutes	packageId, checkIn, checkOut, rooms (optional), adults (optional), children (optional), pets (optional)
`bookStay`	Create a real booking from a quoteId returned by quoteStayBooking, and return a hosted checkoutUrl. The member must open the checkoutUrl themselves to pay — no card details ever pass through the assistant	quoteId, contactName (optional), contactEmail (optional), contactPhone (optional), specialRequest (optional)
`getBookingStatus`	Check a Stay booking's real payment status by PNR. Status is always freshly re-verified against Airwallex directly if not already confirmed paid	pnr
`listMyBookings`	List all Stay bookings owned by the caller's own account, most recent first. Each booking includes needsAction: true if it's still unpaid, with a ready-to-use checkoutUrl	None
📚 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
`getMyStayOnboardingStatus`	Get the Stay's six "Listing Completion" scores (Stay Details, Availability, Rooms, Packages, Wi-Fi, Operator Information) plus an overall completion percentage. Wi-Fi is a test-freshness score, not a speed rating; Operator Information is a status label ("Open"), not a real percentage	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 Stay Dashboard 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 personal, 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/PNG/WebP format, size (up to 20MB), minimum resolution (1920×1080 landscape, or 1080×1350 portrait for the "host" area), and is downscaled to fit 2560×1440 and re-encoded as WebP 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)
💳 Product Payment Tools (require an MCP agent token)
`getProductInfo`	Look up a product's price and purchasability — product 8 (Stay Application) or product 9 (Experience Application), both EUR 39	productId
`purchaseProduct`	Start a purchase on the caller's own behalf. Returns a checkoutUrl the member must open and pay themselves, or resolves immediately as "waived" if the caller already qualifies for a fee waiver	productId (8 for Stay Application, 9 for Experience Application), applicationId (optional — correlates the payment to the application)
`getPurchaseStatus`	Check whether a purchase has been paid — only ever reports "paid" after a fresh server-side check against the payment provider	saleId
📋 Stay Application Tools (require an MCP agent token)
`listStayApplications`	List the caller's Stay Applications (draft and submitted), each with a nextAction hint	None
`getStayApplication`	Get the full current state of one Stay Application, including nextAction and (if incomplete) missingFields	applicationId
`createStayApplication`	Start a new Stay Application. Any fields can be supplied now or filled in later via saveStayApplication	All fields optional — see applicant, address, stay, and property fields below
`saveStayApplication`	Update any subset of fields on an existing, not-yet-submitted application	applicationId, plus any of the createStayApplication fields to change
`submitStayApplication`	Submit a completed application for human review. Rejects with missingFields if incomplete, or a 409 if the Application Fee (product 8) isn't paid/waived yet	applicationId
🧭 Experience Application Tools (require an MCP agent token)
`listExperienceApplications`	List the caller's Experience Applications (draft and submitted), each with a nextAction hint	None
`getExperienceApplication`	Get the full current state of one Experience Application, including nextAction and (if incomplete) missingFields	applicationId
`createExperienceApplication`	Start a new Experience Application. Experiences must run a minimum of 4 days (enforced server-side)	All fields optional — see applicant, address, and experience-detail fields
`saveExperienceApplication`	Update any subset of fields on an existing, not-yet-submitted application	applicationId, plus any of the createExperienceApplication fields to change
`submitExperienceApplication`	Submit a completed application for human review. Rejects with missingFields if incomplete, or a 409 if the Application Fee (product 9, NOT product 8) isn't paid/waived yet	applicationId
🏢 Coworking Application Tools (require an MCP agent token)
`listCoworkingApplications`	List the caller's Coworking Applications (draft and submitted), each with a nextAction hint	None
`getCoworkingApplication`	Get the full current state of one Coworking Application, including nextAction and (if incomplete) missingFields	applicationId
`createCoworkingApplication`	Start a new Coworking Application. Much simpler than Stay/Experience: no VAT/tourism/business-model rules and no Application Fee at all — nextAction goes straight to submit once coworkingName, applicantName, applicantEmail, city and country are present	All fields optional — coworkingName, applicantName, applicantEmail, telephone, address, city, country, website
`saveCoworkingApplication`	Update any subset of fields on an existing, not-yet-submitted application	applicationId, plus any of the createCoworkingApplication fields to change
`submitCoworkingApplication`	Submit a completed application for human review. Rejects with missingFields if incomplete. There is no Application Fee for Coworking, so this never returns a payment-required response	applicationId

📊 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 Nomad Stays. Two integration modes are available:

Option 1 — MCP Server (Pull)

Run your own MCP server that exposes a get_allocation tool. Nomad Stays 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 — Nomad Stays sends Authorization: Bearer <key> on every request

Option 2 — Webhook Push Recommended

Push availability changes to Nomad Stays the moment they occur — no waiting for the next poll cycle. When webhook push is enabled, Nomad Stays 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 Nomad Stays 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

👥 Nomads & Stay Partners

🤖 MCP Protocol

💡 Examples

🆘 Help Center

📊 Data Model

🏨 Supplier Integration

👥 What You Can Do

🧳 Digital Nomads & Remote Workers

🏡 Trusted Stay Partners

🤖 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