API di Casafari e piattaforma MCP
Casafari è la piattaforma di intelligence dei dati immobiliari nativa per agenti AI. L'indice immobiliare più completo d'Europa: un grafo immobiliare deduplicato e ripulito di immobili residenziali e commerciali, in vendita e in affitto, in 16 paesi.
Ogni immobile nel grafo immobiliare è un unico record, aggregato da ogni fonte che lo pubblicizza, ripulito e con la sua cronologia completa: ogni variazione di prezzo, ogni cambio di stato, la data di ingresso sul mercato e quella di rimozione. Sia immobili residenziali che commerciali, in vendita e in affitto. Come viene costruito il grafo immobiliare.
I server MCP di Casafari connettono assistenti e agenti IA ad essi tramite gli strumenti del Model Context Protocol: ricerca di località, comparables e valutazioni, area insights, analisi di agenzie e agenti. Sono parte della Casafari API and MCP Platform: un server MCP per ogni prodotto, https://platform.casafari.com/mcp, una connessione e un unico accesso OAuth (ogni prodotto è anche un server a sé).
Gli stessi dati sono disponibili anche tramite la REST API della piattaforma (https://platform.casafari.com/v1/<product>, 37 operazioni, stessi token e API key della piattaforma usati per i server MCP; i clienti Casafari con contratto mantengono anche i vecchi percorsi su https://api.casafari.com, nella pagina Legacy API). La documentazione è organizzata per prodotto e ogni prodotto elenca i propri strumenti MCP e le proprie operazioni REST; Confronto tra MCP e REST mostra dove i due sistemi si sovrappongono e dove differiscono.
Sei già cliente Casafari API? Il tuo token continua a funzionare e il riferimento dell'API esistente è ora disponibile su questo sito. Accedi al tuo account API per visualizzare il tuo token.
Endpoint
Un server MCP per ogni prodotto (Streamable HTTP, accesso OAuth 2.1 nel browser, nessuna chiave da copiare):
https://platform.casafari.com/mcpIn Claude o ChatGPT, aggiungi un connettore personalizzato chiamato Casafari con quell'URL; in Claude Code: claude mcp add --transport http casafari https://platform.casafari.com/mcp. Oppure un prodotto alla volta, ognuno sul proprio server. Passaggi per Claude, ChatGPT, Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI, Zed e altri client: Connessione e Connessione alla Casafari Platform.
Sei già cliente Casafari? Utilizza lo stesso server: registrati su https://platform.casafari.com/console/; se hai un contratto, Casafari configurerà il tuo account sul piano Custom. mcp.casafari.com è il gateway legacy, ancora attivo, in fase di migrazione su https://platform.casafari.com/mcp/<product>.
Ogni server pubblica la propria card su <server URL>/.well-known/mcp/server-card.json, quella del server unico è disponibile su https://platform.casafari.com/mcp/.well-known/mcp/server-card.json. Accesso: Autenticazione.
Anche Claro AI è un prodotto della piattaforma; con una API key della piattaforma anziché OAuth, consulta Connettere Claro AI.
Prodotti
| Prodotto | Strumenti MCP | Operazioni REST | Cosa fornisce |
|---|---|---|---|
| Property Sourcing | 5 | 5 | Trova immobili nel grafo immobiliare, dove ogni immobile è un unico record a prescindere da quante agenzie e portali lo pubblicizzino: effettua ricerche tramite filtri strutturati o linguaggio naturale, naviga tra i risultati, leggi ogni immobile con tutti i portali su cui è pubblicato e la sua cronologia dei prezzi, e risolvi un link di un portale o di un'agenzia o un riferimento nell'immobile di appartenenza. REST e MCP. |
| High Potential Seller Leads | — | 2 | Immobili con alta probabilità di vendita: proprietà attorno a un punto il cui prezzo di richiesta è stato ridotto ripetutamente, indicando il numero di ribassi e il totale, durante l'intero periodo sul mercato o a partire da una certa data. Ogni lead rimanda alla proprietà e alla sua cronologia dei prezzi. Solo REST; Spagna, Francia, Italia, Germania, Grecia e Andorra. |
| Private Seller Leads | 3 | 3 | Case offerte direttamente dai proprietari, tratte dagli annunci appena pubblicati: gli ultimi arrivati in una località a partire da una certa data (al massimo 90 giorni fa), ordinati dal più recente, completi di link al portale, prezzo, metratura, coordinate approssimative, nome e telefono del venditore. |
| Comparables & Valuation | 1 | 1 | Proprietà comparabili e prezzi stimati per un immobile: immobili sul mercato o ritirati in seguito a vendita o locazione, con i soli prezzi di richiesta, abbinati attorno a un punto, un indirizzo o un riferimento catastale. |
| Comparables with Transactions | 1 | 1 | Tutto ciò che offre Comparables, più i prezzi di chiusura registrati: rogiti notarili in Spagna, compravendite registrate dall'Agenzia delle Entrate in Italia, il registro ufficiale RCN in Polonia (transactional_data) e il registro pubblico DVF in Francia (dvf_results). Gli stessi input di Comparables. |
| Area Insights | 10 | 10 | Analisi di un'area: prezzo, offerta e attività nel tempo, distribuzioni per prezzo, numero di camere e tempo sul mercato, oltre all'analisi di mercato. Tramite MCP sono disponibili anche misure di crescita, volatilità e mappe di calore per distretto. |
| New Market Leads | — | — | Feed di avvisi basati sul grafo immobiliare per una serie di filtri: nuovi immobili, aumenti e tagli di prezzo, prenotazioni, ritiri dal mercato e vendite. È possibile creare un feed, leggere gli avvisi o riceverli tramite webhook. In fase di manutenzione. |
| References | — | — | I dati di riferimento su cui si basano le richieste: tipologie di proprietà, caratteristiche e condizioni, agenzie, agenti e fonti che compongono il grafo, località con ricerca predittiva e confini dei codici postali. |
| Cadastre | 5 | — | Registri catastali spagnoli e valori di riferimento delle zone: ricerca di un immobile tramite riferimento catastale, indirizzo o coordinate, lettura della scheda catastale e del valore di riferimento di una zona o di ogni zona in un comune. Spagna, esclusi Navarra e Paesi Baschi. |
| Parcel Zoning | 2 | 6 | Zonizzazione e superficie edificabile di una particella catastale, tramite riferimento catastale o coordinate. Disponibile per Spagna (Bizkaia, Catalogna e particelle con locali commerciali censiti nella regione di Madrid e nella Comunità Valenciana) e Germania (Amburgo, Renania Settentrionale-Vestfalia). |
Claro AI
Claro AI è l'agente di ricerca di Casafari per l'espansione commerciale di locali in Spagna e Germania. È un prodotto della piattaforma: dispone di un proprio MCP server e REST API sulla piattaforma, accessibili tramite chiave della piattaforma o OAuth della piattaforma. Connetti Claro.
Come sono denominati i tool
Ogni server denomina i propri tool come <server>_<tool>: il prefisso è l'ultimo segmento dell'URL del server, mentre il resto è il nome del tool, ad esempio comparables_get_comparables, area-insights_get_heatmap o property-sourcing_search. I tool di Location Lookup sono locations_search e locations_get, e ogni server dispone anche di account_status. Chiamare sempre un tool con il suo nome completo, così come elencato dal server.
Un'API per agenti AI
Casafari è un'API per agenti AI disponibile in due forme, basate sullo stesso grafo immobiliare:
- L'MCP server (
https://platform.casafari.com/mcp, per tutti i prodotti; oppure uno per prodotto sottohttps://platform.casafari.com/mcp/), per agenti che individuano i tool e decidono quali richiamare: in Claude, ChatGPT e altri MCP client, o dal proprio codice tramite OpenAI API o Claude API. - La REST API (riferimento), per agenti e applicazioni il cui codice effettua richieste fisse.
Anche questa documentazione è pensata per gli agenti: ogni pagina è in formato Markdown e /llms.txt le indicizza tutte.
Token, pagamento e verifica
Ogni chiamata ha un costo fisso in token sul Suo account di piattaforma. Alcuni strumenti costano meno via MCP rispetto alla stessa chiamata via REST: costo di una chiamata. account_status, presente su ogni server, mostra il piano e il saldo. Quando i token si esauriscono, lo strumento risponde con un errore di pagamento che contiene un link per la ricarica; non è necessario alcun abbonamento (il titolare dell'account o un responsabile della fatturazione può procedere al pagamento). Limiti per piano: Limiti.
Iniziare da una località
La maggior parte dei tool di dati richiede una località espressa come ID, cerchio o poligono piuttosto che come nome: occorre prima risolvere il nome del luogo in ID utilizzando locations_search di Location Lookup (https://platform.casafari.com/mcp/locations, gratuito).
Leggere questa documentazione in formato Markdown
Ogni pagina dispone di una versione Markdown: basta aggiungere .md all'URL o inviare Accept: text/markdown. /llms.txt elenca ogni pagina e tool; /llms-full.txt contiene l'intero riferimento in un unico file. Maggiori informazioni su Per agenti AI.
Domande e risposte
Quale indirizzo utilizzare: api.casafari.com o platform.casafari.com (mcp.casafari.com è il gateway legacy)?
I nuovi utenti e chi utilizza MCP iniziano da platform.casafari.com, la piattaforma self-service di Casafari; i clienti Casafari esistenti continuano a utilizzare api.casafari.com per REST, mentre mcp.casafari.com è il gateway legacy, che rimane attivo pur essendo in fase di migrazione verso la piattaforma.
Se è la prima volta su Casafari: utilizzi https://platform.casafari.com.
- Gli assistenti si connettono tramite MCP all'indirizzo https://platform.casafari.com/mcp, un unico punto di accesso per ogni prodotto; ogni prodotto è inoltre un server dedicato all'indirizzo
https://platform.casafari.com/mcp/<product>, ad esempio https://platform.casafari.com/mcp/comparables. - Il codice chiama la REST API su
https://platform.casafari.com/v1/<product>per account, locations, area-insights, property-sourcing, seller-leads, private-sellers, comparables, comparables-transactions, parcel-zoning e claro. High Potential Seller Leads è disponibile solo tramite REST; ogni altro prodotto dispone di un server MCP.
Si registri autonomamente, provi senza carta di credito e paghi in base al consumo: come registrarsi.
Se sei un cliente Casafari: la tua integrazione REST esistente mantiene https://api.casafari.com, la Legacy API, con il tuo login e il tuo contratto attuali. Non cambia nulla: non è prevista alcuna migrazione né collegamento di account. I nuovi sviluppi, incluso Property Sourcing, possono utilizzare i percorsi della piattaforma. Per MCP, utilizza la piattaforma self-service come tutti gli altri: registrati su https://platform.casafari.com/console/ e, se hai un contratto, Casafari configurerà il tuo account sul piano Custom. Dettagli: Clienti API esistenti e cosa cambia per te.
URL completi: URL del server MCP e URL di base REST.
Permalink: /docs/faq/which-address-do-i-use
Come ottenere una API key ed effettuare la prima chiamata?
Crei un account su https://platform.casafari.com (il piano Free non richiede carta di credito), generi una API key nella console e la utilizzi per la prima chiamata.
- Generi una chiave (
cf_sk_…) nella console; viene mostrata una sola volta, quindi la conservi subito e non la inserisca mai in un URL. - Esegua la chiamata
GET https://platform.casafari.com/v1/locations/search?query=Lisbonincludendo la chiave nell'headerX-API-Key, oppure comeAuthorization: Bearer <api_key>. Le ricerche di località costano 0 token, quindi questa prima chiamata è gratuita.
Gli assistenti non necessitano di una chiave: aggiungi il server MCP di un prodotto e accedi tramite OAuth (connessione di un client). Un account Free ha 1 membro e 2 API key; Agent ha 1 membro e 3 chiavi; Agency ha 5 membri e 10 chiavi (prezzi). Ciò che include la prova è descritto nella prova gratuita; il riferimento REST si trova in REST API e API key della piattaforma.
I clienti Casafari esistenti mantengono le proprie credenziali di accesso sulla API REST di Casafari (Clienti API esistenti).
Permalink: /docs/faq/how-to-sign-up
Che cosa sono i token sulla piattaforma Casafari?
Il token è l'unità di misura utilizzata dalla piattaforma Casafari per conteggiare l'utilizzo: ogni chiamata ha un costo fisso in token; alcune operazioni sono più economiche se effettuate tramite un assistente AI, via MCP, rispetto alle chiamate REST API.
- Le ricerche di posizioni (Location Lookup) e la verifica dello stato dell'account sono gratuite.
- I costi delle operazioni REST sono indicati nella pagina dedicata alla documentazione REST. Gli header di risposta
Casafari-Units-ChargedeCasafari-Units-Remainingspecificano il costo della singola chiamata e il saldo residuo. - Il confronto tra i costi delle chiamate API e quelle via assistenti AI, il dettaglio dei piani e il valore dei token sono disponibili alla pagina Prezzi.
- Il numero di token inclusi nel piano ogni 3 ore o 7 giorni, e le procedure in caso di esaurimento, sono descritti in Limiti e finestre di utilizzo.
Per verificare il proprio stato, chieda all'assistente di richiamare account_status oppure effettui una richiesta GET /v1/account.
Permalink: /docs/faq/what-are-tokens
Il mio agente AI segnala che è richiesto un pagamento o che ho terminato i token. Cosa devo fare?
Sulla piattaforma self-service, un errore di pagamento genera un link di pagamento: l'utente può aprirlo per completare il pagamento, oppure attendere il rinnovo della finestra di utilizzo prima di riprovare.
- Token esauriti: il REST risponde con
402 payment_requiredinsieme a unupgrade_urle un headerLinkconrel="payment"; un MCP server della piattaforma risponde a un errore di pagamento con lo stesso link (pagina di errore). - Finestra di utilizzo di 3 ore esaurita e assenza di crediti residui: REST restituisce
429 usage_limit_reachedindicando il tempo di ripristino, un headerRetry-Aftere unupgrade_urlper l'acquisto di crediti; MCP risponde a un errore di pagamento con le medesime indicazioni. - Limite di spesa raggiunto:
402 payment_requiredcon la motivazionespending_cap_reached, fino al termine del periodo o all'aumento del limite.
Una volta effettuato il pagamento, l'agente interroga GET /v1/account/payment-links/{id} circa ogni 5 secondi finché lo stato non risulta completato, per poi riprovare.
L'agente non può pagare autonomamente (un agente può pagare?); i crediti vengono ricaricati automaticamente solo se è stata attivata la ricarica automatica. Non è indicato se un assistente debba riconnettersi dopo il pagamento. Consultare gestione di un 402 e crediti.
Una quota in un contratto REST API di Casafari è diversa: consultare quota rispetto ai token.
Permalink: /docs/faq/agent-ran-out-of-tokens
È possibile leggere questa documentazione in formato Markdown? Esiste un file llms.txt?
Sì: aggiunga .md all'URL di qualsiasi pagina o invii Accept: text/markdown, mentre /llms.txt indicizza ogni pagina e strumento. Non è richiesta alcuna chiave.
- /llms.txt è l'indice, mentre /llms-full.txt contiene l'intera documentazione in un unico file.
- /tools.json fornisce nome, titolo, schema di input e schema di output di ogni strumento.
- Troverà inoltre il catalogo API, la scheda del server MCP, le competenze dell'agente, il manifesto delle risorse agentiche e la sitemap all'indirizzo
/sitemap.xml. - Le risposte in formato Markdown sono fornite come
text/markdown, con un'intestazionex-markdown-tokensche ne stima la dimensione. - In un browser che supporta
navigator.modelContext, le pagine registrano questi strumenti WebMCP:search_casafari_mcp_docs,get_casafari_tool_reference,get_casafari_rest_operation,get_casafari_connection_configeopen_casafari_docs_page. - La piattaforma self-service pubblica i propri https://platform.casafari.com/llms.txt e https://platform.casafari.com/llms-full.txt, oltre a una OpenAPI per ogni prodotto.
Vedere: Per agenti AI.
Permalink: /docs/faq/machine-readable-docs