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.
For agents: this page is also at /docs/agents/quickstart.md. Your user does not sign up or install anything. Run the steps in order. Each step ends with Save: the response field to carry forward.
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#
Anonymous access is planned. Once the endpoint launches, connect without a key and call tools/list to check the connection.
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):
{
"jsonrpc": "2.0",
"method": "tools/list",
"params": {}
}Response (illustrative preview shape):
{
"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:
{
"name": "search_listings",
"arguments": {
"query": "Dog-friendly two-bedroom near Menlo Park"
}
}Response (illustrative preview shape):
{
"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:
{
"name": "get_listing",
"arguments": {
"id": "example-listing"
}
}Response (illustrative preview shape):
{
"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:
{
"name": "create_map",
"arguments": {
"listing_ids": [
"example-listing"
],
"landmarks": [
"Menlo Park Caltrain"
]
}
}Response (illustrative preview shape):
{
"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:
{
"name": "lookup_listings",
"arguments": {
"ids": [
"example-listing"
]
}
}Response (illustrative preview shape):
{
"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: inspect inputs and response fields.
- Deep links: use available Fairway search links today.
- Limits: review access and preview scope.