Claro AI

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.

#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.

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.

#Keys

Claro uses a platform API key (create and revoke it in your account on platform.casafari.com, like every other Casafari API and MCP key; see platform API keys) or the platform's OAuth (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). Calls are metered in platform units; the units each Claro tool and operation costs are not published yet. The 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.

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.

#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.

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

#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.

#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.

#Spain, commercial premises

• POST /v1/search: Search commercial premises. Find shops, restaurant premises, offices, warehouses and other commercial premises for rent or sale anywhere in Spain.
• POST /v1/search/refine: 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}: 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: Compare premises. 2 to 10 premises side by side, by the ids a search returned.
• POST /v1/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: 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: 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: 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: Service status and data vintages

#Germany, commercial plots

• POST /v1/plots/search: 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}: 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 and GET /v1/health. Details: MCP and REST compared.

#Limits and errors

Your platform plan's limits and units apply first (Limits and usage windows). 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.

#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 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 is for managers, this section for the developers and assistants behind them.

#Use cases

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

#Ask your assistant

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