MCP server for AI agents

Server URL

Streamable HTTP in stateless mode. Any MCP-compatible client can add it with this URL:

https://www.beachvalencia.com/api/mcp

Available tools

Four read-only tools (search_availability, get_property_details, get_quote, get_policies) and one narrowly scoped write tool (create_booking_request) that creates a provisional booking with a 30-minute hold and returns a Stripe payment link. Charging ALWAYS happens on Stripe hosted at beachvalencia.com — the agent never charges the guest itself.

• search_availability — availability search for a date range and party size. Optional parameters: flexible_days (0–3, broadens the search by ±N days), budget_eur (max total price), zone ("beach" | "city" | "any") and min_bedrooms. Returns matches sorted by price plus up to 6 alternatives with the reason ("same dates, other category" / "2 days earlier, same category").
• get_property_details — description, capacity, m², photos, generic location and location_summary (travel time to the old town, tram, airport) for one category (G1..G6, G4B).
• get_quote — exact quote for a specific category, including deposit and cancellation summary.
• get_policies — check-in / check-out times, cancellation, deposit, Spanish traveller registration (SES.Hospedajes) and contact channels.
• create_booking_request — provisional booking with a 30-minute hold and a link to the intermediate web page (breakdown + explicit terms acceptance + Stripe). Public rate, no member discount, no coupon codes. The guest pays via Stripe; if the hold expires, the unit is released automatically.

Example prompts

• “Find me a two-bedroom apartment near the beach in Valencia for four people, 15 to 20 October, under 900 €.”
• “What’s the exact price for the largest apartment with pool from 24 December to 1 January for six people?”
• “What’s the cancellation policy if I book now and cancel one week before arrival?”
• “Perfect, book G4 from 22 to 27 May. I’m Ada Lovelace, ada@example.com, +34 612 345 678. I have read the cancellation policy.” → the agent confirms and sends `accepted_terms: true`; returns a payment link and `expires_at`.

What it does NOT do

• The agent does not charge: all payments go through Stripe Checkout hosted at beachvalencia.com. If an agent claims it can charge you directly, that is an agent error — the only valid payment URL is the one create_booking_request returns.
• It does not expose apartment codes (Axxx-N) or exact street addresses. The specific address and access instructions are sent by email once the reservation is confirmed.
• It does not validate or apply discount codes. If you have one, you enter it yourself on the website checkout.
• It does not access personal guest data or booking history.
• Prices returned are the public non-member rate with no discount code — exactly what you would pay at the website checkout.
• create_booking_request does NOT confirm the reservation nor charge: it only holds the unit for 30 minutes and returns the payment link. If the guest does not pay before expires_at, the hold is released and a new request is needed.

Data we log

Each call to the MCP server is logged anonymously for operational purposes, capacity planning and abuse detection: timestamp, tool invoked, query parameters (dates, party size, category), latency, result and — if the MCP client sends it — the client identifier itself (e.g. "claude.ai" or "chatgpt.com"). We do not store your IP address in clear text: it is turned into an irreversible hash (SHA-256 of IP + user-agent + an internal secret) used only to rate-limit sessions.

Limits and kill switch

• Up to 600 calls every 10 minutes per anonymous session (ip_hash).
• Global upstream cap to our booking engine: 120 calls per minute.
• Bursts above the limit return a readable error with retry_after_seconds; the server does not retry aggressively.
• Operational kill switch (MCP_ENABLED=false) returns HTTP 503 with a readable message without hitting the booking engine.

Public registry

We are listed in the official Model Context Protocol registry under the canonical name com.beachvalencia/booking. Namespace ownership is verified via DNS (Ed25519).

• Listing: https://registry.modelcontextprotocol.io/v0/servers?search=com.beachvalencia/booking

Legal and contact

Use of the server is subject to our Privacy Policy and Rental terms and conditions.

• Privacy: https://www.beachvalencia.com/privacidad
• Terms and conditions: https://www.beachvalencia.com/legal/condiciones
• Operational contact (bugs, incidents, feedback): reservas@beachvalencia.com