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. This API supports both the Model Context Protocol (MCP) for AI assistants and standard REST endpoints for direct integration.

🔌 API Endpoints

Browse available REST endpoints

🤖 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

🔌 REST API Endpoints

GET /health

Health check endpoint to verify the server is running.

Response

                    {
                    "status": "healthy",
                    "timestamp": "2025-01-15T10:30:00Z"
                    }

GET /api/stays

Retrieve a list of stays with optional filtering.

Query Parameters

countrycode (string) Optional

ISO 3166-1 alpha-2 country code (e.g., PT, ES, TH, MX, CO)

limit (integer) Optional

Maximum number of results to return (default: 10, max: 100)

Example Request

GET https://mcp.nomadstays.com/api/stays?countrycode=PT&limit=5

Example Response

                    {
                    "stays": [
                    {
                    "id": "stay_001",
                    "name": "Lisbon Co-living Hub",
                    "description": "Modern co-living space in the heart of Lisbon",
                    "country": "Portugal",
                    "countryCode": "PT",
                    "city": "Lisbon",
                    "pricePerMonth": 850,
                    "currency": "EUR",
                    "amenities": ["high_speed_wifi", "dedicated_desk", "kitchen", "coworking_space"],
                    "coordinates": {
                    "latitude": 38.7223,
                    "longitude": -9.1393
                    },
                    "images": ["https://example.com/image1.jpg"],
                    "bookingUrl": "https://www.nomadstays.com/stays/001"
                    }
                    ],
                    "count": 1,
                    "filters": {
                    "countryCode": "PT",
                    "limit": 5
                    }
                    }

GET /api/stays/cost-estimate

Estimate the total cost for a stay duration and optional country.

Query Parameters

durationDays (integer) Optional

Number of nights to estimate (default: 30)

countrycode (string) Optional

Country code or country name to narrow the estimate

currency (string) Optional

Target currency for the estimate (e.g., EUR, USD)

checkInDate (string) Optional

Optional start date (e.g., 2026-05-15 or May)

limit (integer) Optional

Maximum number of sample stays to return (default: 15)

Example Request

                    GET https://mcp.nomadstays.com/api/stays/cost-estimate?countrycode=ES&durationDays=30¤cy=EUR&limit=5

Example Response

                    {
                    "countryCode": "ES",
                    "durationDays": 30,
                    "currency": "EUR",
                    "estimatedCost": 1200,
                    "sampleStays": [ ... ]
                    }

GET /api/stays/{id}

Retrieve detailed information about a specific stay.

Path Parameters

id (string) Required

Unique identifier for the stay

Example Request

GET https://mcp.nomadstays.com/api/stays/stay_001

Example Response

                    {
                    "id": "stay_001",
                    "name": "Lisbon Co-living Hub",
                    "description": "Modern co-living space in the heart of Lisbon with fast WiFi...",
                    "longDescription": "Full detailed description with multiple paragraphs...",
                    "country": "Portugal",
                    "countryCode": "PT",
                    "city": "Lisbon",
                    "neighborhood": "Príncipe Real",
                    "pricePerMonth": 850,
                    "currency": "EUR",
                    "amenities": ["high_speed_wifi", "dedicated_desk", "kitchen", "coworking_space"],
                    "wifiSpeed": 200,
                    "coordinates": {
                    "latitude": 38.7223,
                    "longitude": -9.1393
                    },
                    "images": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"],
                    "bookingUrl": "https://www.nomadstays.com/stays/001",
                    "reviews": {
                    "average": 4.5,
                    "count": 42
                    }
                    }

🤖 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

Connect this server to Claude in just 2 steps:

Step 1: Open your Claude configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 2: Add this configuration:

                {
                    "mcpServers": {
                    "nomadstays": { 
                        "command": 
                        "npx", 
                        "args": [ "mcp-remote", 
                            "https://mcp.nomadstays.com/mcp", 
                            "--transport", 
                            "http-first"
                            ]  
                        }
                    }
                }
            

After adding, restart Claude. You can then ask: "Find me remote work stays in Portugal"

For Claude.ai Web Users

Go to Settings → Features → Model Context Protocol
Click "Add Server"
Enter server URL: https://mcp.nomadstays.com/mcp
Save and 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"
                    }
                    }
                    }

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)
`getStayCostEstimate`	Estimate total stay cost for a given duration and country without requiring a max budget	durationDays (optional, default 30), currency (optional), 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

📊 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"

Estimate stay cost for 1 month in Spain

                    curl "https://mcp.nomadstays.com/api/stays/cost-estimate?countrycode=ES&durationDays=30¤cy=EUR&limit=5"

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.

⚡ 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

🔌 API Endpoints

🤖 MCP Protocol

💡 Examples

🆘 Help Center

📊 Data Model

🔌 REST API Endpoints

Response

Query Parameters

Example Request

Example Response

Query Parameters

Example Request

Example Response

Path Parameters

Example Request

Example Response

🤖 Model Context Protocol (MCP)

🚀 Quick Setup for Claude

For Claude.ai Web Users

Integration

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)

Estimate stay cost for 1 month in Spain

Get specific stay details

Using with Claude (MCP)

🆘 Help Center Integration

🌍 Supported Countries

⚡ Rate Limits & Best Practices

🆘 Support