NuVista Haven MCP Server

NuVista Haven MCP server ("AI front desk")

Model Context Protocol server that lets AI assistants answer, from live data:

• what NuVista Haven properties exist → search_properties
• what's free on given dates → check_availability (Hospitable calendars)
• what's the price → get_quote (nightly rates × nights + cleaning fee)
• where to book direct → getbookinglink (nuvistahaven.com)

Security model

HTTP verb (GET) against an allow-list of read paths (/user, /properties, /reservations). There are no POST/PUT/PATCH/DELETE methods anywhere — even though the token may carry write scopes, this code cannot mutate anything in Hospitable.

• Read-only by construction. hospitable_client.py exposes exactly one

from the HOSPITABLEAPITOKEN environment variable. It is never hardcoded, never logged, never written to disk.

• Token handling. The Hospitable Personal Access Token is read ONLY

Setup

cd ~/workspace/nuvista-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

Run

# local testing (stdio)
HOSPITABLE_API_TOKEN=<token> ./venv/bin/python server.py

# public hosting (Streamable HTTP)
HOSPITABLE_API_TOKEN=<token> ./venv/bin/python server.py --http --port 8000

Tests (mocked, no token needed)

./venv/bin/python test_server.py

One-time: map Hospitable property IDs

properties.py holds the 12 canonical properties with best-effort Hospitable name guesses (7 strong, 5 guesses — see guessconfidence). With a live token, run the matcher and confirm each mapping by hand, then fill in hospitableid per property:

HOSPITABLE_API_TOKEN=<token> ./venv/bin/python - <<'EOF'
import sys; sys.path.insert(0, '.')
from hospitable_client import HospitableClient
from logic import build_id_mapping
import json
print(json.dumps(build_id_mapping(HospitableClient()), indent=2))
EOF

Entries with "needshumanconfirm": true must be verified before use — checkavailability/getquote refuse to run for unmapped properties.

Known API gaps / assumptions (verify against live API)

(the Hospitable convention used by /reservations). If the endpoint ignores them, availability windows may be wrong — verify on first live run.

1. Calendar query params: getcalendar sends startdate/end_date

probes the property record for common fee shapes; if absent, the total is explicitly marked totalispartial_estimate: true — never silently zero.

1. Cleaning fee: not part of the calendar day object. get_quote

nuvistahaven.com is unverified, so getbookinglink returns the plain property URL (no fabricated params).

1. Booking-link date params: date pre-fill via query string on

calendar is the source of truth; reservations are not currently consulted.

1. Reservations cross-check: list_reservations is implemented but the

Files

• server.py — FastMCP server, 4 tools, stdio + Streamable HTTP
• logic.py — tool logic (testable without MCP)
• hospitable_client.py — GET-only Hospitable Public API v2 client
• properties.py — canonical 12-property registry + Hospitable mapping
• test_server.py — mock-based tests