# Happy Endpoint MCP Server

An MCP server that gives Claude, Cursor, and other MCP clients direct access to
real-time real estate, retail, and travel data. Ask questions in plain language
and the assistant queries the APIs itself.

> **Beta.** This is a 0.x release. Tools and their arguments may change before 1.0.

```
"What's the rental yield on a 1-bed in JVC versus Dubai Marina?"
"What did apartments in Business Bay actually sell for this year?"
"Find off-plan projects in Dubai Hills under 2 million with less than 50% before handover."
```

Built and maintained by [Happy Endpoint](https://happyendpoint.com).

---

## Install

Add to your MCP client config and restart it. No install step, `npx` fetches the
package on first run.

```json
{
  "mcpServers": {
    "happyendpoint": {
      "command": "npx",
      "args": ["-y", "happyendpoint-mcp"],
      "env": {
        "RAPIDAPI_KEY": "your_rapidapi_key"
      }
    }
  }
}
```

| Client | Config path |
|---|---|
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor | `~/.cursor/mcp.json` |
| Claude Code | `.mcp.json` in your project root |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |

Get a key at [rapidapi.com/user/happyendpoint](https://rapidapi.com/user/happyendpoint).
One key works across every API, and each has a free tier, but you subscribe to
each one separately.

---

## Tools

| Tool | What it does |
|---|---|
| `search_properties` | Property listings for sale or rent by area, price, bedrooms, type |
| `get_property_details` | Full record for one property, with amenities and agency |
| `get_transactions` | Recorded sale transactions with price per sqm and sale type |
| `compare_rental_yields` | Gross yield across several areas at once, computed |
| `search_off_plan` | Off-plan and under-construction developments |
| `find_agents` | Agents by area, with agency and performance badges |
| `find_locations` | Search areas, communities, and buildings by name |
| `search_products` | Retail product search across beauty and home categories |
| `search_hotels` | Hotel search by destination and dates |
| `list_available_apis` | What this server can reach, and where to subscribe |

---

## Why this rather than a generic API proxy

Some marketplaces expose a generic MCP endpoint that forwards raw REST calls. For
simple cases that is fine. This server exists because four things go wrong when
an assistant is handed raw endpoints.

### 1. Location IDs fail silently

Property search endpoints take a numeric location ID. Pass a wrong one and the
API returns **a different area** rather than an error. The answer looks
completely plausible and is about the wrong place.

This is not hypothetical. A published ID table for these endpoints had seven of
nine areas wrong, with two major communities transposed.

Here, tools take place names. IDs are resolved internally, and every response
echoes which area was actually matched:

```json
"resolvedLocation": { "name": "Jumeirah Village Circle (JVC)", "id": "5416" }
```

### 2. The endpoints disagree with each other

Four different response shapes for closely related data:

| Endpoint | Shape |
|---|---|
| Property search | `{properties, total}`, camelCase, `title` is `{en: "..."}` |
| Property details | flat object, `title` is a plain **string** |
| Agent search | a bare **array**, snake_case field names |
| Transactions | search-index shaped `{hits, nbHits}`, numbers as strings |

Given three shapes for "title", a model will read the wrong field and state the
result confidently. Everything is normalised to one shape here.

### 3. Some questions are not a single endpoint

"Which area has the better rental yield" needs a sale search and a rent search
per area, medians over both, and a division. `compare_rental_yields` does it in
one call across up to eight areas. There is no endpoint for it.

### 4. Ten tools beats seventeen

Models choose badly among seventeen near-identical endpoint names. This exposes
ten task-shaped tools with descriptions that say when to use them, including the
distinction that trips up most analysis: listings are **asking** prices,
transactions are what property **actually sold for**.

---

## Example output

`compare_rental_yields` across four areas, 1-bed apartments:

| Area | Gross yield | Median asking sale | Median annual rent |
|---|---|---|---|
| Jumeirah Village Circle (JVC) | 7.87% | 890,000 | 69,999 |
| Business Bay | 6.06% | 1,650,000 | 100,000 |
| Dubai Marina | 6.00% | 1,500,000 | 90,000 |
| Palm Jumeirah | 3.78% | 3,700,000 | 140,000 |

`get_transactions` returns a computed summary alongside the rows:

```json
{
  "totalTransactions": 3421,
  "summary": {
    "medianPricePerSqm": 15871,
    "minPricePerSqm": 7944,
    "maxPricePerSqm": 27013,
    "saleTypeBreakdown": { "Primary First Sale": 13, "Secondary Resale": 7 }
  }
}
```

---

## Data domains

| Domain | Coverage |
|---|---|
| Real estate | UAE listings, transactions, agents, off-plan developments |
| Retail, beauty | Cosmetics and skincare across the US, Canada, France |
| Retail, home | Furniture and home goods across eight countries |
| Travel | Hotels, flights, car rental |

Full catalogue at [happyendpoint.com/library](https://happyendpoint.com/library).

---

## Things worth knowing

**Rental prices are annual.** These markets quote yearly rent, not monthly. The
server labels it so the assistant does not divide by twelve without noticing.

**Asking prices are not transaction prices.** `search_properties` returns what
sellers want. `get_transactions` returns what buyers paid. For valuation, use
transactions.

**`get_property_details` is slow**, routinely over 30 seconds. The server allows
for it, but prefer `search_properties` when its fields suffice.

**Gross yield is not net yield.** Service charges, management, maintenance, and
vacancy typically remove 2 to 3 percentage points. The tool says so in its
output.

---

## Local development

```bash
git clone https://github.com/happyendpointhq/happyendpoint-mcp
cd happyendpoint-mcp
npm install
npm run build

RAPIDAPI_KEY=your_key node test-client.mjs
```

`test-client.mjs` connects over stdio, lists the tools, and calls several
against the live API.

Point your client at the local build:

```json
{
  "mcpServers": {
    "happyendpoint-dev": {
      "command": "node",
      "args": ["/absolute/path/to/happyendpoint-mcp/dist/index.js"],
      "env": { "RAPIDAPI_KEY": "your_key" }
    }
  }
}
```

---

## FAQ

### Do I need a paid plan?

No. Every API has a free tier, enough to try all the tools. Heavier use needs a
paid plan on the specific APIs you use.

### Why did a tool return a 403?

You are not subscribed to that particular API, or its quota is exhausted. The
error names the API and links its subscription page. `list_available_apis` shows
all of them.

### Does it cover countries outside the UAE?

Property tools are UAE-focused today. The wider catalogue covers the UK, Spain,
Turkey, Singapore, Japan, and the US, and those will be added as tools. See
[happyendpoint.com/library](https://happyendpoint.com/library).

### Is my API key sent anywhere except the data provider?

No. It stays in your MCP client config, is read from the environment, and is
sent only as an authentication header to the upstream API gateway.

### Can I use this without an MCP client?

Yes, through the language SDKs:
[happyendpoint](https://pypi.org/project/happyendpoint/) on PyPI and
[happyendpoint-js](https://github.com/happyendpointhq/happyendpoint-js).

---

## Status

Beta, 0.x. Tool names and arguments may change before 1.0. Pin a version if you
need stability.

---

## Disclaimer

Happy Endpoint is an independent provider. This package is **not affiliated
with, endorsed by, sponsored by, or connected to** any of the websites,
platforms, retailers, or marketplaces whose data may be accessible through the
underlying APIs.

All product names, brands, trademarks, and registered trademarks are the
property of their respective owners. Any reference to them is descriptive only,
to identify the subject matter of the data, and does not imply any association
or endorsement.

Users are responsible for ensuring their use of any data complies with
applicable laws and the terms of service of the relevant source.

---

## Related

- [happyendpoint](https://pypi.org/project/happyendpoint/) - Python client for the same APIs
- [happyendpoint-js](https://github.com/happyendpointhq/happyendpoint-js) - TypeScript client
- [awesome-real-estate-apis](https://github.com/happyendpointhq/awesome-real-estate-apis) - curated list of property data sources
- [awesome-alternative-data](https://github.com/happyendpointhq/awesome-alternative-data) - curated list of alternative data sources

---

## About Happy Endpoint

[Happy Endpoint](https://happyendpoint.com) builds and maintains real-time data
APIs across real estate, ecommerce, retail, and travel.

- Catalogue: [happyendpoint.com/library](https://happyendpoint.com/library)
- Datasets: [happyendpoint.com/datasets](https://happyendpoint.com/datasets)
- Contact: happyendpointhq@gmail.com

## Licence

MIT. See [LICENSE](LICENSE).