# Use Casafari from the OpenAI API and the Claude API

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

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](/docs/connect); for fixed requests from your own code without a model, use the [REST API](/docs/rest).

## Before you start: an access token

The MCP server needs an OAuth access token for `https://mcp.casafari.com/` ([MCP authorization](/docs/authentication)).

- **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:

```bash
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](/docs/authentication)).

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.

```javascript
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);
```

```python
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_tools` limits 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](/docs/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.

```typescript
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);
}
```

```python
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](/docs/tools) 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](/docs/rest), `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](/docs/parity) shows which data each offers.