# Authentication

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

This page is about signing in to the MCP server. The REST API signs in differently, with an email and password and a bearer token: see [REST API](/docs/rest#get-a-token).

The MCP server is an OAuth 2.1 resource server. Access is bound to a Casafari account with an MCP subscription: a token carries exactly that account's rights. Casafari does not use OAuth scopes; rights are per tool and resolved from the account on every call. The canonical, agent-facing version of this page is [casafari.com/auth.md](https://www.casafari.com/auth.md).

## Discovery

A request without a token answers:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://mcp.casafari.com/.well-known/oauth-protected-resource"
```

1. Fetch the protected resource metadata, [https://mcp.casafari.com/.well-known/oauth-protected-resource](https://mcp.casafari.com/.well-known/oauth-protected-resource). Its `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. Fetch the authorization server metadata, [https://api.casafari.com/.well-known/oauth-authorization-server](https://api.casafari.com/.well-known/oauth-authorization-server), for the registration, authorization and token endpoints.

## Sign in on behalf of a person

1. **Register** (once): `POST` to the registration endpoint with your client name and redirect URIs, `grant_types` `["authorization_code", "refresh_token"]` and `token_endpoint_auth_method` `none`. Keep the `client_id`.
2. **Authorize**: send the person to the authorization endpoint with PKCE (`S256`), `state` and `resource`. They sign in with their Casafari account and approve.
3. **Exchange the code** at the token endpoint, again with `resource` and the PKCE verifier.
4. **Call the server** with `Authorization: Bearer <access_token>`.
5. **Refresh** with the refresh token when `expires_in` runs out. A `401` with `error="invalid_token"` on a token that used to work means it expired or was revoked: refresh it, and if that fails, authorize again. Keep the client; do not register again.

## Agents without a person

An agent that runs unattended uses the client credentials grant. Such a client cannot register itself: Casafari issues a `client_id` and `client_secret` for the account, and the account owner hands them to the agent.

## Errors

| Status | Where | Meaning | What to do |
|---|---|---|---|
| `400 invalid_client_metadata` | Registration | Unsupported grant types, redirect URIs or auth method | Fix the request; never ask for `client_credentials` there |
| `401 invalid_client` | Token endpoint | Unknown `client_id` or wrong secret | Check the credential |
| `401 invalid_token` | MCP server | Token missing, expired, revoked or bound to another resource | Refresh; if that fails, authorize again |
| Tool missing, or a call refused | MCP server | The account has no right to that tool | Do not retry; the subscription does not cover it |
| `Request limit reached for this product.` | MCP server | The product's quota is used up | Stop calling that product |
| `5xx` | Anywhere | Transient error | Retry with exponential backoff |

## Questions about this

- [What is the Casafari MCP server URL?](/docs/faq/mcp-server-url)
- [What is the difference between Casafari MCP and the Casafari REST API?](/docs/faq/mcp-vs-rest-api)
- [Which AI assistants and MCP clients work with Casafari MCP?](/docs/faq/supported-clients)
- [Who can use Casafari MCP?](/docs/faq/who-can-use)
- [Do I need an API key for Casafari MCP?](/docs/faq/api-key)