Documentation

Domus Aedes connector

A remote MCP server that puts the Domus Aedes portfolio inside ChatGPT, Claude and Claude Code. One endpoint, three tools, one interactive view.

• Overview
• Connect
• Tools
• search_properties
• get_property
• request_property_details
• Interactive view
• Data & freshness
• Test it
• Plugin bundles
• Support

Overview

The connector turns a natural-language brief (“a villa to buy in Marbella under €3M with sea views”) into a search over Domus Aedes’ own listings: properties for sale and long-term rentals on the Costa del Sol, and short stays on the Costa del Sol, in Catalonia, Marrakech and Casablanca. It is deterministic — no model runs inside the server — and it never invents a property.

The product rule: every search returns up to six best matches, whether more exist, and up to four refinement suggestions. There is no pagination parameter. When a person wants more, the assistant offers to narrow down (budget, area, bedrooms, features) and searches again.

The privacy rule: nothing in this API states how many properties Domus Aedes has — no totals, no per-area or per-type counts, no “N of M”. The portfolio is curated and changes weekly; the connector answers a brief, it does not enumerate the catalogue.

Connect

ChatGPT

Plugins → search “Domus Aedes” → Connect. Start your prompt with “Domus Aedes”. Developer mode: Settings → Security and login → Developer mode, then add the endpoint above as a public MCP server.

Claude

Settings → Connectors → Add custom connector → name “Domus Aedes”, URL https://ai.domusaedes.com/mcp. No OAuth.

Claude Code

/plugin marketplace add moss1337/domus-aedes-plugin
/plugin install domus-aedes@domus-aedes

Any other MCP client: add an HTTP server with the URL above.

Tools

Every tool returns structuredContent (the JSON documented below) and a plain-text content block that says the same thing, so hosts without the interactive view still work.

search_properties

Result

{
  "view": "results",
  "intent": "buy",
  "language": "en",
  "query_summary": "Homes to buy in Marbella under €3M",
  "results": [
    {
      "ref": "DA-CAMPANA",
      "title": "Refurbished Penthouse with Jacuzzi & Terrace — La Campana",
      "price_label": "€749,000",
      "price_value": 749000,
      "city": "Marbella", "area": "La Campana", "country": "ES",
      "type": "penthouse", "bedrooms": 3, "bathrooms": 2, "built_area": 240, "max_guests": null,
      "features": ["jacuzzi", "terrace", "garage"],
      "summary": "…",
      "image": "https://sales.domusaedes.com/uploads/yM22xXrcHG.webp?w=960",
      "images": ["…"],
      "url": "https://sales.domusaedes.com/sales/properties/DA-CAMPANA",
      "location": { "lat": 36.4942, "lng": -4.9768, "approx": true }
    }
  ],
  "has_more": true,
  "refinements": [
    { "label": "Under €2M", "params": { "budget_max": 2000000 } },
    { "label": "Nueva Andalucía only", "params": { "location": "Nueva Andalucía" } }
  ],
  "notes": [],
  "contact": { "phone": "+34 930 34 46 10", "whatsapp": "https://wa.me/34930344610", "email": "contact@domusaedes.com", "website": "https://domusaedes.com" },
  "applied": { "intent": "buy", "location": "Marbella", "budget_max": 3000000, "language": "en" }
}

results is always ≤ 6. has_more says whether more listings matched than are shown — a boolean, never a number. refinements is empty unless has_more is true; otherwise up to four, each a label and partial params to merge into the previous search (no counts). notes carries anything the person should hear — for example that a location was not recognised and the search was widened.

Buy and rent: when nothing matches exactly, filters are relaxed one step at a time (features → bedrooms → budget +25% → budget dropped, cheapest first → wider location → no location → type → minimum budget) and each relaxation is noted — the area the person asked for is kept as long as it has anything at all; an empty result only happens when the intent has no listings at all.

Stays never relax. Dates, guests, budget, type and features are hard filters; the only exception is a location nobody recognised, which is widened to its country (a typo should not send anyone away). When our own stays cannot serve the brief, results is empty and concierge carries the referral — the assistant says our stays are fully booked for those dates and points the person to concierge.domusaedes.com:

