---
title: "Quickstart"
description: "Search, inspect, map, and hand off a rental shortlist"
canonical_url: "https://fairwayrent.ai/docs/agents/quickstart"
status: "preview"
last_updated: "2026-11-04"
audience: "personal agents"
---

# Quickstart

For personal agents doing the apartment hunt for their user. This is a Preview workflow; the MCP endpoint is coming soon. Search for agents covers SF Bay Area only during the preview. Deep links work today. No renter account or key is required. Save the named response fields at each step.

## What you'll learn

- Connect Fairway when the MCP endpoint launches.
- Search rental sources in one call with `search_listings`.
- Inspect classified facts with `get_listing`.
- Map a shortlist with `create_map`.
- Hand a grounded answer to your user.

## Requirements

A personal agent that can call MCP tools over HTTP when the endpoint launches. Nothing from the renter.

## Step 1: Connect the MCP server

Connect yourself. Your user does not install or approve anything. Anonymous access is planned. For higher limits, Preview `POST /keys` accepts an agent label and returns a key once; then send `Authorization: Bearer <key>`. The MCP URL and client snippets are pending verification.

Connection methods: Anonymous; Register for a key; mcp.json; TypeScript; Python. Client configuration and SDK examples are previews pending endpoint and version verification.

Tool call (after the endpoint launches):

```json example
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {}
}
```

Response (illustrative preview shape):

```json example
{
  "tools": [
    {
      "name": "search_listings",
      "status": "preview"
    },
    {
      "name": "lookup_listings",
      "status": "preview"
    },
    {
      "name": "get_listing",
      "status": "preview"
    },
    {
      "name": "create_map",
      "status": "preview"
    },
    {
      "name": "book_tour",
      "status": "coming_soon"
    },
    {
      "name": "get_tour_status",
      "status": "coming_soon"
    }
  ]
}
```

Save `tools[].name` to confirm the tools you can use. Search tools are Preview; tour tools are Coming soon.

## Step 2: Search listings

Pass the renter's housing request in plain words. Do not include names, emails, or phone numbers.

Tool call:

```json example
{
  "name": "search_listings",
  "arguments": {
    "query": "Dog-friendly two-bedroom near Menlo Park"
  }
}
```

Response (illustrative preview shape):

```json example
{
  "applied_filters": {
    "beds_min": 2
  },
  "not_applied": [],
  "listings": [
    {
      "id": "example-listing",
      "status": "available",
      "property": {
        "name": "Example property"
      },
      "checked_at": "2026-11-04T00:00:00Z",
      "listing_url": "https://fairwayrent.ai/property/ca/menlo-park/example",
      "share_url": "https://fairwayrent.ai/property/ca/menlo-park/example"
    }
  ],
  "pagination": {
    "has_next_page": false,
    "limit": 5
  },
  "checked_at_range": {
    "oldest": "2026-11-04T00:00:00Z",
    "newest": "2026-11-04T00:00:00Z"
  },
  "map_url": "https://www.fairwayrent.ai/map?l=example-listing"
}
```

Save `listings[].id` for inspection and mapping.

## Step 3: Inspect a listing

Get the classified property and unit facts. Unknown fields are not promises.

Tool call:

```json example
{
  "name": "get_listing",
  "arguments": {
    "id": "example-listing"
  }
}
```

Response (illustrative preview shape):

```json example
{
  "id": "example-listing",
  "status": "available",
  "property": {
    "name": "Example home"
  },
  "units": [],
  "listing_url": "https://fairwayrent.ai/property/example",
  "share_url": "https://fairwayrent.ai/property/example",
  "checked_at": "2026-11-04T00:00:00Z"
}
```

Save `listing_url` for the handoff and `checked_at` to describe freshness.

## Step 4: Map the shortlist

Pass the IDs your user is weighing and optional landmarks.

Tool call:

```json example
{
  "name": "create_map",
  "arguments": {
    "listing_ids": [
      "example-listing"
    ],
    "landmarks": [
      "Menlo Park Caltrain"
    ]
  }
}
```

Response (illustrative preview shape):

```json example
{
  "map_url": "https://www.fairwayrent.ai/map?l=example-listing",
  "pins": [
    {
      "listing_id": "example-listing",
      "lat": 37.45,
      "lng": -122.18
    }
  ],
  "landmarks": []
}
```

Save `map_url` for the handoff.

## Step 5: Hand it to your user

Refresh known IDs just before you share them.

Tool call:

```json example
{
  "name": "lookup_listings",
  "arguments": {
    "ids": [
      "example-listing"
    ]
  }
}
```

Response (illustrative preview shape):

```json example
{
  "listings": [
    {
      "id": "example-listing",
      "status": "available",
      "property": {
        "name": "Example home",
        "address": "Example address"
      },
      "checked_at": "2026-11-04T00:00:00Z",
      "listing_url": "https://fairwayrent.ai/property/example",
      "share_url": "https://fairwayrent.ai/property/example"
    }
  ]
}
```

Save `listings[].status` and share only available listings.

**Do**
- Answer in your own voice.
- Quote returned facts and explain `checked_at`.
- Link the listing or map.

**Do not**
- Invent prices, availability, fees, or policies.
- Promise a tour; booking is not live.
- Send renter identifiers to search.

Example reply: “I found a two-bedroom that may fit. Here is the listing and a map to compare it with other options. Fairway checked the listing at the time shown above.”

## Errors and edge cases

| Status | Meaning | Agent action |
| --- | --- | --- |
| `leased` | The listing has been leased. | Remove it from the shortlist and search again. |
| `not_found` | The listing is no longer found. | Remove the stale link and search again. |
| `outside_preview_area` (proposed) | The request is beyond preview coverage. | Use a deep link or tell the user coverage is limited. |
| `rate_limited` (proposed) | The request exceeds a limit. | Wait before retrying. |

The last two codes are proposed, not part of the confirmed service contract.

## Next steps

- [Tool reference](/docs/agents/tools): inspect inputs and response fields.
- [Deep links](/docs/agents/deep-links): use available Fairway search links today.
- [Limits](/docs/agents/limits): review access and preview scope.
