Casafari API and MCP Platform: frequently asked questions

Casafari is a real estate data intelligence platform whose data is a deduplicated, cleaned property graph, with one record per property and its full history.

Casafari gathers property advertisements from agency websites and portals and maps each one to a single schema: type, operation, price, area, rooms, features, condition, energy rating and location. It then cleans the values, detects when several agencies and portals are advertising the same property, and merges them into one record per property. That record holds every price change, status change, appearance and removal, each with its date. Residential and commercial properties, for sale and for rent, share one schema and one location tree. Count properties, not advertisements. By Casafari's own count, the graph is the most complete property index in Europe: at least 40% more coverage of deduplicated properties, and 7 times more property advertisements tracked, than any standalone platform or portal (why).

Casafari calls itself the AI agent-native real estate data intelligence platform. AI assistants reach the graph through the self-serve platform at platform.casafari.com, where anyone can sign up; existing Casafari clients also keep the Casafari REST API (which address to use).

See The property graph and https://www.casafari.com/.

Casafari MCP lets an AI assistant or agent use Casafari's real estate data through the self-serve platform's remote MCP server, which signs in with OAuth 2.1.

One address for every product:

• https://platform.casafari.com/mcp

Add it once as a connector named Casafari, sign in once, and every product's tools are there, named after their product (comparables_get_comparables, area-insights_get_heatmap, property-sourcing_search); locations_search and account_status are free. In Claude Code: claude mcp add --transport http casafari https://platform.casafari.com/mcp. Assistants such as Claude sign in with OAuth 2.1, no API key is needed, and you pay by usage. Each product is also its own server, https://platform.casafari.com/mcp/<product>, for a connector limited to one product (the list; Connect to the Casafari Platform, All tools).

Already a Casafari client? Sign up the same way; if you have a contract, Casafari sets your account up on Custom. The old gateway, https://mcp.casafari.com/, is the legacy gateway: it still answers, and its servers are moving to the platform.

For code rather than an assistant, see What is the Casafari REST API?. To pick a route, see which address to use and the MCP server URL.

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.

For the Casafari REST API, nothing changes; for MCP, the old gateway, mcp.casafari.com, is the legacy gateway (still answering, moving to the platform), and you connect through the self-serve platform's MCP servers like everyone else.

• REST: keep calling https://api.casafari.com (REST API) with your existing login, access tokens and contract. There is no migration and no account linking.
• MCP: sign up at https://platform.casafari.com/console/ and connect each product you use, such as https://platform.casafari.com/mcp/comparables (all URLs, Connect to the Casafari Platform). If you have a contract, Casafari sets your platform account up on Custom. Your Casafari REST API login and access tokens are not linked to it.

The self-serve platform's tokens and credits never apply to your REST API contract (quota versus tokens).

More: Existing API customers and which address to use.

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.

1. Create a key (cf_sk_…) in the console; it is shown once, so store it at once, and never put it in a URL.
2. Call GET https://platform.casafari.com/v1/locations/search?query=Lisbon with the key in the X-API-Key header, or as Authorization: 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).

Yes: the Free plan on the Casafari self-serve platform is a trial of 1,000 tokens for 30 days, and it needs no card.

Every operation costs a fixed number of tokens, the same over MCP and REST. Free includes every self-serve product. A Free account has 1 member, 2 API keys and 2 OAuth clients, and request guards of 2 requests in flight, 10 requests a minute, 50 per rolling 3 hours, 100 a day, 300 per rolling 7 days and 10 different places a day, free calls included, at most 500 tokens per rolling 3 hours, plus 4 Claro AI searches in all.

After the 30 days, place lookups and account status stay usable, and paid calls answer with a payment link. Free users may buy credits without subscribing, at €0.04 a token from €20, excluding VAT. Or compare the plans.

To start, sign up at platform.casafari.com. For existing Casafari REST API contracts, Casafari publishes no trial figures.

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.

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.

1. Tokens ran out: REST answers 402 payment_required with an upgrade_url and a Link header with rel="payment"; a platform MCP server answers a payment error with the same link (error page).
2. A 3-hour usage window is used up and no credits remain: REST answers 429 usage_limit_reached with the refill time, a Retry-After header and an upgrade_url to buy credits; MCP answers a payment error with the same members.
3. The spending cap is reached: 402 payment_required with the reason spending_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.

Casafari's products are grouped by what you want to do: find homes, value a home, understand an area, know the agencies and find premises. Every one is on the self-serve platform over REST, and the ones with an MCP server are also available to AI assistants.

• Find homes: Property Sourcing, Private Seller Leads, High Potential Seller Leads and New Market Leads.
• Value a home: Comparables & Valuation, Comparables with Transactions, Cadastre and Parcel Zoning.
• Understand an area: Area Insights.
• Know the agencies: AgencyGraph.
• Find premises: Claro AI.

Every tool and operation is listed in All tools, and MCP and REST compared shows which tools exist over which interface. Each operation costs tokens. Existing Casafari clients keep the Casafari REST API as it is (Existing API customers).

Casafari's API permissions list exactly 16 markets, and the documentation names no others. The market a given tool serves is only what that tool's own description says.

