# Use Casafari from AWS

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

Casafari's MCP servers work with AWS's agent tools as they are. **Kiro** and **Amazon Quick** connect to a server's URL and sign you in with OAuth in the browser. **Amazon Bedrock AgentCore Gateway** adds the servers as MCP server targets and sends a platform API key. Each server is one product of the Casafari API and MCP Platform: sign up at https://platform.casafari.com/console/ and start on the Free plan, with no card.

## The servers

| Product | MCP server | What it answers |
|---|---|---|
| Location Lookup | `https://platform.casafari.com/mcp/locations` | Place names to location ids, which the other products take. Free (0 tokens) |
| Comparables | `https://platform.casafari.com/mcp/comparables` | Comparable properties and a price estimate for a subject property |
| Area Insights | `https://platform.casafari.com/mcp/area-insights` | Asking price series, price, bedroom and time-on-market distributions, and heatmaps for an area |
| [Claro AI](/docs/claro) | `https://platform.casafari.com/mcp/claro` | Commercial premises in Spain and commercial plots in Germany, from a brief in plain words |

Every server speaks Streamable HTTP and also has `account_status`. Tools are named `<server>_<tool>`, for example `comparables_get_comparables`. Each call spends tokens from your plan, except Location Lookup's, which are free; the limits per plan are on [Limits and usage windows](/docs/limits).

| You use | Sign-in |
|---|---|
| Kiro, AWS's agentic IDE | OAuth in the browser, no key |
| Amazon Quick | OAuth in the browser, set up once per product |
| Your own agent behind Amazon Bedrock AgentCore Gateway | A platform API key (`cf_sk_...`) kept in AgentCore Identity |

## Kiro

Kiro reads MCP servers from `~/.kiro/settings/mcp.json` (every workspace) or `.kiro/settings/mcp.json` (one workspace). Add the servers you need:

```json
{
  "mcpServers": {
    "casafari-locations": {
      "url": "https://platform.casafari.com/mcp/locations",
      "oauthScopes": ["account:read", "locations:read"]
    },
    "casafari-comparables": {
      "url": "https://platform.casafari.com/mcp/comparables",
      "oauthScopes": ["comparables:read", "account:read", "locations:read"]
    },
    "casafari-area-insights": {
      "url": "https://platform.casafari.com/mcp/area-insights",
      "oauthScopes": ["area-insights:read", "account:read", "locations:read"]
    },
    "casafari-claro": {
      "url": "https://platform.casafari.com/mcp/claro",
      "oauthScopes": ["claro:read", "claro:write", "account:read", "locations:read"]
    }
  }
}
```

When it connects, Kiro registers itself with Casafari's authorization server (dynamic client registration with PKCE) and opens Casafari's sign-in page in your browser: sign in or create your account, then approve. No key goes in the file. Each server is its own connection with its own sign-in.

Keep `oauthScopes` as shown. Without it Kiro asks for `openid`, `email`, `profile` and `offline_access`, and each Casafari server accepts only its own scopes, the ones its protected-resource metadata lists.

For a run where nobody signs in, send a platform API key instead of signing in: give the entry `"headers": { "X-API-Key": "${CASAFARI_API_KEY}" }` and approve the variable in Kiro's settings (**Mcp Approved Env Vars**); Kiro expands only variables you have approved.

## Amazon Quick

Amazon Quick turns each tool of an MCP server into an action its assistant and agents can use. Adding a server takes an Amazon Quick Enterprise subscription; add one integration per Casafari product.

1. In the Amazon Quick console, choose **Connectors**, then the **Create for your team** tab, and choose **Model Context Protocol (MCP)**.
2. On **Create Integration**, enter a **Name** (for example `Casafari Comparables`), a **Description** if you like, and the server's URL as the **MCP server endpoint**, for example `https://platform.casafari.com/mcp/comparables`. Leave **Connection type** and **Auth server connection type** on **Public network**, then choose **Next**.
3. Choose **User authentication**. Quick reads the server's protected-resource metadata from its `401` answer, finds Casafari's authorization server and registers itself there, so there is no client ID or secret to enter.
4. Choose **Create and continue**, sign in to Casafari in the window that opens and approve. Quick lists the server's tools as actions: review them, choose **Next**, and share the integration with your team if you want to.

Quick sends no custom HTTP headers to an MCP server, so an API key does not work there: use the sign-in above. It does not refresh a custom integration's tool list on its own: when Casafari adds a tool, choose **Sync** on the integration's page.

## Amazon Bedrock AgentCore Gateway

