# Claro AI

> **Casafari is the AI agent-native real estate data intelligence platform.** The most complete property index in Europe: a deduplicated, cleaned property graph of residential and commercial property, for sale and for rent, in 16 countries. Every property is one record with its full price and market history. [How the property graph is built](/docs/property-graph).

Claro, Casafari's business expansion search agent: describe the site a business needs in plain words and find the commercial premises across Spain that meet it. Every answer says which criteria each premises meets, which it does not and which its advertisement does not state, with the sentence or figure it rests on.

Claro AI has three doors on the same search, the same keys and the same answers: an app, the Claro API (REST) and the Claro MCP server. This section documents the second and the third. [Open the Claro app](https://expansion.casafari.com).

## The three doors

Claro AI is a platform product: you reach it through the platform's Worker on `https://platform.casafari.com` with a platform API key or the platform's OAuth, metered in platform units. The platform's Claro paths are `/v1/claro/*` for REST and `/mcp/claro` for MCP, live.

| Door | Address | Sign-in |
|---|---|---|
| App | [https://expansion.casafari.com](https://expansion.casafari.com) | The site's own sign-in |
| Claro API (REST) | `https://platform.casafari.com/v1/claro` | A platform API key or OAuth token |
| Claro MCP | `https://platform.casafari.com/mcp/claro` | The same platform key or OAuth |
| OpenAPI description (Claro's own; its paths have no `/claro`) | [https://expansion.casafari.com/v1/openapi.json](https://expansion.casafari.com/v1/openapi.json) | None |
| Tool definitions | `GET https://expansion.casafari.com/v1/tools` | None |
| Service status and data vintages | `GET https://expansion.casafari.com/v1/health` | None |

The platform forwards the call to Claro unchanged: Claro's `Claro-Version` header and its error bodies (`{"error":{"code","message"}}`, with `rate_limited` and `quota_reached` on a 429) pass through. To add the MCP server to an assistant, see [Connect Claro to an MCP client](/docs/claro/connect).

## Keys

Claro uses a platform API key (create and revoke it in your account on [platform.casafari.com](https://platform.casafari.com), like every other Casafari API and MCP key; see [platform API keys](/docs/rest#platform-api-keys)) or the platform's OAuth ([Authentication](/docs/authentication)). Send it as `Authorization: Bearer $CASAFARI_API_KEY` on both the REST API and the MCP server, and keep it on the server side: never in a browser, a URL or a repository. Because the platform's OAuth signs the client in, connectors in claude.ai and ChatGPT can reach Claro too ([Connect Claro](/docs/claro/connect)). Calls are metered in platform units; the units each Claro tool and operation costs are not published yet. The [platform terms](/legal/platform-terms) apply.

You never hold a Claro `pk_` key. The platform forwards your calls to Claro with your organisation's own Claro account, a key the platform keeps. A direct route at `https://expansion.casafari.com/v1` and `https://expansion.casafari.com/mcp` with a `pk_` key remains only for Casafari's own products and for pilot customers who already hold a key; it is not the public route.

What an account may do is set on the account: its limits, and whether its plan includes location data. Without location access the figures are left out, and a search that asks for a location criterion refuses it and names it in `not_applied` rather than ignoring it.

## How Claro differs from the Casafari MCP gateway

Claro is not behind the Casafari MCP gateway at `https://mcp.casafari.com/`. It is a platform product with its own MCP address and its own tool names, reached with a platform key or the platform's OAuth, like the other platform products.

| | Casafari MCP gateway | Claro MCP |
|---|---|---|
| Address | `https://mcp.casafari.com/` | `https://platform.casafari.com/mcp/claro` |
| Sign-in | OAuth 2.1 with a Casafari account ([Authentication](/docs/authentication)) | A platform API key or the platform's OAuth, sent as a bearer token; never a Claro `pk_` key |
| Tools | 22 tools in 3 products, named `<product>_<tool>`, listed by `list_servers` | 9 tools with their own names and no prefix; tools only, no resources or prompts |
| Server | Casafari MCP gateway | `serverInfo.name` `casafari-claro`, title "Claro AI by Casafari" |
| Transport | Streamable HTTP | Streamable HTTP with JSON responses, stateless (no session to keep) |
| Version | Not versioned by date | Every response carries `Claro-Version: YYYY-MM-DD` (2026-10-15 at the snapshot); changes within `v1` are additive; it passes through the platform |
| Limits and billing | Per plan: [Limits and usage windows](/docs/limits) | Platform units and plan limits, with Claro's own account limits behind them: see [Limits and errors](#limits-and-errors) |

Claro also has a REST API at `https://platform.casafari.com/v1/claro`. It is not the Casafari REST API at `api.casafari.com`: a Casafari bearer token (`POST /login`) does not work on it. The two interfaces of Claro are one to one (9 tools and as many operations): [MCP and REST compared](/docs/parity#claro-ai).

## How an answer reads

- **Counts are exact:** the number of premises that match, the number for which every criterion is stated, and the number for which some are not stated.
- **Every criterion is met, not met or not stated,** with the quote it rests on. Nothing is inferred; missing data is "not stated", never "no".
- **Ids are opaque.** A premises id is a `pm_` token, the same on every door.
- **Location figures carry their meaning:** unit, source and vintage in `location_sources`. A figure that is not known is `null`, never 0.
- **Keyword search needs no model:** send `criteria.keywords` (and `exclude_keywords`) with no `brief` and `"check": false`.

## Coverage and data

Claro covers commercial premises across Spain, for rent and for sale: shops, restaurant premises, offices, warehouses and other commercial units. Separately, and never mixed into a premises count, it covers **Germany, commercial plots**: plots of land for sale or rent in Germany for a commercial building, searched with their own tools and operations. The table is a snapshot of `GET /v1/health` (no key needed) taken on 15 October 2026; the live values are always at https://platform.casafari.com/v1/claro/health.

| | |
|---|---|
| Active premises (`active_listings`) | 230,403 |
| Last sync | 2026-10-15 01:40 UTC |
| Footfall estimates | 2024 |
| MB Research sociodemographics | 2024 |
| Places release (Overture Maps) | 2026-09-23.1 |
| Claro version (`Claro-Version`) | 2026-10-15 |

Every location figure in an answer also carries its own unit, source and vintage (`location_sources`), so the snapshot above is only the overview.

## MCP tools

9 tools on `https://platform.casafari.com/mcp/claro`, each documented with its parameters and a copy-ready call.

### Spain, commercial premises

| Tool | Title | What it does |
|---|---|---|
| [`search_premises`](/docs/claro/search_premises) | Search commercial premises | Find shops, restaurant premises, offices, warehouses and other commercial premises for rent or sale anywhere in Spain. |
| [`refine_search`](/docs/claro/refine_search) | Refine a search | Change part of an earlier search in plain words ("bigger, at least 200 m²", "Barcelona too", "drop the corner") and run it again, as a new search with its own… |
| [`get_premises`](/docs/claro/get_premises) | Get one premises | One premises in full by the id a search returned: its data, facts read from its text with the sentence each came from (fact_sources), its coordinates (exact,… |
| [`compare_premises`](/docs/claro/compare_premises) | Compare premises | 2 to 10 premises side by side, by the ids a search returned. |
| [`market_snapshot`](/docs/claro/market_snapshot) | What premises ask in a place | What commercial premises of a kind ask in a place anywhere in Spain, from every active property of that kind and place (each unit counted once): the asking… |
| [`explain_location`](/docs/claro/explain_location) | Location figures | Footfall index (an index of pedestrian activity within a 5-minute walk that compares places with each other; not a head count, never people or visitors a day;… |
| [`brief_from_file`](/docs/claro/brief_from_file) | Read a brief from a file | The premises requirements a file states (a site brief, a location profile, a requirements sheet): a PDF, a photo or scan (JPG, PNG, WebP, HEIC), a Word, Excel… |

### Germany, commercial plots

2 tools for plots of land in Germany, a set of their own: plots only, never premises, and never in a premises count.

| Tool | Title | What it does |
|---|---|---|
| [`search_plots`](/docs/claro/search_plots) | Search commercial plots (Germany) | Find plots of land for sale or rent in Germany for a commercial building, from Casafari's property graph. |
| [`get_plot`](/docs/claro/get_plot) | Get one plot (Germany) | One plot in full by the id search_plots returned: its data, commercial-use level, the facts read from its text with the quote each came from (fact_sources),… |

## REST API

11 operations under `https://platform.casafari.com/v1/claro`, each documented with its parameters, an example request with a key placeholder and its responses. The OpenAPI description is at [https://expansion.casafari.com/v1/openapi.json](https://expansion.casafari.com/v1/openapi.json).

### Spain, commercial premises

- [`POST /v1/search`](/docs/rest/claro/search-premises): Search commercial premises. Find shops, restaurant premises, offices, warehouses and other commercial premises for rent or sale anywhere in Spain.
- [`POST /v1/search/refine`](/docs/rest/claro/refine-search): Refine a search. Change part of an earlier search in plain words ("bigger, at least 200 m²", "Barcelona too", "drop the corner") and run it again, as a new search with its own search_id…
- [`GET /v1/premises/{id}`](/docs/rest/claro/get-premises): Get one premises. One premises in full by the id a search returned: its data, facts read from its text with the sentence each came from (fact_sources), its coordinates (exact, or…
- [`POST /v1/compare`](/docs/rest/claro/compare-premises): Compare premises. 2 to 10 premises side by side, by the ids a search returned.
- [`POST /v1/location`](/docs/rest/claro/explain-location): Location figures. Footfall index (an index of pedestrian activity within a 5-minute walk that compares places with each other; not a head count, never people or visitors a day; split…
- [`POST /v1/market`](/docs/rest/claro/market-snapshot): What premises ask in a place. What commercial premises of a kind ask in a place anywhere in Spain, from every active property of that kind and place (each unit counted once): the asking price per m²…
- [`POST /v1/brief/file`](/docs/rest/claro/brief-file): Read a brief from a file. The premises requirements a file states: a site brief, a location profile or a requirements sheet, as a PDF, a photo or scan (JPG, PNG, WebP, HEIC), a Word, Excel or…
- [`PUT /v1/stores`](/docs/rest/claro/stores): Your own stores. PUT replaces the list: text/csv with a header naming name, lat and lon (latitude/longitude also work; comma, semicolon or tab separated), or JSON {"stores": [{"name",…
- [`GET /v1/health`](/docs/rest/claro/health): Service status and data vintages

### Germany, commercial plots

- [`POST /v1/plots/search`](/docs/rest/claro/search-plots): Search commercial plots (Germany). Find plots of land for sale or rent in Germany for a commercial building, from Casafari's property graph.
- [`GET /v1/plots/{id}`](/docs/rest/claro/get-plot): Get one plot (Germany). One plot in full by the id search_plots returned: its data, commercial-use level, the facts read from its text with the quote each came from (fact_sources), an excerpt,…

## MCP and REST compared

Every tool has a REST operation that does the same job, and the answers are the same. Two operations have no tool: [`PUT /v1/stores`](/docs/rest/claro/stores) and [`GET /v1/health`](/docs/rest/claro/health). Details: [MCP and REST compared](/docs/parity#claro-ai).

## Limits and errors

Your platform plan's limits and units apply first ([Limits and usage windows](/docs/limits)). Behind them Claro keeps limits per account: calls a minute, calls a day, results a page (up to 200) and live location points a day. A call Claro answers passes through unchanged, with its `Claro-Version` header. At a limit the answer is `429` with a body of the form `{"error": {"code": "...", "message": "..."}}`, whose code is `rate_limited` when calls come too fast and `quota_reached` when a daily limit is used up. Wait and retry for `rate_limited`; `quota_reached` lasts until the limit resets (for the live-location limit its message names `live_location_points_daily`). Over MCP a refusal arrives as a tool error with the same body. A call the platform refuses before Claro (no valid platform key or token, no credit) is answered by the platform in its own error format.

| Status | Meaning |
|---|---|
| `400` | Invalid request |
| `401` | Missing or invalid key (a platform key or token) |
| `403` | The account has no access to this |
| `413` | A brief file is above 10 MB |
| `429` | Rate limited or quota reached |
| `503` | The database cannot be read (`GET /v1/health`) |

## Content terms

These are terms of use of Claro's data, and the API enforces them in what it returns. They apply to every door, and to anything you build on the answers.

- **Link only to the agency's own page.** Show the link the answer gives for the property and name the agency. Never name or link a property portal, and never show a portal's name.
- **Never name a private seller.** An answer names an agency, never a private person selling.
- **Show an excerpt and the matched sentences, not the full description.** An answer carries an `excerpt` and the sentence each criterion rests on; do not republish the full advertisement text.
- **Use photos only as the Casafari thumbnails the answer gives** (`photos`). Do not fetch, copy or show the original image of an advertisement or any image host of a portal.
- **Keep what a figure says.** A criterion is met, not met or not stated; show a "not stated" as not stated, never as "no". An unknown footfall or population is `null`, never 0, and a figure keeps its unit, source and vintage.

The [platform Terms of Use](/legal/platform-terms) apply until a Claro annex exists.

## Who it is for

Expansion teams at store, restaurant and service chains and their site-selection consultants, and the software partners who build for them: [the Claro app](https://expansion.casafari.com) is for managers, this section for the developers and assistants behind them.

## Use cases

- [Score every premises with your own agent](/docs/claro/use-cases/score-premises-with-your-own-agent): Pull every match with its raw figures, matched sentences and location_sources, treat null and not_stated as unknown, and score with your own model.
- [Load every match into a CRM or warehouse nightly](/docs/claro/use-cases/nightly-pipeline-into-crm-or-bi): Page every match 200 at a time within the search's 24 hours, key rows on pm_ ids, reconcile with matching, and refresh status and price history nightly.
- [Get location figures for any point in Spain](/docs/claro/use-cases/explain-any-point-in-spain): Send lat and lon to POST /v1/claro/location for footfall, residents and nearby places at any point in Spain, within the live-location daily limit.
- [Keyword search from a simple form, no model](/docs/claro/use-cases/keyword-search-from-a-form): Send criteria.keywords and exclude_keywords with no brief and check false: reproducible results with the matched sentence as evidence.
- [Compare a shortlist for the committee dossier](/docs/claro/use-cases/compare-a-shortlist-for-a-dossier): Put 2 to 10 premises side by side with compare_premises and add a site assessment, fact sources and agency links from get_premises.
- [Embed the search box with a publishable key](/docs/claro/use-cases/embed-the-search-box): Load /embed.js with a pub_ key for a public search box, 50 results a page, and keep every other operation on your server.
- [Turn a PDF or Word brief into a search](/docs/claro/use-cases/brief-from-a-file): Send a PDF, scan or Office file to brief_from_file, show the brief and its quotes for approval, then run search_premises with it.
- [Keep candidates away from your own stores](/docs/claro/use-cases/keep-candidates-away-from-your-own-stores): Upload up to 5,000 store coordinates with PUT /v1/claro/stores and exclude premises within own_stores_away_m metres of any of them.

## Questions about Claro AI

- [What is the base URL of the Claro API, and where is the OpenAPI description?](/docs/claro/faq#base-url)
- [How do I get access to the Claro API and the Claro MCP?](/docs/claro/faq#get-access)
- [Which header carries the key, and does Claro need its own `pk_` key?](/docs/claro/faq#api-key-header)
- [How does a call travel through the platform to Claro, what passes through unchanged, and what is the direct route?](/docs/claro/faq#platform-route)
- [What transport does the Claro MCP use, and do I have to keep a session?](/docs/claro/faq#mcp-transport)
- [What URL and sign-in does a claude.ai or ChatGPT connector need for the Claro MCP?](/docs/claro/faq#claude-chatgpt-connector)
- [Is Claro one of the tools on the Casafari MCP gateway at mcp.casafari.com?](/docs/claro/faq#claro-mcp-vs-gateway)
- [Do the Claro MCP tools and the REST operations do the same things?](/docs/claro/faq#rest-mcp-parity)
- [What does an error body look like, and which statuses can a call return?](/docs/claro/faq#error-bodies)
- [How do I tell a per-minute 429 from a daily 429, and what limits does Claro keep?](/docs/claro/faq#rate-limits-429)
- [What is the `Claro-Version` header, and how are changes to `v1` published?](/docs/claro/faq#claro-version)
- [What does `GET /v1/health` return, and what does `active_listings` count?](/docs/claro/faq#health-active-count)
- [Are the counts a search returns exact, and what do `matching` and `all_criteria_stated` mean?](/docs/claro/faq#exact-counts)
- [Can my client treat `not_stated` as false?](/docs/claro/faq#not-stated)
- [Are premises ids stable across REST and MCP, and can I parse them?](/docs/claro/faq#premises-ids)
- [How do I page through every match: `limit`, `next_cursor`, `cursor` and `page`?](/docs/claro/faq#paging)
- [What does `check` do, when does it run, and how do I keep a model out of a search?](/docs/claro/faq#check-model)
- [How do I run a keyword-only search with no model in the loop?](/docs/claro/faq#keyword-search)
- [Which criteria need location data access, and what is `not_applied`?](/docs/claro/faq#location-access-not-applied)
- [Where do I find the unit, source and vintage of each location figure, and why is footfall `null` rather than 0?](/docs/claro/faq#location-sources)
- [How do I upload my own stores and keep candidates away from them?](/docs/claro/faq#own-stores)
- [What may my product display from a Claro answer?](/docs/claro/faq#content-terms)
- [How does the embeddable search box authenticate, and what are its limits?](/docs/claro/faq#embed-box)

## Ask your assistant

> burger restaurant, corner unit 120-250 m², smoke outlet, busy street, Madrid, rent under 8,000 a month