• Andorra (AD)
• United Arab Emirates (AE)
• Austria (AT)
• Belgium (BE)
• Switzerland (CH)
• Germany (DE)
• Spain (ES)
• France (FR)
• Greece (GR)
• Italy (IT)
• Luxembourg (LU)
• Monaco (MC)
• Poland (PL)
• Portugal (PT)
• San Marino (SM)
• United States (US)

The self-serve platform at platform.casafari.com covers the same 16 markets.

Not every tool covers every market: a few name a market in their own description, such as the existing API's place typeahead, which is scoped to Spain and Portugal (Comparables & Valuation, All tools). If the country you need is not on the list, ask Casafari. The documentation publishes no other country count.

See: Casafari API and MCP Platform, Comparables & Valuation, and the existing Casafari REST API's typeahead, POST /api/v1/references/locations/typeahead.

For anything not covered here, contact Casafari: https://www.casafari.com/

Add Casafari's MCP server, https://platform.casafari.com/mcp, to your client as a connector named Casafari and sign in with OAuth; no API key is needed, and every product's tools are there.

• Claude: open Customize → Connectors, choose + Add and Add custom connector, paste the URL and choose Connect (Claro AI alone is also in the Connectors Directory: Claro AI by Casafari). On Team and Enterprise plans only an organisation owner can add a custom connector, once, for everyone.
• ChatGPT: turn on Developer mode (Apps & Connectors, advanced settings), create a connector with the URL, choose OAuth, then sign in and approve.
• Claude Code: run claude mcp add --transport http casafari https://platform.casafari.com/mcp, then /mcp and Authenticate. The plugin in casafari/casafari-mcp does the same.
• Cursor: choose Add to Cursor in Casafari in the Cursor Directory, or add "casafari": { "url": "https://platform.casafari.com/mcp" } under mcpServers in ~/.cursor/mcp.json.

Sign in or create your self-serve platform account when asked. To check, ask the assistant to call account_status. A connector limited to one product uses that product's own server, https://platform.casafari.com/mcp/<product>. VS Code, Zed and other clients, and the per-product list, are in Connect your assistant and Connect to the Casafari Platform.

Request comparables around an address or a point, as in Casafari's example: a 3-bedroom flat near Avenida da Liberdade, Lisbon, with comparables within 1 km.

If you're a Casafari client: over the Casafari REST API, POST /api/v2/comparables/search and POST /api/v1/valuation/comparables-prices do the job. For an assistant, use the self-serve platform's Comparables MCP server like everyone else (below).

If you're new to Casafari: connect your assistant to https://platform.casafari.com/mcp/comparables and ask the same question, or from code call POST https://platform.casafari.com/v1/comparables/search with the same input as the MCP tool.

1. The assistant calls comparables_get_comparables with a circle. The target point is an address, coordinates or, in Spain only, a cadastral reference. The call also sets the distance in kilometres, operation sale, type apartment and bedrooms.
2. It returns comparables ranked by similarity, with price, area, status, dates and price-change history. It also returns aggregated statistics and fast-sell, fair-market and out-of-market price estimates.
3. Set sold_or_rented_after to a date to include properties sold or rented since then, or to null for active properties only.

Each comparables call costs 25 tokens on either.

See: Comparables & Valuation and What does Comparables & Valuation do?

Resolve the place to a location id, fetch a price time series from Area Insights, then compute growth and volatility with time-series operations.

If you're a Casafari client: over the Casafari REST API, POST /market-analytics-api/time-series returns the series. For an assistant, use the self-serve platform's MCP servers like everyone else (below).

If you're new to Casafari: over MCP, on the self-serve platform:

1. locations_search, on the Area Insights server itself (also on https://platform.casafari.com/mcp/locations): pass the place name and pick the location_id you want (location ids).
2. area-insights_get_time_series_data (https://platform.casafari.com/mcp/area-insights): request type_group apartment, business_type sale, data_point avg_price_psqm and date_interval month, with a date_range and the location ids. Each point holds one period's value.
3. area-insights_get_time_series_operations: request the same segment with operations such as mean, delta_pct, cagr, std and cv.

A place lookup costs 0 tokens; a time series and its operations cost 5 tokens each. Over REST, use https://platform.casafari.com/v1/area-insights, described in https://platform.casafari.com/v1/area-insights/openapi.json.

Casafari's example question: "How has the asking price per m² of flats in Valencia moved over the last three years?"

See: Area Insights and What is Area Insights?

Use a location lookup to turn a place name into location ids, then pass those ids to the operations that need them.

If you're a Casafari client: over the Casafari REST API, POST /api/v1/references/locations/typeahead is scoped to ES or PT. GET /api/v1/references/locations/by-coordinates resolves a point, and POST /api/v1/references/locations reads the location tree. Over MCP, use Location Lookup on the self-serve platform like everyone else (below).

If you're new to Casafari: use Location Lookup on the self-serve platform, over MCP at https://platform.casafari.com/mcp/locations (locations_search finds places by name, locations_get fetches one) or REST at https://platform.casafari.com/v1/locations. locations_search is also on the Area Insights MCP server, so a single Area Insights connector can find ids itself. Searching by name, fetching a place, reading its children and resolving coordinates all cost 0 tokens, for example GET https://platform.casafari.com/v1/locations/search?query=Lisbon. The ids work with the Area Insights tools.

• comparables_get_comparables needs no id: it takes coordinates, an address or a cadastral reference.

See: Area Insights and References.

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 an x-markdown-tokens header 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_config and open_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.