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 and Germany 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 tokens. The platform's Claro paths are /v1/claro/* for REST and /mcp/claro for MCP.

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. An unauthenticated call answers 401 with a WWW-Authenticate header whose resource_metadata points at the OAuth protected-resource metadata (MCP, REST), which names the platform as the authorization server and the scopes claro:read, claro:write. 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 tokens; the tokens each Claro tool and operation costs are not published yet (GET /v1/claro/health is free, 0 tokens). 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 Casafari's other MCP servers

Claro is one of the platform's MCP servers, like Property Sourcing https://platform.casafari.com/mcp/property-sourcing, Private Seller Leads https://platform.casafari.com/mcp/private-sellers, Comparables & Valuation https://platform.casafari.com/mcp/comparables, Comparables with Transactions https://platform.casafari.com/mcp/comparables-transactions, Area Insights https://platform.casafari.com/mcp/area-insights, Cadastre https://platform.casafari.com/mcp/cadastre, Parcel Zoning https://platform.casafari.com/mcp/parcel-zoning: the same platform account, keys and OAuth, metered in the same tokens. It differs from them in a few ways.

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: token, 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 and Germany, 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 taken on 21 October 2026; the live values are at GET /v1/claro/health on the platform (https://platform.casafari.com/v1/claro/health), free (0 tokens) with your platform key.

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

12 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://platform.casafari.com/v1/claro/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 or Germany (one country per search; Spain unless…
• 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 5 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 or Germany (one country per search; Spain unless Germany is asked), from every active property of…
• 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
• POST /v1/search/ask: Ask about a search you show. A free question about a search you show your user ("why only 180?", "which has the longest frontage?"), answered by a model from that search and the read-only…

#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 tokens 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: Use search_premises to identify targets and then iterate through pages using next_cursor to retrieve every match and its location figure sources.
• Nightly pipeline of premises into a CRM: Automate daily calls to search_premises using your stored criteria to update your internal CRM with the latest commercial premises for expansion.
• Explain any point with Location Intelligence: Use explain_location to retrieve pedestrian activity and sociodemographic data for any latitude and longitude in Spain via the API.
• Keyword search from a simple form: Use criteria.keywords in your search request with check: false to filter properties based on explicit text matching in advertisements.
• Compare a shortlist for a dossier: Use compare_premises with the IDs of your shortlisted properties to generate a comparative side-by-side analysis for your expansion committee.
• Embed the search box on your site: Use a publishable pub_ key to load the Claro search box for your users, limited to 50 results per page, served via the Claro service.
• Generate a brief from a file: Use brief_from_file to upload a file and parse it into structured requirements, which you then pass directly into the search_premises tool.
• Search commercial plots in Germany: Use search_plots and get_plot tools to find land for commercial development in Germany, distinct from any commercial premises searches.

#Questions about Claro AI

• What are the base URLs for the Claro API and how do I authenticate?
• How do I discover the OAuth protected resource for Claro?
• How do I check the Claro service status and data vintages?
• How do I get access to the Claro API?
• How is the Claro MCP server configured and how does it transport data?
• How should I handle missing data in the response?
• What is the difference between matching and all_criteria_stated counts?
• What format are the premises IDs?
• How does pagination work for Claro searches?
• When does the model assessment run for search results?
• Can I perform a search using keywords only?
• What happens if I lack location data access?
• How do I interpret location figures and sources?
• How do I handle 429 rate limit responses?
• How is the API versioned?
• What are the usage terms for premises data?
• What is the direct Claro host?
• How do I use Claro in AI assistants?
• How do I use the embeddable search box?
• What is the geographic coverage of Claro?

#Ask your assistant

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

See what Claude wrote from a single brief: Claro AI in Claude: example reports.

#Questions about this

• Which Casafari products and tools can I use?