{
  "view": "results",
  "intent": "stay",
  "language": "en",
  "query_summary": "Stays in Marrakech, 12 guests, 24–27 Dec",
  "results": [],
  "has_more": false,
  "refinements": [],
  "notes": ["Our own stays are fully booked for this request — referred to the Domus Aedes concierge."],
  "concierge": {
    "url": "https://concierge.domusaedes.com",
    "message": "Our own stays are fully booked for this request. The Domus Aedes concierge sources stays beyond our portfolio — tell us your dates and we'll come back with options."
  },
  "contact": { "phone": "+34 930 34 46 10", "whatsapp": "https://wa.me/34930344610", "email": "contact@domusaedes.com", "website": "https://domusaedes.com" },
  "applied": { "intent": "stay", "location": "Marrakech", "guests": 12, "check_in": "2026-12-24", "check_out": "2026-12-27", "language": "en" }
}

get_property

Returns { view: "detail", listing: {…card fields, description, plot_area, region, offers, is_direct, source, updated_at, images ≤ 12} }. An unknown reference returns a plain { view: "error", message } rather than a protocol error.

request_property_details

Returns { view: "lead_confirmation", ok, message, ref, title, contact }. Search parameters are not stored. When you submit an advisor request, your name, email, phone and message are kept in Domus Aedes' customer records and forwarded to the owning agent — see the privacy notice.

Interactive view

Hosts that support MCP Apps (and ChatGPT via the Apps SDK) render a Domus Aedes view instead of text: up to six cards with photo, price and key facts, a map, refinement chips, a concierge card for stays we cannot serve, a detail page and the request form. The tools reference the resource ui://domus-aedes/app.html (text/html;profile=mcp-app). It loads images from sales.domusaedes.com and l.icdbcdn.com, and — only when the map is opened — tiles from server.arcgisonline.com (Esri), or from basemaps.cartocdn.com when the view is built with VITE_CARTO_KEY; it makes no other network requests. Preview it at /app.html?demo=search.

Data & freshness

• Sales and long-term rentals come from the Domus Aedes sales catalogue (sales.domusaedes.com), refreshed every 10 minutes. Only published listings are searchable.
• Stays — on the Costa del Sol, in Catalonia, Marrakech and Casablanca — come from the Domus Aedes booking system (stay.domusaedes.com), refreshed every 30 minutes; availability and totals are checked live when dates are given.
• Locations are approximate — an area or city centroid — unless the listing publishes its address. location.approx says which.
• Prices, facts and amenities are returned exactly as listed. If a stay total cannot be computed, the result says so instead of guessing.

Test it

Initialize:

curl -s https://ai.domusaedes.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Then call a tool (send notifications/initialized first if your client expects a session; this server is stateless and accepts each request on its own):

{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "search_properties",
    "arguments": { "intent": "buy", "location": "Marbella", "budget_max": 3000000, "language": "en" }
  }
}

Suggested reviewer prompts, in any of the three assistants:

1. “Domus Aedes, find me a villa to buy in Marbella under €3M with sea views.” — expect up to six properties and an offer to narrow down.
2. “Show me more.” — expect refinement options, not a longer list.
3. “Domus Aedes, a stay in Marrakech for four guests, 12 to 19 October.” — expect availability and a total per property.
4. “Tell me more about the first one.” — expect photos, description, map and the listing link.
5. “Send my details to an advisor.” — the assistant asks for name and email, then confirms.
6. “How many properties does Domus Aedes have?” — expect no number: the portfolio is curated and changes weekly, and an offer to search for a brief.
7. “Domus Aedes, a stay in Marrakech for twelve guests tomorrow.” — expect no listings and a pointer to the concierge when our own stays cannot serve it.

Plugin bundles

• GitHub: moss1337/domus-aedes-plugin (Claude Code marketplace + ChatGPT bundle).
• Claude marketplace manifest: /plugin/.claude-plugin/marketplace.json · plugin: /plugin/claude/.claude-plugin/plugin.json · MCP config: /plugin/claude/.mcp.json
• ChatGPT bundle: /plugin/chatgpt/plugin.json
• Skill (shared): SKILL.md

Support

Technical and listing questions: contact@domusaedes.com. Advisors: +34 930 34 46 10 · WhatsApp. Terms: sales.domusaedes.com/sales/legal/terms. Privacy: https://ai.domusaedes.com/privacy.

Server version 0.1.0 · updated 13 September 2026