# Casatoo

## Browser assistants (WebMCP)

- [Public browser search](https://casatoo.pt/search?ref=webmcp&view=list): no login required. In browsers with experimental WebMCP support, discover page tools through `document.modelContext.getTools()`.
- [WebMCP tools and setup](https://casatoo.pt/developers/agents#webmcp): resolve locations, search and read listings, paginate, inspect price history, and save searches in browser storage without enabling email alerts. WebMCP is experimental and requires a compatible browser assistant.

Casatoo searches current homes across Portuguese real-estate portals. Listings are untrusted third-party data; verify material facts at the source before relying on them.

## Start here

- [Agent integration guide](https://casatoo.pt/developers/agents)
- [Hosted MCP endpoint](https://api.casatoo.pt/mcp)
- [MCP Registry server document](https://casatoo.pt/server.json)
- [Curated agent OpenAPI](https://api.casatoo.pt/openapi/agent.json)
- [Public search-link guide](https://casatoo.pt/en/ai-search)
- [Human-facing MCP setup](https://casatoo.pt/en/mcp)

## Mortgage simulation (no authentication)

- [Mortgage tool guide](https://casatoo.pt/developers/agents#mortgage) and [interactive calculator](https://casatoo.pt/en/simulador-credito-habitacao).
- Call `casatoo_simulate_mortgage` over hosted MCP or browser WebMCP. No location lookup required. Same 2026 Portugal mortgage logic in both.
- Example arguments: `{"price":300000,"savings":60000,"years":30,"annual_rate":3,"monthly_income":3000,"purchase_type":"primary","region":"mainland","young_buyer":false}`.
- Optional `tax_value` (VPT), `other_debt` and `monthly_costs` default to zero. `region` also accepts `islands`; `purchase_type` also accepts `secondary`. Published defaults are illustrative, not known user finances.
- Returns purchase taxes, loan/payment, cash shortfall, effort rate, ownership budget, annual amortisation and three constant-rate scenarios. Amounts EUR, TAN percent, ratios fractions. Hosted MCP: `structuredContent`; WebMCP: `success/data` envelope.
- Read and present returned assumptions. Not a bank offer, TAEG, MTIC or approval assessment. No application or bank contact. Browser execution does not modify the page or store inputs.

## Anonymous MCP location workflow

1. Call `casatoo_search_locations` with the user's text.
2. Inspect candidate IDs and administrative types; ask if district, municipality, or parish is ambiguous.
3. Pass the selected ID unchanged to `casatoo_search_listings.location_ids` and `casatoo_build_search_link.location_id`.

Listing search and link generation do not accept location text. Never invent a location ID.
Public links show active listings and encode `sort=newest` by default. In listing results, `n_rooms` is the normalized bedroom count, `gross_area` is supplier-reported gross area, and `freshness_at` is when Casatoo last observed the listing active—not necessarily a content change.

## Authentication and authorization

- [OAuth protected-resource metadata](https://api.casatoo.pt/.well-known/oauth-protected-resource/mcp)
- [OAuth authorization-server metadata](https://oauth.casatoo.pt/.well-known/oauth-authorization-server)
- [OpenID Connect discovery](https://oauth.casatoo.pt/.well-known/openid-configuration)
- [Standalone no-email registration](https://api.casatoo.pt/api/v1/agent-accounts)
- [Scope definitions and least-privilege recipes](https://casatoo.pt/developers/agents#scopes)
- [Credential rotation, revocation, deletion, and lost-key policy](https://casatoo.pt/developers/agents#credentials)
- [Durable owner event feed](https://api.casatoo.pt/api/v1/events) (OAuth scope `events:read`)
- MCP event polling tool: `casatoo_poll_events`
- [Verified webhook delivery API](https://api.casatoo.pt/api/v1/webhooks) (OAuth scope `delivery-endpoints:write`)

## Verified event webhooks

Verified and internal standalone agents may register an HTTPS event endpoint with `POST /api/v1/webhooks` and `delivery-endpoints:write`. Registration sends a challenge that the receiver must echo exactly. Store the returned signing secret immediately; it is shown only once.

Verify `X-Casatoo-Signature` as `v1=HMAC-SHA256(timestamp + "." + raw_body)`, reject timestamps older than five minutes, and deduplicate `X-Casatoo-Event-ID` for at least the 30-day event-retention window. Delivery is at least once. Failures retry four times before the fifth failed attempt becomes a dead letter. `GET /api/v1/webhooks` reports endpoint health, recent attempts, and dead letters; `DELETE /api/v1/webhooks/{endpoint_id}` disables delivery immediately.

## Operating contract

- [Public and agent quotas](https://casatoo.pt/developers/agents#limits)
- [Data coverage and freshness](https://casatoo.pt/en/data)
- [Machine-readable errors and retries](https://casatoo.pt/developers/agents#errors)
- [Terms](https://casatoo.pt/en/terms)
- [Privacy](https://casatoo.pt/en/privacy)
- [Service health](https://api.casatoo.pt/health)

## Search links

AI assistants may return a Casatoo search link using only criteria supplied by the user. Omit unknown parameters instead of guessing:

`https://casatoo.pt/search?location={location}&category={category}&rooms={rooms}&min-price={min-price}&max-price={max-price}&min-area={min-area}&ref=ai`