Casafari API and MCP Platform
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 in the graph is one record, merged from every source that advertises it and cleaned, with its full history: every price change, every status change, when it came on the market and when it was delisted. Residential and commercial property alike, for sale and for rent. How the property graph is built.
Casafari's MCP servers connect AI assistants and agents to it as Model Context Protocol tools: place lookup, comparables and valuations, area insights, and agency and agent analysis. They are part of the Casafari API and MCP Platform: one MCP server for every product, https://platform.casafari.com/mcp, one connection and one OAuth sign-in (each product is also its own server).
The same data is also available over the platform's REST API (https://platform.casafari.com/v1/<product>, 37 operations, the same platform API key and tokens as the MCP servers; Casafari clients with a contract also keep the existing API at https://api.casafari.com, 39 operations). Docs are organised by product, and each product lists its MCP tools and its REST operations; MCP and REST compared shows where the two overlap and where they do not.
Already a Casafari API customer? Your token keeps working, and the existing API's reference is now on this site. Log in to your API account to see your token.
Endpoints
One MCP server for every product (Streamable HTTP, OAuth 2.1 sign-in in the browser, no key to copy):
https://platform.casafari.com/mcpIn Claude or ChatGPT, add a custom connector named Casafari with that URL; in Claude Code: claude mcp add --transport http casafari https://platform.casafari.com/mcp. Or one product at a time, each product on its own server. Steps for Claude, ChatGPT, Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI, Zed and other clients: Connect and Connect to the Casafari Platform.
Already a Casafari client? Use the same server: sign up at https://platform.casafari.com/console/, and if you have a contract, Casafari sets your account up on the Custom plan. mcp.casafari.com is the legacy gateway, still answering, moving to https://platform.casafari.com/mcp/<product>.
Each server publishes its own card at <server URL>/.well-known/mcp/server-card.json, the one server's at https://platform.casafari.com/mcp/.well-known/mcp/server-card.json. Sign-in: Authentication.
Claro AI is a platform product too; with a platform API key instead of OAuth, see Connect Claro.
Products
| Product | MCP tools | REST operations | What it answers |
|---|---|---|---|
| Property Sourcing | 5 | 10 | Find properties in the property graph, where every property is one record however many agencies and portals advertise it: search by structured filters or in plain language, page through the results, read one property with everywhere it is advertised and its price history, and resolve a portal or agency link or a reference to the property it belongs to. REST and MCP. |
| High Potential Seller Leads | — | 2 | Homes likely to sell: properties around a point whose asking price was cut repeatedly, by how many cuts and how much in total, over their whole time on the market or since a date. Each lead links to its property and its price history. REST only; Spain, France, Italy, Germany, Greece and Andorra. |
| Private Seller Leads | 3 | 3 | Homes offered by their owners, from newly published adverts: first seen in a place since a date (90 days back at most), newest first, with portal link, price, area and rounded coordinates. No contact details yet. |
| Comparables & Valuation | 1 | 5 | Comparable properties and estimated prices for a home: properties on the market or taken off it as sold or rented, with their asking prices only, matched around a point, an address or a cadastral reference. |
| Comparables with Transactions | 1 | 1 | Everything Comparables returns, plus registered closing prices: Spain's notary deals, Italy's registered sales via our partner Ring33 and Poland's RCN official register (transactional_data), France's DVF public register (dvf_results). The same input as Comparables. |
| Area Insights | 10 | 16 | Insights for an area: price, supply and activity over time, distributions by price, bedrooms and time on market, and market analysis. Over MCP also growth and volatility measures and heatmaps by district. |
| New Market Leads | — | 12 | Alert feeds that follow the property graph for a set of filters: new properties, price rises and cuts, reservations, delistings and sales. Create a feed, read its alerts, or have them delivered to your webhook. In maintenance. |
| References | — | 10 | The reference data requests are built from: property types, features and conditions, agencies, agents and the sources the graph is built from, locations with typeahead, and zip-code boundaries. |
| Cadastre | 5 | — | Spanish cadastral records and zone reference values: find a property by cadastral reference, address or coordinates, read its registry record, and the reference value of its zone or of every zone in a municipality. Spain, except Navarra and the Basque Country. |
| Parcel Zoning | 2 | 6 | Zoning and buildable area of a land parcel, by cadastral reference or point. Spain (Bizkaia, Catalonia) and Germany (Hamburg, North Rhine-Westphalia). |
Claro AI
Claro AI is Casafari's business expansion search agent for commercial premises across Spain and Germany. It is a platform product: its own MCP server and REST API on the platform, with a platform key or the platform's OAuth. Connect Claro.
How tools are named
Each server names its tools <server>_<tool>: the prefix is the last segment of the server's URL, the rest is the tool's own name, for example comparables_get_comparables, area-insights_get_heatmap or property-sourcing_search. Location Lookup's tools are locations_search and locations_get, and every server also has account_status. Always call a tool by its full name, as the server lists it.
An API for AI agents
Casafari is an API for AI agents in two forms, on the same property graph:
- The MCP server (
https://platform.casafari.com/mcp, every product; or one per product underhttps://platform.casafari.com/mcp/), for agents that discover the tools and decide which to call: in Claude, ChatGPT and other MCP clients, or from your own code through the OpenAI API or the Claude API. - The REST API (reference), for agents and apps whose code makes fixed requests.
These docs are written for agents too: every page is Markdown, and /llms.txt indexes them all.
Tokens, payment and verification
Every call costs a fixed number of tokens on your platform account, the same over MCP and REST. account_status, on every server, shows your plan and balance. When tokens run out, a tool answers with a payment error that carries a link to top up, with no subscription needed (the account's owner or a billing member opens it and pays). Limits per plan: Limits.
Start with a location
Most data tools take a location as ids, a circle or a polygon rather than a name: resolve a place name to ids with Location Lookup's locations_search first (https://platform.casafari.com/mcp/locations, free).
Read these docs as Markdown
Every page has a Markdown version: add .md to its URL, or send Accept: text/markdown. /llms.txt lists every page and tool; /llms-full.txt is the whole reference in one file. More in For AI agents.
Questions and answers
Which address do I use: api.casafari.com or platform.casafari.com (mcp.casafari.com is the legacy gateway)?
New users and every MCP user start at platform.casafari.com, Casafari's self-serve platform; existing Casafari clients keep api.casafari.com for REST, and mcp.casafari.com is the legacy gateway, still answering and moving to the platform.
If you're new to Casafari: use https://platform.casafari.com.
- Assistants connect over MCP at https://platform.casafari.com/mcp, one address for every product; each product is also its own server at
https://platform.casafari.com/mcp/<product>, for example https://platform.casafari.com/mcp/comparables. - Code calls REST at
https://platform.casafari.com/v1/<product>for account, locations, area-insights, property-sourcing, seller-leads, alerts, comparables and claro. High Potential Seller Leads is REST only; every other product has an MCP server.
Sign up yourself, try without a card and pay by usage: how to sign up.
If you're a Casafari client: keep https://api.casafari.com for REST, with your existing login and contract. Nothing changes there: there is no migration and no account linking, and Property Sourcing stays on the Casafari REST API. For MCP, use the self-serve platform like everyone else: sign up at https://platform.casafari.com/console/, and if you have a contract, Casafari sets your account up on Custom. Details: Existing API customers and what changes for you.
Full URLs: MCP server URL and REST base URL.
Permalink: /docs/faq/which-address-do-i-use
How do I get an API key and make my first call?
Create an account at https://platform.casafari.com (the Free plan needs no card), then create an API key in the console and send it with your first call.
- Create a key (
cf_sk_…) in the console; it is shown once, so store it at once, and never put it in a URL. - Call
GET https://platform.casafari.com/v1/locations/search?query=Lisbonwith the key in theX-API-Keyheader, or asAuthorization: Bearer <api_key>. Place lookups cost 0 tokens, so this first call is free.
Assistants do not need a key: add a product's MCP server and sign in with OAuth (connecting a client). A Free account has 1 member and 2 API keys; Agent has 1 member and 3 keys; Agency has 5 members and 10 keys (pricing). What the trial includes is in the free trial; the REST reference is in REST API and Authentication.
Existing Casafari clients keep their login on the Casafari REST API (Existing API customers).
Permalink: /docs/faq/how-to-sign-up
What are tokens on the Casafari platform, and how many does each request cost?
A token is the self-serve platform's billing atom: every operation costs a fixed whole number of tokens, the same over MCP and REST, from 0 to 2,500.
- Location Lookup (place lookups) and account calls: 0 tokens (location lookups).
- Area Insights: 25 tokens per operation (0 for the current date).
- Comparables & Valuation: 25 tokens per operation.
- Alerts: in maintenance on the self-serve platform while webhook delivery is rebuilt; existing clients keep their contracts.
The Free trial has 1,000 tokens: a partner brief costs more than that. More tokens are credits at €0.04 a token, excluding VAT. Agent plan usage is also metered in usage windows; follow yours in usage and balance.
Permalink: /docs/faq/what-are-units
My AI agent says payment is required or I'm out of tokens. What do I do?
On the self-serve platform, a payment error carries a payment link: a person opens it and pays, or waits for a usage window to refill, then the agent retries.
- Tokens ran out: REST answers
402 payment_requiredwith anupgrade_urland aLinkheader withrel="payment"; a platform MCP server answers a payment error with the same link (error page). - A 3-hour usage window is used up and no credits remain: REST answers
429 usage_limit_reachedwith the refill time, aRetry-Afterheader and anupgrade_urlto buy credits; MCP answers a payment error with the same members. - The spending cap is reached:
402 payment_requiredwith the reasonspending_cap_reached, until the period ends or the cap is raised.
Once a person has paid, the agent polls GET /v1/account/payment-links/{id} about every 5 seconds until the status is completed, then retries.
The agent cannot pay by itself (can an agent pay?); credits top up automatically only if a person turned on auto top-up. Whether an assistant must reconnect after paying is not published. See handling a 402 and credits.
A quota in a Casafari REST API contract is different: see quota versus tokens.
Permalink: /docs/faq/agent-ran-out-of-units
Can I read these docs as Markdown, and is there an llms.txt?
Yes: add .md to any page's URL or send Accept: text/markdown, and /llms.txt indexes every page and tool. None of it needs a key.
- /llms.txt is the index, and /llms-full.txt holds the whole reference in one file.
- /tools.json gives every tool's name, title, input schema and output schema.
- You'll also find the API catalog, MCP server card, agent skill, agentic resource manifest and the sitemap at
/sitemap.xml. - Markdown responses are served as
text/markdown, with anx-markdown-tokensheader that estimates their size. - In a browser that supports
navigator.modelContext, pages register these WebMCP tools:search_casafari_mcp_docs,get_casafari_tool_reference,get_casafari_rest_operation,get_casafari_connection_configandopen_casafari_docs_page. - The self-serve platform publishes its own https://platform.casafari.com/llms.txt and https://platform.casafari.com/llms-full.txt, plus an OpenAPI for each product.
See: For AI agents.
Permalink: /docs/faq/machine-readable-docs