# Casafari MCP: frequently asked questions

> **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).

Answers to what people and agents ask about Casafari MCP: what it is, where it covers, its products and tools, access, connecting a client, sign-in, limits, worked examples, the data and pricing. Every question has a permalink of its own; every answer links the page that documents it.

## What Casafari MCP is

### What is Casafari MCP?

Casafari MCP is a single remote MCP server, `https://mcp.casafari.com/`, that gives an AI assistant or agent access to Casafari's real estate data: 22 data tools across 3 products.

Casafari describes itself as the AI agent-native real estate data intelligence platform. The server uses Streamable HTTP and signs you in with OAuth 2.1 through your Casafari account. It acts as a gateway: it signs the user in, checks the account's rights on every call, and forwards each tool to the service that owns it. The products available over MCP are [Comparables & Valuation](https://platform.casafari.com/docs/comparables-valuation), [Area Insights](https://platform.casafari.com/docs/area-insights) and [AgentGraph AI](https://platform.casafari.com/docs/agentgraph). The gateway also adds its own [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers), which shows which products your account can use. The same data is also available through a REST API.

See: [Casafari MCP](https://platform.casafari.com/docs), [Connect your assistant](https://platform.casafari.com/docs/connect), [All tools](https://platform.casafari.com/docs/tools), [The property graph](https://platform.casafari.com/docs/property-graph).

Permalink: https://platform.casafari.com/docs/faq/what-is-casafari-mcp

### What is Casafari?

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. Casafari describes the graph as the most complete property index in Europe ([why](https://platform.casafari.com/docs/faq#why-most-complete-property-index)).

Casafari calls itself the AI agent-native real estate data intelligence platform. Assistants, agents and applications access the graph through Casafari MCP and the REST API.

See [The property graph](https://platform.casafari.com/docs/property-graph) and https://www.casafari.com/.

Permalink: https://platform.casafari.com/docs/faq/what-is-casafari

### What is the Casafari MCP server URL?

The Casafari MCP server URL is `https://mcp.casafari.com/`. Every client uses the same address, served over Streamable HTTP with OAuth 2.1 sign-in.

Paste it wherever your client asks for a remote MCP server URL. The first connection opens Casafari's sign-in page. A request without a token returns `401` with a `WWW-Authenticate` header that points to the sign-in metadata, so a client that supports OAuth discovers the rest on its own. Don't confuse it with the REST API, which lives at `https://api.casafari.com` and uses email and password sign-in.

See: [Connect your assistant](https://platform.casafari.com/docs/connect) and [Authentication](https://platform.casafari.com/docs/authentication).

Permalink: https://platform.casafari.com/docs/faq/mcp-server-url

### What is the difference between Casafari MCP and the Casafari REST API?

Casafari MCP and the REST API serve the same property graph, but MCP serves assistants and agents and uses OAuth 2.1, while REST offers 39 operations and signs in with email and password.

- MCP: one server at `https://mcp.casafari.com/` over Streamable HTTP, with a gateway that checks your account's rights on every call. It offers 22 data tools plus [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers).
- REST: base URL `https://api.casafari.com`, with no gateway. [`POST /login`](https://platform.casafari.com/docs/rest/authentication/login) returns an access token and a refresh token (JWT), and [`GET /refresh-token`](https://platform.casafari.com/docs/rest/authentication/refresh-token) renews it. The public OpenAPI description is at https://docs.api.casafari.com/openapi.json.

Not everything is available over both. Properties, Alerts and References are REST only, AgentGraph AI is MCP only, and Area Insights and Comparables & Valuation differ in detail.

See: [MCP and REST compared](https://platform.casafari.com/docs/parity), [REST API](https://platform.casafari.com/docs/rest), [Authentication](https://platform.casafari.com/docs/authentication).

Permalink: https://platform.casafari.com/docs/faq/mcp-vs-rest-api

### What is the Casafari MCP gateway, and what does `list_servers` do?

The gateway is the Casafari MCP server: it signs you in, checks your rights on every call, and forwards each tool to the service that owns it; `list_servers` is a tool of the gateway itself.

[`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) takes no input. It returns every tool group your account can use, with each group's title, description, and usage instructions (for example, which tool to start with). Call it before you use a product for the first time.

`tools/list` already returns only the tools your subscription covers, and rights are checked again on every call, so a subscription change takes effect on your next request. If `tools/list` is empty or a tool is missing, your subscription doesn't cover it.

See: [Gateway](https://platform.casafari.com/docs/gateway) and [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers).

Permalink: https://platform.casafari.com/docs/faq/gateway-and-list-servers

### Which AI assistants and MCP clients work with Casafari MCP?

Casafari MCP works with any client that supports remote MCP servers over Streamable HTTP with OAuth. The Connect guide has steps for Claude, ChatGPT, Claude Code, Cursor and VS Code.

- Claude: add a custom connector with the server URL.
- ChatGPT: create a connector in Developer mode and select OAuth.
- Claude Code: run `claude mcp add --transport http casafari https://mcp.casafari.com/`.
- Cursor and VS Code: add an entry to `mcp.json`.
- Any other client or your own agent: point it at `https://mcp.casafari.com/`. It discovers the sign-in metadata from the `401` response and registers itself using dynamic client registration with PKCE.

In every case, you sign in with your Casafari account, and the assistant acts with that account's permissions.

See: [Connect your assistant](https://platform.casafari.com/docs/connect) and [Authentication](https://platform.casafari.com/docs/authentication).

Permalink: https://platform.casafari.com/docs/faq/supported-clients

## Coverage

### Which countries does Casafari cover?

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)

A few tools name a market in their own description. See [per-tool coverage](https://platform.casafari.com/docs/faq#per-tool-coverage). The documentation publishes no other country count.

See: [Casafari MCP](https://platform.casafari.com/docs), [AgentGraph AI](https://platform.casafari.com/docs/agentgraph), [Comparables & Valuation](https://platform.casafari.com/docs/comparables-valuation), [`POST /api/v1/references/locations/typeahead`](https://platform.casafari.com/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1).

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

Permalink: https://platform.casafari.com/docs/faq/which-countries

### Does Casafari cover Spain and Portugal?

Yes, Spain (ES) and Portugal (PT) are two of the 16 markets in Casafari's API permissions, and several tools mention them by name.

- The REST typeahead [`POST /api/v1/references/locations/typeahead`](https://platform.casafari.com/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1) is scoped by country code and accepts ES or PT.
- The comparables tool [`comps_get-comparables`](https://platform.casafari.com/docs/comparables-valuation/get-comparables) accepts a cadastral reference as its target point, but only for Spain.
- Casafari's own example questions are set in Lisbon (comparables within 1 km of Avenida da Liberdade) and Valencia (asking price per m² for flats over three years).

Other tools don't mention any market in their descriptions.

See: [Comparables & Valuation](https://platform.casafari.com/docs/comparables-valuation) and [Area Insights](https://platform.casafari.com/docs/area-insights).

Permalink: https://platform.casafari.com/docs/faq/coverage-spain-portugal

### Does Casafari cover Germany?

Yes: Germany (DE) is one of the 16 markets in Casafari's API permissions, and AgentGraph AI, the product for agencies and agents, is described for Germany.

[`agentgraph_find_location`](https://platform.casafari.com/docs/agentgraph/find_location) looks up German cities, districts and states by name and returns their location ids, and [`agentgraph_screen_agencies`](https://platform.casafari.com/docs/agentgraph/screen_agencies) ranks the agencies active in a German area against partner profiles. Casafari's example question is: Which independent agencies in München are growing faster than the market? Tools in the other products don't name a market in their descriptions, so for those the documentation says no more than the permissions list does.

See: [AgentGraph AI](https://platform.casafari.com/docs/agentgraph).

Permalink: https://platform.casafari.com/docs/faq/coverage-germany

### What if the country I need is not on the list?

If your market is not one of the 16 in Casafari's API permissions, this documentation does not cover it, and it publishes no roadmap.

The hub names no other country and gives no date for new markets. Don't assume a market is served just because a tool accepts coordinates or a polygon. Coverage is defined by the permissions list and by each tool's own description.

See [Which countries does Casafari cover?](https://platform.casafari.com/docs/faq#which-countries).

For a market outside the 16, contact Casafari: https://www.casafari.com/

Permalink: https://platform.casafari.com/docs/faq/country-not-listed

### Does every tool cover all 16 countries?

There is no per-tool country list: each tool covers what its own description says, and only three places in the documentation name a market.

- [AgentGraph AI](https://platform.casafari.com/docs/agentgraph): its tools look up German cities, districts and states, and screen agencies and agents in a German area.
- [`comps_get-comparables`](https://platform.casafari.com/docs/comparables-valuation/get-comparables): the cadastral-reference target point works in Spain only, while the coordinate and address inputs name no market.
- [`POST /api/v1/references/locations/typeahead`](https://platform.casafari.com/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1): accepts ES or PT country codes.

No other tool names a market, and the hub does not say which of the 16 markets each one serves.

See: [All tools](https://platform.casafari.com/docs/tools).

For a tool-by-tool answer, contact Casafari: https://www.casafari.com/

Permalink: https://platform.casafari.com/docs/faq/per-tool-coverage

## Products and tools

### Which products does Casafari MCP offer, and how many tools are there?

Casafari MCP offers 22 data tools across 3 products behind the gateway, plus `list_servers`. Three more products are available over the REST API only, 39 operations in all.

Over MCP:
- [Comparables & Valuation](https://platform.casafari.com/docs/comparables-valuation): 1 tool, `comps_get-comparables`.
- [Area Insights](https://platform.casafari.com/docs/area-insights): 8 tools, named `ma_…`.
- [AgentGraph AI](https://platform.casafari.com/docs/agentgraph): 13 tools, named `agentgraph_…`.
- Gateway: [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers), with no prefix.

Over REST only:
- [Properties](https://platform.casafari.com/docs/properties): 5 operations.
- [Alerts](https://platform.casafari.com/docs/alerts): 12 operations.
- [References](https://platform.casafari.com/docs/references): 10 operations.

Comparables & Valuation and Area Insights also have REST operations (4 and 6, respectively).

See [MCP and REST compared](https://platform.casafari.com/docs/parity), and find every tool's schema at `/tools.json`.

Permalink: https://platform.casafari.com/docs/faq/which-products

### What is Area Insights?

Area Insights is Casafari's product for analysing an area rather than a single home: price, supply and activity over time; distributions by price, bedrooms and time on market; and market analysis.

It offers 8 tools over MCP:
- [`ma_get_location_typeahead`](https://platform.casafari.com/docs/area-insights/get_location_typeahead): turns a place name (in English) into location ids.
- [`ma_get_time_series_data`](https://platform.casafari.com/docs/area-insights/get_time_series_data): one metric per week, month, quarter or year.
- [`ma_get_time_series_operations`](https://platform.casafari.com/docs/area-insights/get_time_series_operations): growth and volatility measures such as mean, delta_pct, CAGR, std and cv.
- [`ma_get_price_distribution`](https://platform.casafari.com/docs/area-insights/get_price_distribution), [`ma_get_bedrooms_distribution`](https://platform.casafari.com/docs/area-insights/get_bedrooms_distribution), [`ma_get_time_on_market_distribution`](https://platform.casafari.com/docs/area-insights/get_time_on_market_distribution).
- [`ma_get_heatmap`](https://platform.casafari.com/docs/area-insights/get_heatmap): a metric for each child location, such as the districts of a city.
- `ma_get_current_datetime`: today's date.

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

See [Area Insights](https://platform.casafari.com/docs/area-insights).

Permalink: https://platform.casafari.com/docs/faq/what-is-area-insights

### What does Comparables & Valuation do?

Comparables & Valuation returns comparable properties and estimated prices for a home, matched around a point, an address or a cadastral reference.

It draws on properties on the market, past sales and rentals, and official registry records.

Over MCP, it has 1 tool, [`comps_get-comparables`](https://platform.casafari.com/docs/comparables-valuation/get-comparables). The tool takes a circle (target point and radius in kilometres) or a closed polygon, an operation (sale or rent), property types and optional filters. It returns:

- Ranked comparables with a similarity score
- Aggregated statistics (average price, price per m², time on the market)
- Estimated prices: fast-sell, fair-market and out-of-market

The cadastral-reference input is for Spain only.

Over REST, it has 4 operations: [`POST /api/v1/comparables/search`](https://platform.casafari.com/docs/rest/comparables-valuation/search-comparables-v1), [`POST /api/v2/comparables/search`](https://platform.casafari.com/docs/rest/comparables-valuation/search-comparables-v2), [`POST /api/v1/valuation/comparables-prices`](https://platform.casafari.com/docs/rest/comparables-valuation/search-estimated-prices-v1) and the REST-only [`POST /api/v2/comparables/ai-builder`](https://platform.casafari.com/docs/rest/comparables-valuation/initialize-an-ai-builder-session-v2).

See [Comparables & Valuation](https://platform.casafari.com/docs/comparables-valuation) and its [REST API](https://platform.casafari.com/docs/rest/comparables-valuation).

Permalink: https://platform.casafari.com/docs/faq/what-is-comparables-valuation

### What is AgentGraph AI?

AgentGraph AI finds the real estate agencies and agents in Germany worth partnering with, using area screens against partner profiles, full profiles, territory maps, partner briefs and watchlists.

It offers 13 MCP tools and no REST operations:
- Locate: [`agentgraph_find_location`](https://platform.casafari.com/docs/agentgraph/find_location).
- Profiles: [`agentgraph_list_profiles`](https://platform.casafari.com/docs/agentgraph/list_profiles).
- Screen: [`agentgraph_screen_agencies`](https://platform.casafari.com/docs/agentgraph/screen_agencies), [`agentgraph_screen_agents`](https://platform.casafari.com/docs/agentgraph/screen_agents).
- Detail: `agentgraph_agency_profile`, `agentgraph_agent_profile`, [`agentgraph_partner_brief`](https://platform.casafari.com/docs/agentgraph/partner_brief).
- Area: [`agentgraph_territory_map`](https://platform.casafari.com/docs/agentgraph/territory_map), `agentgraph_area_benchmark`.
- Watchlist: [`agentgraph_save_to_watchlist`](https://platform.casafari.com/docs/agentgraph/save_to_watchlist), `agentgraph_remove_from_watchlist`, `agentgraph_watchlist`, `agentgraph_watchlist_changes`.

Casafari's example question: Which independent agencies in München are growing faster than the market?

See [AgentGraph AI](https://platform.casafari.com/docs/agentgraph).

Permalink: https://platform.casafari.com/docs/faq/what-is-agentgraph

### Can I search properties over Casafari MCP?

No. Properties is available only over the REST API, with 5 operations and no MCP tool, so an assistant can't search the property graph through Casafari MCP.

Over REST you can:
- search with structured filters: [`POST /api/v2/properties/search`](https://platform.casafari.com/docs/rest/properties/search-properties-v2) (and [`POST /api/v1/properties/search`](https://platform.casafari.com/docs/rest/properties/search-properties-v1));
- fetch a property and its history by id: [`GET /api/v1/properties/search/{property_id}`](https://platform.casafari.com/docs/rest/properties/get-property-by-id-v1);
- resolve a portal or agency ad id to its property: [`POST /api/v1/properties/match-by-listings`](https://platform.casafari.com/docs/rest/properties/get-property-by-listing-ids-v1);
- create shareable links: [`POST /api/v1/properties/smart-links`](https://platform.casafari.com/docs/rest/properties/create-a-smart-link-beta-v1) (BETA).

Each property is a single record with its price and status history. The closest options over MCP are comparables around a point (Comparables & Valuation) and area statistics (Area Insights).

See: [Properties](https://platform.casafari.com/docs/properties), [Properties REST API](https://platform.casafari.com/docs/rest/properties), [MCP and REST compared](https://platform.casafari.com/docs/parity).

Permalink: https://platform.casafari.com/docs/faq/properties-over-mcp

### Can I get alerts (new properties, price cuts, sales) over Casafari MCP?

No. Alerts is available only through the REST API, which has 12 operations; there is no MCP tool.

An alert feed tracks the property graph for a set of filters and reports new properties, price rises and cuts, reservations, removals and sales. You can create a feed, read its alerts, or have them delivered to your webhook:
- [`POST /alerts-api/feeds`](https://platform.casafari.com/docs/rest/alerts/create-feed) creates a feed, and [`GET /alerts-api/feeds`](https://platform.casafari.com/docs/rest/alerts/list-feeds) returns your feeds.
- [`PUT /alerts-api/webhooks`](https://platform.casafari.com/docs/rest/alerts/set-webhook-url) sets the webhook URL, and [`POST /alerts-api/webhooks/rotate-secret`](https://platform.casafari.com/docs/rest/alerts/rotate-signing-secret) rotates the signing secret.
- The v1 operations under `/api/v1/listing-alerts/` create, read, update and delete feeds, and search alerts.

See: [Alerts](https://platform.casafari.com/docs/alerts), [Alerts REST API](https://platform.casafari.com/docs/rest/alerts), [MCP and REST compared](https://platform.casafari.com/docs/parity).

Permalink: https://platform.casafari.com/docs/faq/alerts-over-mcp

### What are the References operations for?

References is the REST-only set of 10 operations that return the reference data other requests are built from: property types, features, conditions, agencies, agents, sources, locations and zip-code boundaries.

- [`GET /api/v1/references/types`](https://platform.casafari.com/docs/rest/references/get-types-v1), [`GET /api/v1/references/features`](https://platform.casafari.com/docs/rest/references/get-features-v1), [`GET /api/v1/references/conditions`](https://platform.casafari.com/docs/rest/references/get-conditions-v1): the values property filters accept, including which countries each type is available in.
- [`GET /api/v1/references/agencies`](https://platform.casafari.com/docs/rest/references/get-agencies-v1), `GET /api/v1/references/agents`, `GET /api/v1/references/sources`: agencies, agents and the sources the graph is built from.
- [`POST /api/v1/references/locations`](https://platform.casafari.com/docs/rest/references/get-locations-v1), `GET /api/v1/references/locations/by-coordinates`, `POST /api/v1/references/locations/typeahead`: the location tree, looked up by name, by coordinates or by typeahead scoped to ES or PT.
- [`POST /api/v1/references/zipcode-boundary`](https://platform.casafari.com/docs/rest/references/get-zipcode-boundary-by-zipcode-and-country-code-v1): the boundary of a zip code within a country.

References has no MCP tool. Over MCP, `ma_get_location_typeahead` resolves place names.

See: [References](https://platform.casafari.com/docs/references) and [References REST API](https://platform.casafari.com/docs/rest/references).

Permalink: https://platform.casafari.com/docs/faq/what-is-references

### Which tools exist only over MCP, and which operations only over REST?

Three Area Insights tools and all 13 AgentGraph AI tools are available only over MCP; Properties, Alerts, References, the comparables AI builder, and two Area Insights operations are available only over REST.

MCP only:
- [`ma_get_current_datetime`](https://platform.casafari.com/docs/area-insights/get_current_datetime), [`ma_get_time_series_operations`](https://platform.casafari.com/docs/area-insights/get_time_series_operations), and [`ma_get_heatmap`](https://platform.casafari.com/docs/area-insights/get_heatmap).
- Every `agentgraph_…` tool.

REST only:
- All 5 Properties, 12 Alerts, and 10 References operations.
- [`POST /api/v2/comparables/ai-builder`](https://platform.casafari.com/docs/rest/comparables-valuation/initialize-an-ai-builder-session-v2).
- [`POST /market-analytics-api/distributions/properties`](https://platform.casafari.com/docs/rest/area-insights/properties-distribution) and [`POST /market-analytics-api/analysis`](https://platform.casafari.com/docs/rest/area-insights/analysis).

Everything else is available over both: comparables search and the Area Insights time series and distributions.

See [MCP and REST compared](https://platform.casafari.com/docs/parity).

Permalink: https://platform.casafari.com/docs/faq/mcp-only-and-rest-only

### How are Casafari MCP tools named?

Casafari MCP tools follow the pattern `<group>_<tool>`, such as `comps_get-comparables` or `ma_get_heatmap`. The only tool without a prefix is the gateway's `list_servers`.

The group is the product namespace: `comps` for Comparables & Valuation, `ma` for Area Insights, and `agentgraph` for AgentGraph AI. The tool part is whatever name the owning service uses, so it can contain hyphens or underscores. Clients call each tool by its exact name, and the documentation always writes names exactly as they are called. [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) returns the namespaces available to your account, and `/tools.json` gives every tool's name, title, input schema and output schema.

See: [All tools](https://platform.casafari.com/docs/tools) and [/tools.json](https://platform.casafari.com/tools.json).

Permalink: https://platform.casafari.com/docs/faq/tool-naming

## Access

### Who can use Casafari MCP?

Anyone with a Casafari account that has an MCP subscription can use Casafari MCP. A token carries exactly that account's rights, and nothing works without one.

To connect a client, you sign in with the account in a browser and approve. The assistant then acts with that account's rights. `tools/list` shows only the tools your subscription covers, and rights are resolved on every call. An agent that runs unattended uses client credentials that Casafari issues for the account. If you don't have a Casafari account, get one first. Without one, the sign-in flow has nothing to grant.

See: [Connect your assistant](https://platform.casafari.com/docs/connect), [Authentication](https://platform.casafari.com/docs/authentication), [casafari.com/auth.md](https://www.casafari.com/auth.md).

Permalink: https://platform.casafari.com/docs/faq/who-can-use

### How do I get access to Casafari MCP, and is there a free trial?

Contact Casafari through the "Contact us" button on its MCP page (https://www.casafari.com/products/property-data-mcp-ai-agents/), since access requires a Casafari account with an MCP subscription.

The casafari.com navigation also shows a "Start free trial" button, but the documentation doesn't say what a trial includes.

Once you have an account, connecting takes a minute: paste `https://mcp.casafari.com/` into your client, sign in, and approve. Your assistant will then see exactly the tools your subscription covers.

See: [Connect your assistant](https://platform.casafari.com/docs/connect).

Permalink: https://platform.casafari.com/docs/faq/how-to-get-access

### Do I need an API key for Casafari MCP?

No, Casafari MCP doesn't use an API key: you sign in with OAuth 2.1 through your Casafari account, and the token you get carries that account's rights.

- Interactive clients (Claude, ChatGPT, Cursor, VS Code, Claude Code) open Casafari's sign-in page the first time you connect, so you never paste a credential.
- Your own client registers itself and uses PKCE, so it needs no secret.
- An agent with no person to approve uses a `client_id` and `client_secret` that Casafari issues for the account (client credentials grant).
- The REST API works differently: [`POST /login`](https://platform.casafari.com/docs/rest/authentication/login) with email and password returns a JWT access token and a refresh token.

See: [Authentication](https://platform.casafari.com/docs/authentication) and [casafari.com/auth.md](https://www.casafari.com/auth.md).

Permalink: https://platform.casafari.com/docs/faq/api-key

## Connect a client

### How do I connect Casafari MCP to Claude?

In Claude, go to Settings → Connectors, choose Add custom connector, name it `Casafari`, paste `https://mcp.casafari.com/` as the URL, and connect.

1. Open **Settings → Connectors** and choose **Add custom connector**.
2. Name it `Casafari` and paste `https://mcp.casafari.com/` as the URL.
3. Choose **Connect**, sign in with your Casafari account, and approve.

On Team and Enterprise, an owner first adds the connector for the organisation, and then members connect their own accounts. To check that it works, ask: "Which Casafari products can I use?" Claude should call [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) and name the products your subscription covers.

See: [Connect your assistant](https://platform.casafari.com/docs/connect).

Permalink: https://platform.casafari.com/docs/faq/connect-claude

### How do I connect Casafari MCP to ChatGPT?

In ChatGPT, turn on Developer mode, create a connector with `https://mcp.casafari.com/` as the MCP server URL, choose OAuth, then sign in with your Casafari account and approve.

1. In ChatGPT's settings, turn on **Developer mode** (under Apps & Connectors, in the advanced settings).
2. Create a connector, paste `https://mcp.casafari.com/` as the MCP server URL, and choose OAuth.
3. Sign in with your Casafari account and approve.

ChatGPT then acts with your account's permissions, so it sees only the tools your subscription covers. To check, ask which Casafari products you can use. It should call [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) and name them.

See: [Connect your assistant](https://platform.casafari.com/docs/connect).

Permalink: https://platform.casafari.com/docs/faq/connect-chatgpt

### How do I add Casafari MCP to Claude Code?

Run `claude mcp add --transport http casafari https://mcp.casafari.com/`, then run `/mcp` in Claude Code and choose Authenticate for `casafari`.

1. In a terminal, run `claude mcp add --transport http casafari https://mcp.casafari.com/`.
2. In Claude Code, run `/mcp`.
3. Choose **Authenticate** for `casafari`, sign in to your Casafari account in the browser, and approve access.

The `--transport http` flag selects the Streamable HTTP transport. After you authenticate, Claude Code shows the tools your subscription covers. Call [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) first to read each product's instructions.

See [Connect your assistant](https://platform.casafari.com/docs/connect).

Permalink: https://platform.casafari.com/docs/faq/connect-claude-code

### How do I add Casafari MCP to Cursor?

Add a `casafari` entry with the URL `https://mcp.casafari.com/` under `mcpServers` in `~/.cursor/mcp.json`, or in `.cursor/mcp.json` within a project.

```json
{
  "mcpServers": {
    "casafari": { "url": "https://mcp.casafari.com/" }
  }
}
```

Cursor opens Casafari's sign-in page the first time it connects; sign in with your Casafari account and approve. The server uses Streamable HTTP with OAuth, so no key goes in the file. Once connected, the tools your subscription covers appear; start with [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers).

See: [Connect your assistant](https://platform.casafari.com/docs/connect).

Permalink: https://platform.casafari.com/docs/faq/connect-cursor

### How do I add Casafari MCP to VS Code?

In `.vscode/mcp.json`, add a `casafari` server under `servers` with `"type": "http"` and the URL `https://mcp.casafari.com/`.

```json
{
  "servers": {
    "casafari": { "type": "http", "url": "https://mcp.casafari.com/" }
  }
}
```

VS Code opens Casafari's sign-in page the first time it connects; sign in with your Casafari account and approve. The server uses Streamable HTTP with OAuth, so no key goes in the file. Once connected, the tools your subscription covers appear; start with [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers).

See: [Connect your assistant](https://platform.casafari.com/docs/connect).

Permalink: https://platform.casafari.com/docs/faq/connect-vscode

### How do I connect any other MCP client or my own agent?

Point the client at `https://mcp.casafari.com/` and let it register itself and sign in with PKCE. The `401` it receives carries a `WWW-Authenticate` header that points to the sign-in metadata.

1. Fetch the protected resource metadata named in the header, then the authorization server metadata it points to.
2. Register once at the registration endpoint (dynamic client registration) and keep the `client_id`.
3. Send the person to the authorization endpoint with PKCE, `state` and `resource`, then exchange the code for tokens.
4. Call the server with `Authorization: Bearer <access_token>`, and refresh the token when it expires.

An agent that runs without a person to sign in can't register itself. Instead, it uses client credentials that Casafari issues for the account. Call [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) before using a product.

See: [Connect your assistant](https://platform.casafari.com/docs/connect), [Authentication](https://platform.casafari.com/docs/authentication), [casafari.com/auth.md](https://www.casafari.com/auth.md).

Permalink: https://platform.casafari.com/docs/faq/connect-other-client

### How do I check that Casafari MCP is connected and working?

Ask your assistant which Casafari products you can use: it should call `list_servers` and name the products your subscription covers.

If it does, your connection, sign-in and access rights all work. If the assistant can't see the server, check that the URL is exactly `https://mcp.casafari.com/` and that the client completed the OAuth sign-in. If a product or tool you expected is missing, that isn't a connection fault: `tools/list` returns only the tools your subscription covers, so retrying won't help. If a connection that used to work returns a `401` with `invalid_token`, the token has expired or been revoked: let the client refresh it, or sign in again.

See: [Connect your assistant](https://platform.casafari.com/docs/connect), [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers), [Why is a tool missing or a call refused?](https://platform.casafari.com/docs/faq#tool-missing-or-refused).

Permalink: https://platform.casafari.com/docs/faq/verify-connection

## Authentication

### How does authentication work on Casafari MCP? Does it use OAuth scopes?

Casafari MCP is an OAuth 2.1 resource server with no OAuth scopes: a token carries exactly the rights of the Casafari account that signed in.

`scopes_supported` in the protected resource metadata is empty on purpose. Rights are per tool and resolved from the account on every call, so `tools/list` shows only what the subscription covers, and any change takes effect on the next request. A person signs in through the authorization code flow with PKCE. An unattended agent uses client credentials issued by Casafari. Tokens are bound to the server's canonical URL as their audience, so every authorization and token request includes `resource`. The REST API works differently: you sign in with email and password to get a JWT.

See: [Authentication](https://platform.casafari.com/docs/authentication), [casafari.com/auth.md](https://www.casafari.com/auth.md), [REST API](https://platform.casafari.com/docs/rest).

Permalink: https://platform.casafari.com/docs/faq/how-authentication-works

### How does a client discover Casafari's authorization server?

A client discovers it in two hops: the `WWW-Authenticate` header on a `401` response points to the protected resource metadata at `https://mcp.casafari.com/.well-known/oauth-protected-resource`, and that document points to the authorization server at `https://api.casafari.com/.well-known/oauth-authorization-server`.

1. Read the protected resource metadata for `resource`, `authorization_servers`, `scopes_supported` (intentionally empty) and `resource_documentation`. `resource` is the server's canonical URL. Send it as the `resource` parameter in every authorization and token request, because tokens are bound to it as their audience.
2. Read the authorization server metadata for `registration_endpoint`, `authorization_endpoint` and `token_endpoint`. Take the supported grant types, code challenge methods and auth methods from this metadata, not from a guide.

Read the live documents, not a copy. A token minted without `resource` has no audience, and the server rejects it.

See: [Authentication](https://platform.casafari.com/docs/authentication) and [casafari.com/auth.md](https://www.casafari.com/auth.md).

Permalink: https://platform.casafari.com/docs/faq/oauth-discovery

### Can my MCP client register itself with Casafari?

Yes, a client that acts for a signed-in person can register itself once at the registration endpoint; a client with no person to sign in cannot, and uses credentials Casafari issues instead.

Send a `POST` with `client_name`, your `redirect_uris`, `grant_types` set to `["authorization_code", "refresh_token"]`, and `token_endpoint_auth_method` set to `none`. Each redirect URI must use `https`, `http` on a loopback host, or a private-use scheme, and must not include a fragment. Any other grant type, redirect URI, or auth method is rejected with `400 invalid_client_metadata`, so never request `client_credentials` there. The `201` response contains the `client_id`. Store it and don't register again. A public client has no secret and authenticates with PKCE (`S256`).

See: [Authentication](https://platform.casafari.com/docs/authentication) and [casafari.com/auth.md](https://www.casafari.com/auth.md).

Permalink: https://platform.casafari.com/docs/faq/dynamic-client-registration

### How does an agent sign in when no person is there to approve?

An agent that runs with no person present signs in with the client credentials grant, using a `client_id` and `client_secret` that Casafari issues for the account. The agent cannot register itself.

1. The account owner gets the credentials from Casafari and gives them to the agent.
2. The agent posts `grant_type=client_credentials` and `resource` to the token endpoint. It authenticates with HTTP Basic (`client_id:client_secret`) or by sending the secret in the form body (`client_secret_post`).
3. It then calls `https://mcp.casafari.com/` with `Authorization: Bearer <access_token>`, exactly as a user-authorized client does.

Requesting `client_credentials` from the registration endpoint fails with `400 invalid_client_metadata`. The token still carries only the account's rights.

See: [Authentication](https://platform.casafari.com/docs/authentication) and [casafari.com/auth.md](https://www.casafari.com/auth.md).

Permalink: https://platform.casafari.com/docs/faq/unattended-agents

### What happens when my access token expires?

When your access token expires, exchange the refresh token at the token endpoint with `grant_type=refresh_token`, your `client_id`, and `resource`; the `expires_in` value in the token response is the authoritative lifetime.

A `401` with `error="invalid_token"` on a token that used to work means it has expired, been revoked, or is bound to another resource. Refresh it, and if the refresh fails, send the person through authorization again. Keep the client and its `client_id`; don't register again. The documentation publishes no token lifetime beyond `expires_in`. For the REST API, [`GET /refresh-token`](https://platform.casafari.com/docs/rest/authentication/refresh-token) renews the JWT, and a `401` from that endpoint means you need to log in again.

See: [Authentication](https://platform.casafari.com/docs/authentication) and [casafari.com/auth.md](https://www.casafari.com/auth.md).

Permalink: https://platform.casafari.com/docs/faq/token-expiry-refresh

### How do I authenticate with the Casafari REST API?

Authenticate with the Casafari REST API by sending your `email` and `password` as JSON to `POST https://api.casafari.com/login`. It returns a JWT access token and a refresh token; the API doesn't use OAuth.

1. Send `{ "email": …, "password": … }` to [`POST /login`](https://platform.casafari.com/docs/rest/authentication/login). It responds `200` with `access_token` and `refresh_token`.
2. Include `Authorization: Bearer <access_token>` when you call any operation.
3. To get a new `access_token`, call [`GET /refresh-token`](https://platform.casafari.com/docs/rest/authentication/refresh-token) with the refresh token as the bearer.

A `401` from either endpoint means the credentials are wrong or the refresh token has expired, so log in again. A `422` from `/login` means the body is malformed, so send `email` and `password` as JSON. After you sign in, https://docs.api.casafari.com/ shows which operations your account may call.

See: [REST API](https://platform.casafari.com/docs/rest) and [REST authentication](https://platform.casafari.com/docs/rest/authentication).

Permalink: https://platform.casafari.com/docs/faq/rest-authentication

## Limits, quotas and errors

### What are Casafari MCP's rate limits and quotas?

The documentation publishes no rate-limit or quota figures; the only documented limit is per product, and once a product's quota is used up, its tools return `Request limit reached for this product.`

This message is a tool error, not an HTTP status. Stop calling that product and don't retry; the other products keep working. A missing tool or a refused call means something else: your subscription doesn't cover it. For `5xx` responses, retry with exponential backoff.

See: [Authentication](https://platform.casafari.com/docs/authentication) (errors table).

For quota and rate-limit figures, contact Casafari: https://www.casafari.com/

Permalink: https://platform.casafari.com/docs/faq/rate-limits-and-quotas

### Why is a tool missing from `tools/list`, or a call refused?

If a tool is missing from `tools/list` or a call is refused, your account's subscription does not cover that tool, so retrying will not help.

`tools/list` returns only the tools your subscription covers, and the gateway checks rights again on every call. A subscription change in either direction takes effect on the next request, so there is nothing to reconnect or clear. To see which products you can use, call [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers).

This differs from two other errors:

- `Request limit reached for this product.` means the product's quota is used up.
- `401 invalid_token` means the token has expired or been revoked.

See: [Authentication](https://platform.casafari.com/docs/authentication) and [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers).

Permalink: https://platform.casafari.com/docs/faq/tool-missing-or-refused

### Which Casafari MCP errors should I retry, and which not?

Retry only `5xx` responses, using exponential backoff; every other documented error calls for a fix on your side, not a retry.

- `400 invalid_client_metadata` (registration): fix the request, and never request `client_credentials` there.
- `401 invalid_client` (token endpoint): check the credential.
- `401 invalid_token` (MCP server): refresh the token; if that fails, authorize again.
- Tool missing or call refused: don't retry, because your subscription doesn't cover it.
- `Request limit reached for this product.`: stop calling that product.
- REST `401` on `/login` or `/refresh-token`: log in again. REST `422` on `/login`: send `email` and `password` as JSON.

See the errors table in [Authentication](https://platform.casafari.com/docs/authentication) and [casafari.com/auth.md](https://www.casafari.com/auth.md).

Permalink: https://platform.casafari.com/docs/faq/which-errors-to-retry

## Use cases and worked examples

### How do I value a home or find comparables with Casafari MCP?

To value a home or find comparables, ask your assistant for comparables around an address, as in Casafari's example: a 3-bedroom flat near Avenida da Liberdade, Lisbon, with comparables within 1 km.

1. The assistant calls [`comps_get-comparables`](https://platform.casafari.com/docs/comparables-valuation/get-comparables) with a circle. The target point is the address, coordinates or, in Spain, a cadastral reference, and the call also includes 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.

Over REST, [`POST /api/v2/comparables/search`](https://platform.casafari.com/docs/rest/comparables-valuation/search-comparables-v2) and [`POST /api/v1/valuation/comparables-prices`](https://platform.casafari.com/docs/rest/comparables-valuation/search-estimated-prices-v1) do the same job. For area-level questions, first resolve the place with [`ma_get_location_typeahead`](https://platform.casafari.com/docs/area-insights/get_location_typeahead).

See: [Comparables & Valuation](https://platform.casafari.com/docs/comparables-valuation).

Permalink: https://platform.casafari.com/docs/faq/example-valuation

### How do I analyse how prices in an area have moved over time?

Resolve the place to a location id with `ma_get_location_typeahead`, fetch the series with `ma_get_time_series_data`, then calculate growth and volatility with `ma_get_time_series_operations`.

1. [`ma_get_location_typeahead`](https://platform.casafari.com/docs/area-insights/get_location_typeahead): pass the place name in English and pick the `location_id` you want. Check the breadcrumbs when names repeat.
2. [`ma_get_time_series_data`](https://platform.casafari.com/docs/area-insights/get_time_series_data): 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. [`ma_get_time_series_operations`](https://platform.casafari.com/docs/area-insights/get_time_series_operations): request the same segment with operations such as `mean`, `delta_pct`, `cagr`, `std` and `cv`.

Casafari's example question: How has the asking price per m² of flats in Valencia moved over the last three years? Over REST, [`POST /market-analytics-api/time-series`](https://platform.casafari.com/docs/rest/area-insights/time-series) returns the series.

See: [Area Insights](https://platform.casafari.com/docs/area-insights).

Permalink: https://platform.casafari.com/docs/faq/example-price-trend

### How do I see how properties are distributed by price, bedrooms or time on market, or get a heatmap?

Area Insights has a tool for each distribution (`ma_get_price_distribution`, `ma_get_bedrooms_distribution` and `ma_get_time_on_market_distribution`) plus `ma_get_heatmap`, which shows a metric for each district.

- [`ma_get_price_distribution`](https://platform.casafari.com/docs/area-insights/get_price_distribution): returns price intervals, the number of properties in each, and a flag marking the interval that contains the mean.
- [`ma_get_bedrooms_distribution`](https://platform.casafari.com/docs/area-insights/get_bedrooms_distribution): returns, for each bedroom count, the number of properties, the average price and the average price per m².
- [`ma_get_time_on_market_distribution`](https://platform.casafari.com/docs/area-insights/get_time_on_market_distribution): returns, for each price interval, the average days and months on the market and the number of properties.
- [`ma_get_heatmap`](https://platform.casafari.com/docs/area-insights/get_heatmap): returns the chosen `data_point` for the child locations of a `location_id` (the districts of a city), based on active properties only. Available over MCP only.

All four take a `type_group`, a `business_type` and a location boundary (ids or a circle). The [price](https://platform.casafari.com/docs/rest/area-insights/price-distribution), [bedrooms](https://platform.casafari.com/docs/rest/area-insights/bedrooms-distribution) and [time on market](https://platform.casafari.com/docs/rest/area-insights/time-on-market-distribution) distributions are also available over REST.

See: [Area Insights](https://platform.casafari.com/docs/area-insights).

Permalink: https://platform.casafari.com/docs/faq/example-distributions-heatmap

### Can I build a market report with Casafari MCP?

Yes: Casafari MCP supplies the figures and your assistant writes the report, though the hub documents tools, not report formats or exports.

An area report draws on Area Insights: the time series and its operations for trend and volatility, the distributions of price, bedrooms and time on market, and [`ma_get_heatmap`](https://platform.casafari.com/docs/area-insights/get_heatmap) for the districts. A report on a single home draws on [`comps_get-comparables`](https://platform.casafari.com/docs/comparables-valuation/get-comparables) for comparables and estimated prices. [`ma_get_current_datetime`](https://platform.casafari.com/docs/area-insights/get_current_datetime) gives the assistant today's date for setting date ranges. Count properties rather than advertisements, since each record in the graph already merges every source. No template, PDF export or scheduling is documented.

See: [Area Insights](https://platform.casafari.com/docs/area-insights) and [The property graph](https://platform.casafari.com/docs/property-graph).

Permalink: https://platform.casafari.com/docs/faq/example-market-report

### How do I find agencies or agents to partner with in a German city?

Use AgentGraph AI: find the location, review the partner profiles, screen agencies or agents, open a profile, get a partner brief, then watch the ones you choose.

1. [`agentgraph_find_location`](https://platform.casafari.com/docs/agentgraph/find_location): use this when a name is ambiguous or you want a district.
2. [`agentgraph_list_profiles`](https://platform.casafari.com/docs/agentgraph/list_profiles): see the rules behind each profile.
3. [`agentgraph_screen_agencies`](https://platform.casafari.com/docs/agentgraph/screen_agencies) or [`agentgraph_screen_agents`](https://platform.casafari.com/docs/agentgraph/screen_agents): screen the area, optionally with a profile, postcodes and thresholds.
4. `agentgraph_agency_profile` or `agentgraph_agent_profile`: view one result in full.
5. [`agentgraph_partner_brief`](https://platform.casafari.com/docs/agentgraph/partner_brief): get a one-page brief with a printable page valid for 7 days.
6. [`agentgraph_save_to_watchlist`](https://platform.casafari.com/docs/agentgraph/save_to_watchlist), then [`agentgraph_watchlist_changes`](https://platform.casafari.com/docs/agentgraph/watchlist_changes) (default: the last 7 days).

For area context, use `agentgraph_area_benchmark` and `agentgraph_territory_map`. Example from Casafari: "Which independent agencies in München are growing faster than the market?" Germany only.

See: [AgentGraph AI](https://platform.casafari.com/docs/agentgraph).

Permalink: https://platform.casafari.com/docs/faq/example-find-agencies-germany

### How do I look up one property and its price history?

Use the REST API: `GET /api/v1/properties/search/{property_id}` returns a single property with its history, and `POST /api/v1/properties/match-by-listings` resolves an ad id from a portal or agency to its property.

1. If you have an ad id from a portal or agency site, call [`POST /api/v1/properties/match-by-listings`](https://platform.casafari.com/docs/rest/properties/get-property-by-listing-ids-v1) to find the property it belongs to.
2. If you have a property id, call [`GET /api/v1/properties/search/{property_id}`](https://platform.casafari.com/docs/rest/properties/get-property-by-id-v1). The record includes `sale_price_history` and `rent_price_history`, with dates and statuses such as active, reserved, hold, sold and rented.
3. To find properties, use [`POST /api/v2/properties/search`](https://platform.casafari.com/docs/rest/properties/search-properties-v2) with structured filters.
4. To share a property, create a smart link with [`POST /api/v1/properties/smart-links`](https://platform.casafari.com/docs/rest/properties/create-a-smart-link-beta-v1) (BETA).

No MCP tool is available for this.

See: [Properties](https://platform.casafari.com/docs/properties) and [The property graph](https://platform.casafari.com/docs/property-graph).

Permalink: https://platform.casafari.com/docs/faq/example-property-lookup

### How do I turn a place name into a location id?

Use `ma_get_location_typeahead` to turn an English place name into location ids. Most Casafari tools take a location as ids, a circle or a polygon rather than a name.

- Over MCP, [`ma_get_location_typeahead`](https://platform.casafari.com/docs/area-insights/get_location_typeahead) returns each match with its `location_id`, administrative level and breadcrumbs. If several places share a name, add more detail to the request. The ids it returns work with the Area Insights tools.
- For Germany, [`agentgraph_find_location`](https://platform.casafari.com/docs/agentgraph/find_location) finds cities, districts and states. The AgentGraph AI tools also accept a name or a postcode directly.
- Over REST, [`POST /api/v1/references/locations/typeahead`](https://platform.casafari.com/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1) is scoped to ES or PT. [`GET /api/v1/references/locations/by-coordinates`](https://platform.casafari.com/docs/rest/references/get-location-by-passed-coordinates-v1) resolves a point, and [`POST /api/v1/references/locations`](https://platform.casafari.com/docs/rest/references/get-locations-v1) reads the location tree.

`comps_get-comparables` doesn't need an id. It takes coordinates, an address or a cadastral reference.

See: [Area Insights](https://platform.casafari.com/docs/area-insights) and [References](https://platform.casafari.com/docs/references).

Permalink: https://platform.casafari.com/docs/faq/location-ids

### How do I get alerts delivered to a webhook?

Use the REST API: create a feed with `POST /alerts-api/feeds`, set your webhook URL with `PUT /alerts-api/webhooks`, and rotate its signing secret with `POST /alerts-api/webhooks/rotate-secret`.

1. [`POST /alerts-api/feeds`](https://platform.casafari.com/docs/rest/alerts/create-feed) creates a feed for a set of filters. [`GET /alerts-api/feeds`](https://platform.casafari.com/docs/rest/alerts/list-feeds) and [`GET /alerts-api/feeds/{feed_id}`](https://platform.casafari.com/docs/rest/alerts/get-feed) read feeds, and [`DELETE /alerts-api/feeds/{feed_id}`](https://platform.casafari.com/docs/rest/alerts/delete-feed) removes one.
2. [`PUT /alerts-api/webhooks`](https://platform.casafari.com/docs/rest/alerts/set-webhook-url) sets the URL that alerts are delivered to.
3. [`POST /alerts-api/webhooks/rotate-secret`](https://platform.casafari.com/docs/rest/alerts/rotate-signing-secret) rotates the secret used to sign deliveries.

The v1 operations under `/api/v1/listing-alerts/` create, read, update and delete feeds and search alerts without a webhook. Alerts cover new properties, price rises and cuts, reservations, removals and sales. There is no MCP tool.

See: [Alerts](https://platform.casafari.com/docs/alerts) and [Alerts REST API](https://platform.casafari.com/docs/rest/alerts).

Permalink: https://platform.casafari.com/docs/faq/alerts-webhook

### How do I build my own application or agent on Casafari MCP?

Connect to `https://mcp.casafari.com/` over Streamable HTTP, complete OAuth 2.1 (discovery, registration, PKCE authorization, and token), then call `list_servers` and read each tool's schema in `/tools.json`.

1. Discover: the `401` response points to the protected resource metadata, which in turn points to the authorization server metadata.
2. Register once with dynamic client registration and keep the `client_id`. An unattended agent uses client credentials issued by Casafari instead.
3. Authorize with PKCE and `resource`, exchange the code, then call with `Authorization: Bearer <access_token>`. Refresh when `expires_in` runs out.
4. Call [`list_servers`](https://platform.casafari.com/docs/gateway/list_servers) before using a product. Read each tool's description and input schema, because they are the contract.

Machine-readable helpers: [/tools.json](https://platform.casafari.com/tools.json), the [MCP server card](https://platform.casafari.com/.well-known/mcp/server-card.json), and the [agent skill](https://platform.casafari.com/.well-known/agent-skills/index.json).

See [Authentication](https://platform.casafari.com/docs/authentication) and [For AI agents](https://platform.casafari.com/docs/agents).

Permalink: https://platform.casafari.com/docs/faq/build-on-mcp

### How do I build on the Casafari REST API?

The Casafari REST API lives at `https://api.casafari.com`. It has 39 operations and no gateway, uses a JWT from `POST /login`, and publishes a public OpenAPI description at https://docs.api.casafari.com/openapi.json.

1. Read the OpenAPI document for the base catalogue. After you sign in, https://docs.api.casafari.com/ shows your account's own operations.
2. Call [`POST /login`](https://platform.casafari.com/docs/rest/authentication/login) with your email and password, send the access token as a bearer token, and renew it with [`GET /refresh-token`](https://platform.casafari.com/docs/rest/authentication/refresh-token).
3. Build reference lookups from [References](https://platform.casafari.com/docs/references), then call the product operations you need: Properties, Comparables & Valuation, Area Insights and Alerts.

[MCP and REST compared](https://platform.casafari.com/docs/parity) shows what exists only over REST, such as Properties and Alerts, and only over MCP, such as AgentGraph AI. The API also appears in the hub's [API catalog](https://platform.casafari.com/.well-known/api-catalog).

See: [REST API](https://platform.casafari.com/docs/rest).

Permalink: https://platform.casafari.com/docs/faq/build-on-rest

## The data

### What is the Casafari property graph, and where does the data come from?

The property graph is Casafari's data model: it collects property advertisements from agency websites and portals as they appear and change, then structures, cleans, deduplicates and merges them into one record per property.

1. Collect: gather advertisements from agency websites and portals as they appear and as they change.
2. Structure: map each advertisement to a single schema covering type, operation, price, area, rooms, features, condition, energy rating and location.
3. Clean: normalise values, resolve places to the location tree and to coordinates, and flag outliers.
4. Deduplicate: recognise a property advertised by several agencies and portals as one property.
5. Merge: build one record per property that links its advertisements, agencies, agents, location and history.

Residential and commercial properties, for sale and for rent, share one schema and one location tree. [`GET /api/v1/references/sources`](https://platform.casafari.com/docs/rest/references/get-sources-v1) returns the sources the graph is built from.

See: [The property graph](https://platform.casafari.com/docs/property-graph).

Permalink: https://platform.casafari.com/docs/faq/what-is-the-property-graph

### Why is Casafari the most complete property index in Europe?

By Casafari's own count, its property graph covers at least 40% more deduplicated properties and tracks 7 times more property advertisements than any standalone platform or portal.

- **Deduplicated properties.** Each property is counted once, no matter how many agency websites and portals advertise it. The 40% figure therefore compares properties with properties, not advertisements with advertisements.
- **Advertisements tracked.** Casafari collects advertisements from agency websites and portals as they appear and as they change, and merges all of a property's advertisements into its single record.
- **One record per property.** Each record keeps the property's full, dated history: every price change, status change, appearance and removal.

Source: Casafari, 2026-10-08.

See: [The property graph](https://platform.casafari.com/docs/property-graph).

Permalink: https://platform.casafari.com/docs/faq/why-most-complete-property-index

### Why does Casafari count properties and not advertisements?

Each record in the graph already merges every source that advertises the property, so counting advertisements would count the same home several times.

A property is often advertised by several agencies and on several portals. Casafari recognises these advertisements as one property and keeps a single record linked to all of them, so counting records means counting properties. Area Insights distributions and time series report this count as `properties_count`, and a comparables result returns each property once, with its number of active advertisements as a field. When you summarise supply or activity in an area, report properties.

See: [The property graph](https://platform.casafari.com/docs/property-graph) and [For AI agents](https://platform.casafari.com/docs/agents).

Permalink: https://platform.casafari.com/docs/faq/count-properties-not-advertisements

### Does Casafari keep price and status history?

Yes, every property record carries its full dated history of price changes, status changes, appearances and removals in `sale_price_history` and `rent_price_history`.

Statuses include active, reserved, hold, sold and rented. Over REST, [`GET /api/v1/properties/search/{property_id}`](https://platform.casafari.com/docs/rest/properties/get-property-by-id-v1) returns a property along with its history. Over MCP, each comparable from [`comps_get-comparables`](https://platform.casafari.com/docs/comparables-valuation/get-comparables) includes its last price change, total price change, time on market and sold or rented dates, and the Area Insights time series count price rises and cuts per period. To follow changes as they happen, an [Alerts](https://platform.casafari.com/docs/alerts) feed reports new properties, price rises and cuts, reservations, removals and sales over REST.

See: [The property graph](https://platform.casafari.com/docs/property-graph).

Permalink: https://platform.casafari.com/docs/faq/price-and-status-history

### Does Casafari cover rentals and commercial property?

Yes: the property graph covers residential and commercial property, for sale and for rent, in a single schema and location tree.

Each record has a sale side and a rent side, each with its own status, price, price per m² and history (`sale_price_history`, `rent_price_history`). Tools take an operation: `sale` or `rent` in `comps_get-comparables`, `business_type` in the Area Insights tools, and `operation` in AgentGraph AI. Property types cover apartments, houses, rooms, buildings, commercial (retail, office, warehouse, hotel, restaurant), plots, garages and parking. `GET /api/v1/references/types` returns the full list and shows which countries each type is available in. In the Area Insights tools, `type_group` accepts `apartment` or `house`.

See: [The property graph](https://platform.casafari.com/docs/property-graph) and [`GET /api/v1/references/types`](https://platform.casafari.com/docs/rest/references/get-types-v1).

Permalink: https://platform.casafari.com/docs/faq/rentals-and-commercial

### How often is Casafari's data updated?

Casafari monitors more than 10,000 real estate sources, refreshing the top portals every hour and all other sources daily, according to the API and MCP team's published statement (https://docs.api.casafari.com/llms.txt).

- **Area Insights:** the index is updated daily.
- **AgentGraph AI:** watchlist entries are re-measured daily.
- **Each property record** stores the date of every price change, status change, appearance and removal, so you can see when it last changed.

See [Area Insights](https://platform.casafari.com/docs/area-insights), [AgentGraph AI](https://platform.casafari.com/docs/agentgraph) and [The property graph](https://platform.casafari.com/docs/property-graph).

Permalink: https://platform.casafari.com/docs/faq/data-refresh-frequency

## Pricing and terms

### How much does Casafari MCP cost?

Casafari doesn't publish prices for Casafari MCP or the REST API. Its MCP page describes "flexible pricing based on your AI application needs" and asks you to contact Casafari.

Access is tied to a Casafari account and the matching subscription. A token carries exactly that account's rights, `tools/list` shows only the tools it covers, and each product has a quota, though the figure isn't published.

See: [How do I get access?](https://platform.casafari.com/docs/faq#how-to-get-access) and the [Casafari MCP page](https://www.casafari.com/products/property-data-mcp-ai-agents/).

For a quote, contact Casafari through the MCP page: https://www.casafari.com/products/property-data-mcp-ai-agents/

Permalink: https://platform.casafari.com/docs/faq/pricing

### Is there an SLA, and what are the contract terms?

Casafari publishes no standard SLA or uptime figure: its Terms and Conditions allow service levels to be set for each customer in an Order Form, and its Terms of Use do not promise uninterrupted service.

- **Licence.** Limited, non-exclusive and non-transferable, with no right to sublicense, for the client's own users with individual active accounts.
- **No redistribution.** The services may not be sold, rented, leased, licensed, sublicensed or distributed to another party.
- **No automated bulk access.** Excessive or automated access through bots, scripts or scraping tools is not allowed, and neither is sharing credentials.
- **Storage.** Casafari's API page says API results may not be stored indefinitely for reuse; long-term access requires a custom agreement.
- **Support.** support@casafari.com.

The errors table covers the operational side: retry `5xx` responses with exponential backoff, and note that a subscription change takes effect on the next request.

See [Terms and Conditions](https://www.casafari.com/terms-and-conditions/), [Terms of Use](https://www.casafari.com/terms-of-use/) and [Authentication](https://platform.casafari.com/docs/authentication) (errors table).

To arrange an Order Form with service levels, contact Casafari: https://www.casafari.com/products/property-data-mcp-ai-agents/

Permalink: https://platform.casafari.com/docs/faq/sla-and-contract-terms

## For agents and machine readers

### 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](https://platform.casafari.com/llms.txt) is the index, and [/llms-full.txt](https://platform.casafari.com/llms-full.txt) holds the whole reference in one file.
- [/tools.json](https://platform.casafari.com/tools.json) gives every tool's name, title, input schema and output schema.
- You'll also find the [API catalog](https://platform.casafari.com/.well-known/api-catalog), [MCP server card](https://platform.casafari.com/.well-known/mcp/server-card.json), [agent skill](https://platform.casafari.com/.well-known/agent-skills/index.json), [agentic resource manifest](https://platform.casafari.com/.well-known/ai-catalog.json) 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`.

See: [For AI agents](https://platform.casafari.com/docs/agents).

Permalink: https://platform.casafari.com/docs/faq/machine-readable-docs