AgentCore Gateway puts several MCP servers behind one MCP endpoint for your agents. It signs in to each target with a credential kept in AgentCore Identity and does not register itself with an authorization server, so give it a platform API key: the gateway sends it as `X-API-Key` on every call. Calls through the gateway spend your account's tokens like any other call.

### 1. Keep the key in AgentCore Identity

Create an API key in the console at https://platform.casafari.com/console/ (it starts with `cf_sk_` and is shown once), then, in your gateway's AWS Region:

```bash
export CASAFARI_API_KEY=cf_sk_...   # the key you created; never commit it
aws bedrock-agentcore-control create-api-key-credential-provider \
  --name casafari-platform \
  --api-key "$CASAFARI_API_KEY"
```

Keep the `credentialProviderArn` it returns as `PROVIDER_ARN`. AgentCore Identity stores the key encrypted, in AWS Secrets Manager.

### 2. Create a gateway

Skip this if you have one. A gateway needs a service role that AgentCore can assume (trusted by `bedrock-agentcore.amazonaws.com`) with `bedrock-agentcore:GetWorkloadAccessToken`, `bedrock-agentcore:GetResourceApiKey` on the key's credential provider and `secretsmanager:GetSecretValue` on its secret. The AgentCore console and CLI can create the role for you.

```bash
aws bedrock-agentcore-control create-gateway \
  --name casafari \
  --role-arn "$GATEWAY_ROLE_ARN" \
  --protocol-type MCP \
  --authorizer-type AWS_IAM
```

With `AWS_IAM`, your agents call the gateway with their own IAM credentials and need `bedrock-agentcore:InvokeGateway` on it; `CUSTOM_JWT` takes tokens from your own identity provider instead. Keep the `gatewayId` (as `GATEWAY_ID`) and the `gatewayUrl`.

### 3. Add each server as a target

```bash
aws bedrock-agentcore-control create-gateway-target \
  --gateway-identifier "$GATEWAY_ID" \
  --name comparables \
  --target-configuration '{"mcp":{"mcpServer":{"endpoint":"https://platform.casafari.com/mcp/comparables"}}}' \
  --credential-provider-configurations '[{"credentialProviderType":"API_KEY","credentialProvider":{"apiKeyCredentialProvider":{"providerArn":"'"$PROVIDER_ARN"'","credentialLocation":"HEADER","credentialParameterName":"X-API-Key"}}}]'
```

Run it again for each other server, with its name and URL: `--name locations` with `https://platform.casafari.com/mcp/locations`, `--name area-insights` with `https://platform.casafari.com/mcp/area-insights` and `--name claro` with `https://platform.casafari.com/mcp/claro`. On creation the gateway calls the server's `tools/list` and indexes its tools; when Casafari adds a tool, call `SynchronizeGatewayTargets` for that target.

The gateway names each tool `<target>___<tool>`, for example `comparables___comparables_get_comparables`. Keep target names as short as these: an Amazon Bedrock model takes tool names of at most 64 characters, and `area-insights___area-insights_get_time_on_market_distribution` already has 61.

### 4. Ask from an agent

In Python, Strands Agents connects to the gateway through the `mcp-proxy-for-aws` client, which signs each request with your IAM credentials (SigV4):

```python
from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client
from strands import Agent
from strands.tools.mcp import MCPClient

gateway = MCPClient(lambda: aws_iam_streamablehttp_client(
    endpoint=GATEWAY_URL, aws_region=REGION, aws_service="bedrock-agentcore"))

with gateway:
    agent = Agent(tools=gateway.list_tools_sync())
    agent("What is a 2-bedroom flat of 85 m² near Avenida da Liberdade, Lisbon worth? Use comparables within 1 km.")
```

The complete sample creates the credential provider, the gateway's role, the gateway and the targets for Location Lookup, Comparables and Area Insights, then asks that question: [examples/aws-agentcore in casafari/casafari-mcp](https://github.com/casafari/casafari-mcp/tree/main/examples/aws-agentcore).

### Keys and access

- Give each gateway its own API key, so you can revoke one in the console without stopping the others; revoking a key stops its gateway's calls.
- A new key carries the scopes of every product your account has, and never gains one later: create the key after your plan covers the products you add. Claro AI is one of them: add `https://platform.casafari.com/mcp/claro` as a target the same way.
- An agent can call `account_status` through the gateway to see the plan and the tokens left.

## See also

- [Connect an MCP client](/docs/connect): every other client, one section each
- [MCP authorization](/docs/authentication): the OAuth flow Kiro and Amazon Quick run
- [Use Casafari from the OpenAI API and the Claude API](/docs/openai-and-claude-api): the same servers from a model provider's API