Use Casafari from the OpenAI API and the Claude API
An AI API integration with Casafari takes one request. Both the OpenAI API and the Claude API can call a remote MCP server for you: you pass Casafari's server URL and an access token, and the model provider connects to https://mcp.casafari.com/, lists the tools, calls the ones the question needs and returns the answer. You write no tool-calling code.
This is the way to give your own app or agent Casafari data through the model you already use. For assistants such as Claude or ChatGPT used directly, see Connect an MCP client; for fixed requests from your own code without a model, use the REST API.
Before you start: an access token
The MCP server needs an OAuth access token for https://mcp.casafari.com/ (MCP authorization).
- A server-side agent or job (no person signing in): use the client credentials Casafari issues for your account, and ask the token endpoint for a token bound to the MCP server:
curl -s -X POST https://api.casafari.com/oauth/token \
-u "$CASAFARI_CLIENT_ID:$CASAFARI_CLIENT_SECRET" \
-d grant_type=client_credentials \
--data-urlencode resource=https://mcp.casafari.com/ The answer carries access_token and expires_in. Ask for a new one when it expires.
- On behalf of a person: run the authorization code flow with PKCE in your app and pass that person's token, so the model acts with their rights (MCP authorization).
Pass the token in the API's own field, shown below. Never put it in a prompt. The examples read it from CASAFARI_ACCESS_TOKEN.
OpenAI API (Responses API)
Add Casafari as a tool of type mcp. The authorization field carries the access token; OpenAI does not store it, so send it with every request.
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.create({
model: "gpt-6-astra", // any OpenAI model with MCP tool support
tools: [
{
type: "mcp",
server_label: "casafari",
server_description: "Casafari real estate data: comparables, valuations, area insights.",
server_url: "https://mcp.casafari.com/",
authorization: process.env.CASAFARI_ACCESS_TOKEN,
allowed_tools: ["comps_get-comparables"],
require_approval: "never",
},
],
input: "What is a 3-bedroom flat near Avenida da Liberdade, Lisbon worth? Use comparables within 1 km.",
});
console.log(response.output_text);import os
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-6-astra", # any OpenAI model with MCP tool support
tools=[
{
"type": "mcp",
"server_label": "casafari",
"server_description": "Casafari real estate data: comparables, valuations, area insights.",
"server_url": "https://mcp.casafari.com/",
"authorization": os.environ["CASAFARI_ACCESS_TOKEN"],
"allowed_tools": ["comps_get-comparables"],
"require_approval": "never",
},
],
input="What is a 3-bedroom flat near Avenida da Liberdade, Lisbon worth? Use comparables within 1 km.",
)
print(response.output_text)allowed_toolslimits the tools the model sees; leave it out to offer every tool your account may use.require_approval: "never"suits read-only tools. Keep approval on for tools that change saved state (see MCP security).
Claude API (Messages API)
Use the MCP connector: declare the server in mcp_servers and reference it from an mcp_toolset entry in tools, with the mcp-client-2025-11-20 beta. authorization_token carries the access token.
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const response = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 16000,
betas: ["mcp-client-2025-11-20"],
mcp_servers: [
{
type: "url",
url: "https://mcp.casafari.com/",
name: "casafari",
authorization_token: process.env.CASAFARI_ACCESS_TOKEN,
},
],
tools: [{ type: "mcp_toolset", mcp_server_name: "casafari" }],
messages: [{ role: "user", content: "What is a 3-bedroom flat near Avenida da Liberdade, Lisbon worth? Use comparables within 1 km." }],
});
for (const block of response.content) {
if (block.type === "text") console.log(block.text);
}import os
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=16000,
betas=["mcp-client-2025-11-20"],
mcp_servers=[
{
"type": "url",
"url": "https://mcp.casafari.com/",
"name": "casafari",
"authorization_token": os.environ["CASAFARI_ACCESS_TOKEN"],
}
],
tools=[{"type": "mcp_toolset", "mcp_server_name": "casafari"}],
messages=[{"role": "user", "content": "What is a 3-bedroom flat near Avenida da Liberdade, Lisbon worth? Use comparables within 1 km."}],
)
for block in response.content:
if block.type == "text":
print(block.text)To offer only some tools, turn the rest off in the toolset: {"type": "mcp_toolset", "mcp_server_name": "casafari", "default_config": {"enabled": false}, "configs": {"comps_get-comparables": {"enabled": true}}}.
Agent frameworks
Most agent frameworks include an MCP client. Point it at https://mcp.casafari.com/ (Streamable HTTP) and give it the access token, or let it run the OAuth flow; the tool reference lists every tool and its inputs.
An API for AI agents, two ways
- Through a model (this page): the model decides which Casafari tools to call. Best when the questions vary.
- Directly (REST API,
https://api.casafari.com): your code makes fixed requests. Best for the same job every time, bulk work, or apps without a model. MCP vs REST API shows which data each offers.