# Errors & Troubleshooting
Source: https://docs.brightplace.ai/errors-troubleshooting

The brightplace Connect error envelope, error-code set, and common fixes.

## Error envelope

Tool errors use a stable envelope:

```json theme={null}
{
  "ok": false,
  "error": {
    "error_code": "VALIDATION_ERROR",
    "message": "Tool input failed validation.",
    "details": {}
  },
  "latency_ms": 2
}
```

Clients should handle these error codes and tolerate new codes being added over
time.

| Code | Meaning |
| - | - |
| `LISTING_NOT_FOUND` | The requested `listing_id` is unknown. |
| `SLOT_NOT_AVAILABLE` | The requested tour slot is no longer bookable. |
| `BOOKING_LIMIT_REACHED` | The renter already has 2 active tour requests from the last 24 hours. |
| `FAIR_HOUSING_VIOLATION` | The request was blocked by Fair Housing guardrails. |
| `UNAUTHORIZED` | The operation requires an authenticated account. Reconnect before retrying. |
| `TOKEN_EXPIRED` | The bearer token is expired. Refresh or reconnect before retrying the tool request. |
| `VALIDATION_ERROR` | Input failed schema validation. |
| `TOOL_NOT_FOUND` | The requested tool name is not registered on the server. |
| `RATE_LIMITED` | A per-session, aggregate, per-tool, or booking limit was exceeded. |
| `DOWNSTREAM_ERROR` | A connected service failed. |

## HTTP authentication challenge

Authentication can fail before a tool runs. Missing or invalid authentication
returns HTTP `401`, a `WWW-Authenticate` header with `resource_metadata`, and:

```json theme={null}
{"error": "invalid_token", "error_description": "Authentication required"}
```

This is separate from the tool envelope above. It also covers expired tokens;
clients should not depend on a distinct `TOKEN_EXPIRED` response. Refresh if
supported, or reconnect the account and retry. `initialize` and `tools/list`
remain available before sign-in.

## Rate-limited details

`RATE_LIMITED` responses include retry information when available:

```json theme={null}
{
  "error_code": "RATE_LIMITED",
  "message": "Rate limit exceeded.",
  "details": {
    "retry_after_seconds": 60
  }
}
```

Do not retry immediately. Wait at least `retry_after_seconds`, then retry only
if the user's request is still relevant.

## Troubleshooting

| Symptom | What to check |
| - | - |
| Connector cannot be added | Confirm the URL is exactly `https://mcp.brightplace.ai/mcp` and uses HTTPS. See the client-specific [Install](/install/claude) guide. |
| Claude detects “No sign-in” when adding brightplace | Select **Sign in now** and **Use Claude’s published identity**; leave **Request headers** empty. Public tool discovery does not grant tool access. |
| An organization member can see brightplace but cannot use its tools | In the standard OAuth setup, each member must **Connect** and sign in to their own brightplace account. Adding the connector does not share the owner's login. |
| Client says the server is unreachable | Confirm the endpoint resolves over HTTPS from the public internet. |
| Search returns `FAIR_HOUSING_VIOLATION` | Rephrase using objective criteria such as price, size, location, amenities, and availability. Avoid protected-class or demographic terms. |
| Tool calls return HTTP `401`, `Authentication required`, `UNAUTHORIZED`, or `TOKEN_EXPIRED` | Reconnect the account or refresh the bearer token, then retry. |
| Tool calls return `RATE_LIMITED` | Back off for at least `retry_after_seconds` before retrying. |
| `book_tour` returns `BOOKING_LIMIT_REACHED` | The renter already has 2 active tour requests in the last 24 hours; wait before submitting another. |
| `book_tour` returns `SLOT_NOT_AVAILABLE` | Re-fetch open slots with `get_tour_availability` and book a current one. |
| A tool returns `DOWNSTREAM_ERROR` | A connected service failed transiently. Retry later; if it persists, the data may be temporarily unavailable. |


# Overview
Source: https://docs.brightplace.ai/index

Connect AI assistants to brightplace apartment search tools.

brightplace Connect is brightplace's public Model Context Protocol server for AI
rental assistants.

It gives supported AI clients access to brightplace apartment search, listing
detail, neighborhood and financial guidance, tour availability, and tour
request tools through one remote MCP endpoint:

```text theme={null}
https://mcp.brightplace.ai/mcp
```

## What you can do

| Capability | Tool |
| - | - |
| Search apartment listings with objective filters | `search_listings` |
| Get full detail for one listing | `get_listing` |
| Get curated neighborhood context for a listing's area | `get_neighborhood_guide` |
| Answer affordability and cost-of-living questions | `get_financial_guide` |
| Check available tour slots | `get_tour_availability` |
| Submit a tour request | `book_tour` |

Listing detail includes brightplace's letter grades for quality, walkability,
transit, biking, and nearby schools. See
[get\_listing](/reference/tools/get-listing#brightplace-grades) for what each
grade means and how it is calculated.

brightplace Connect is built for renter-facing apartment search. It is not a
general operator API, property-management API, or bulk data export.

To connect a client, see [Install](/install/claude). For the response envelope
and how to drive a search, see [Usage](/usage). For the error set and common
fixes, see [Errors & Troubleshooting](/errors-troubleshooting).

## Supported clients

| Client | Status |
| - | - |
| Claude | Supported for remote MCP connectors. See [Install in Claude](/install/claude). |
| ChatGPT | Supported where custom MCP apps or connectors are available. See [Install in ChatGPT](/install/chatgpt). |
| Perplexity | Supported for custom remote MCP connectors on Pro, Max, and Enterprise plans. See [Install in Perplexity](/install/perplexity). |

Any MCP client that can add a remote server over HTTPS can use brightplace
Connect. The guides above cover the clients we test against; for anything else,
see [Other Clients](/install/other-clients).

## Important links

| Resource | URL |
| - | - |
| MCP endpoint | `https://mcp.brightplace.ai/mcp` |
| Fair Housing commitment | `https://www.brightplace.ai/fair-housing` |
| [brightplace AI instructions](https://www.brightplace.ai/ai-info) | `https://www.brightplace.ai/ai-info` |
| Privacy Policy | `https://www.brightplace.ai/privacy` |
| Terms of Service | `https://www.brightplace.ai/terms` |


# Install in ChatGPT
Source: https://docs.brightplace.ai/install/chatgpt

Add brightplace Connect as a custom MCP app or connector in ChatGPT.

ChatGPT supports custom MCP apps or connectors where developer mode and custom
MCP access are available for your plan or workspace.

## Add the app

1. Go to [chatgpt.com/#settings/Connectors](https://chatgpt.com/#settings/Connectors).
2. Click **Advanced settings** and enable **Developer mode**.
3. Click **Create app**.
4. Set the name to `brightplace` and the connection to:

```text theme={null}
https://mcp.brightplace.ai/mcp
```

5. Click **Advanced OAuth settings**.
6. Set the registration method to **Dynamic Client Registration (DCR)**.
7. In the **Base scopes** box, add `offline_access`.
8. Uncheck **OIDC enabled**.
9. Check **I understand and want to continue**.
10. Click **Create** and follow the sign-in flow.

For Business, Enterprise, or Edu workspaces, admins or owners may need to create
and publish the app before members can use it.


# Install in Claude
Source: https://docs.brightplace.ai/install/claude

Add brightplace Connect as a Claude custom connector.

Claude supports remote MCP custom connectors from Claude's cloud
infrastructure. Your brightplace Connect endpoint must be reachable over the
public internet.

## Before connecting

You need a brightplace account and permission to add a custom connector in your
Claude workspace. Tool discovery works before sign-in, but all tool calls require
an authenticated renter identity. Claude connects from its cloud infrastructure.

## Add the connector

1. Go to [claude.ai/customize/connectors](https://claude.ai/customize/connectors).
2. Click the **+** and then **Add custom connector**.
3. Set the name to `brightplace` and the MCP server URL to:

```text theme={null}
https://mcp.brightplace.ai/mcp
```

4. Under **Authentication**, select **Sign in now**.
5. Under **OAuth client**, select **Use Claude’s published identity**. brightplace
   supports this option through Client ID Metadata Documents (CIMD); no client ID
   or client secret is needed.
6. Leave **Request headers** empty. No custom headers or API key are required.
7. Click **Add**, then **Connect** if prompted. Sign in to your brightplace account
   and approve the consent flow.
8. Enable the connector and ask: “Find two-bedroom apartments in Orlando under
   \$2,200.”

## Which authentication option should I choose?

Choose **Sign in now** because every brightplace tool requires an authenticated
account, including apartment search. It completes sign-in during setup.

**Sign in when needed** delays the same required login until the first tool call.
It does not provide anonymous access to brightplace tools.

Claude may detect **No sign-in** because the server allows initialization and tool
discovery before authentication. Change this selection to **Sign in now**;
discovering the tools does not grant permission to call them.

Keep **Use Claude’s published identity** selected for the standard setup.
**Register automatically** uses Dynamic Client Registration (DCR), which brightplace
also advertises, but is not needed for the recommended flow. **Use your own OAuth
client** is for a separately configured client; do not enter manual credentials
for the standard setup.

## Use brightplace in a Team or Enterprise workspace

An Owner or Primary Owner first adds the custom connector in the organization's
connector settings using the same URL and authentication choices above. Members
then open their own connector settings, select brightplace, and click **Connect**
to sign in to their own brightplace accounts.

For this standard OAuth setup, adding the connector makes it available to the
organization; it does not share the owner's brightplace login. **Sign in now**
applies to each person's connection. Tool calls use that person's authenticated
identity, and tour requests use their brightplace account's contact details unless
they explicitly provide different details for the booking.

See [Claude's custom connector setup guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
for organization setup and permissions.

## Recover a disconnected or expired connection

If you see `Authentication required`, open Claude's connector settings and connect
or reconnect brightplace. If necessary, remove and re-add the connector and finish
sign-in. An attached connector can list tools without being signed in.

Do not switch to no authentication or paste a token into the server URL.
See [OAuth and Scopes](/security/oauth-scopes) for discovery, consent, and refresh
behavior, and [Errors & Troubleshooting](/errors-troubleshooting) for other errors.


# Other Clients
Source: https://docs.brightplace.ai/install/other-clients

Add brightplace Connect to any MCP client that supports remote servers.

Any client that supports remote MCP over HTTPS and the OAuth flow below can
use brightplace Connect. The [Claude](/install/claude),
[ChatGPT](/install/chatgpt), and [Perplexity](/install/perplexity) guides cover
the clients we test against; use this page for everything else.

## What your client needs

* Support for **remote** MCP servers (a server URL), not just local stdio
  servers.
* The ability to reach the public internet over HTTPS.
* OAuth Authorization Code with PKCE and compatible client registration.
  All tool calls require a signed-in brightplace identity; anonymous clients
  can discover tools but cannot use them.

## Add the server

1. Open your client's connector, integration, or MCP server settings.
2. Add a custom remote MCP server.
3. Enter the endpoint:

```text theme={null}
https://mcp.brightplace.ai/mcp
```

4. Choose OAuth and complete the brightplace sign-in and consent flow. If your
   client cannot complete OAuth, use a supported client instead.
5. Save and enable the server for the conversation or workspace where you want
   to use it.

On team, business, or enterprise plans, an administrator may need to add and
share the server before members can use it.

## Configuration reference

Some clients are configured with a JSON file rather than a settings UI. The
exact key names vary by client, but the shape is usually:

```json theme={null}
{
  "mcpServers": {
    "brightplace-connect": {
      "url": "https://mcp.brightplace.ai/mcp"
    }
  }
}
```

Check your client's documentation for the precise field names and where the
config file lives.

See [Usage](/usage) for the full tool flow, and
[Errors & Troubleshooting](/errors-troubleshooting) if a connection or tool
call fails.


# Install in Perplexity
Source: https://docs.brightplace.ai/install/perplexity

Add brightplace Connect as a custom remote MCP connector in Perplexity.

Perplexity supports custom remote MCP connectors on Pro, Max, and Enterprise
plans. Custom connectors are not available on the free tier. The brightplace
Connect endpoint must be reachable over the public internet via HTTPS.

## Add the connector

1. Go to [perplexity.ai/computer/connectors](https://perplexity.ai/computer/connectors).
2. Click **+ Custom connector**.
3. Set the name to `brightplace` and the MCP server URL to:

```text theme={null}
https://mcp.brightplace.ai/mcp
```

4. Click **Add**.
5. Search for `brightplace` in connectors, then click **brightplace**.
6. Click **Add connector** and follow the sign-in flow.

On Enterprise workspaces, an administrator may need to add and share the
connector org-wide, and may control whether members can add their own
connectors, before you can use it.


# Acceptable Use
Source: https://docs.brightplace.ai/policies/acceptable-use

Fair Housing, rate limits, abuse reporting, and safe tool use.

brightplace Connect is for renter-facing apartment search and tour workflows. Use it
only for objective rental criteria and renter-authorized actions.

## Fair Housing

brightplace works only with objective criteria such as:

* Price and rent range
* Bedrooms, bathrooms, and square footage
* Location and commute preferences
* Availability and lease timing
* Building and unit amenities
* Pet policy, parking, and accessibility features

Do not use brightplace Connect to filter, rank, steer, or describe housing based on
protected characteristics such as race, color, religion, sex, national origin,
familial status, disability, age of residents, source of income, or demographic
proxies.

When a request violates Fair Housing guardrails, `search_listings` returns
`FAIR_HOUSING_VIOLATION`.

## Rate limits

brightplace Connect applies server-side limits to protect the service and
connected partners.

| Scope | Limit |
| - | - |
| Per MCP session | 30 requests per minute |
| `search_listings` per session | 5 calls per minute |
| `get_listing` per session | 10 calls per minute |
| `get_tour_availability` per session | 10 calls per minute |
| `book_tour` per session | 3 calls per hour |
| Active booking requests per renter email | 2 active requests per 24 hours |

Rate-limit responses use `RATE_LIMITED` and include `retry_after_seconds` in
the error details when available.

## Tour request safety

`book_tour` submits a tour request for a renter. Clients should ask users to
review the renter contact information, listing, slot, and notes before calling
the tool.

## Abuse and security reports

Report abuse or suspected security issues through the public brightplace support
channel. Include the MCP session id, timestamp, client name, and a short
description.


# book_tour
Source: https://docs.brightplace.ai/reference/tools/book-tour

Submit a tour request using the renter's confirmed preferences.

`book_tour` requires a signed-in account. Call `get_tour_availability` first and
confirm the renter authorizes sending their contact details to the property.

## Input

```json theme={null}
{
  "listing_id": "listing-record-id",
  "slot": {
    "starts_at": "2026-10-02T10:00:00-04:00",
    "ends_at": "2026-10-02T10:30:00-04:00"
  },
  "mode": "slots",
  "tour_type": "in_person",
  "move_in_date": "2026-11-01"
}
```

| Field | Type | Required | Notes |
| - | - | - | - |
| `listing_id` | string | Yes | Listing snapshot id returned by `search_listings`. |
| `slot` | object | For slots mode | Exact `starts_at` and `ends_at` from availability. |
| `mode` | string | No | `slots`, `request`, or `contact`; defaults to `slots` when a slot is supplied, otherwise `request`. |
| `tour_type` | string | No | Renter's preference: `in_person`, `self_guided`, or `video`. |
| `move_in_date` | date string | No | Renter-supplied YYYY-MM-DD. Never infer it from availability or the tour date. |
| `renter` | object | No | Defaults to signed-in account details. Override only at the user's request. Requires `first_name`, `last_name`, and `email`; `phone` is optional. |

For `request_only` or `contact_only` availability, omit the slot and use
`mode="request"` or `mode="contact"`. The worker must not select an arbitrary
appointment time. Required missing preferences or incompatible layout choices
stop the request for review instead of being filled with defaults.

## Output

```json theme={null}
{
  "tour_id": "book_01HZY...",
  "status": "submitted",
  "next_step_message": "Your tour request is in! The property will follow up by email to confirm the appointment.",
  "listing_id": "listing-record-id",
  "requested_start": "2026-10-02T10:00:00-04:00",
  "requested_end": "2026-10-02T10:30:00-04:00",
  "tour_type": "in_person",
  "mode": "slots"
}
```

`submitted` acknowledges the asynchronous request, not a confirmed appointment.
`get_tour_booking` returns its later status. `needs_review` can indicate missing
renter input, an unavailable requested option, or an unverified confirmation.
Read its message before retrying; an uncertain submission may already have reached
the property. The worker does not automatically resubmit.

## Limits and errors

brightplace limits active tour requests to 2 per renter email in a rolling
24-hour window. Additional active requests return `BOOKING_LIMIT_REACHED`.
Invalid input, including an invalid move-in date, returns a validation error.


# get_financial_guide
Source: https://docs.brightplace.ai/reference/tools/get-financial-guide

Answer affordability, budgeting, and cost-of-living questions.

`get_financial_guide` answers affordability, budgeting, and cost-of-living
questions using a curated financial reference library — cost of living, rent
benchmarks by metro, taxes, median income, utilities, and renters insurance. It
may take several seconds to return.

## When to use it

Use it for questions like "what can I expect to pay?", "what's a reasonable
budget for this city?", "is this rent affordable?", "what income do I need?",
"how much should I budget for utilities?", or "how does cost of living compare
to another city?". Prefer it over a general web search for these questions.

Pass a `query` with the renter's question and/or a `listing_id` to frame the
answer around that listing's city and rent. **At least one of `query` or
`listing_id` is required.** When only `listing_id` is given, a general
affordability overview for its city is returned.

Requests that tie affordability to a protected class are blocked by Fair
Housing guardrails and return `FAIR_HOUSING_VIOLATION`.

## Input

```json theme={null}
{
  "listing_id": "listing-record-id",
  "query": "what income do I need to afford this?"
}
```

| Field | Type | Required | Notes |
| - | - | - | - |
| `listing_id` | string | Conditional | A listing snapshot id from `search_listings`. When provided, the answer is framed around that listing's city and rent. |
| `query` | string | Conditional | The financial question to answer. Required when no `listing_id` is given. |

## Output

```json theme={null}
{
  "status": "available",
  "listing_id": "listing-record-id",
  "query": "what income do I need to afford this? (listing in Austin, TX for a renter paying $2200/mo)",
  "city": "Austin",
  "state": "TX",
  "message": null,
  "content": "A common guideline is spending no more than 30% of gross income on rent...",
  "source": "Curated financial reference library"
}
```

| Field | Type | Notes |
| - | - | - |
| `status` | string | `available` when reference data matched; `no_data` when nothing matched. |
| `listing_id` | string \| null | Echoes the requested id, or `null` when only a `query` was given. |
| `query` | string | The resolved query, including any city/rent context added from the listing. |
| `city` | string \| null | The listing's city when a `listing_id` framed the answer; otherwise `null`. |
| `state` | string \| null | The listing's state, if known. |
| `message` | string \| null | Set when `status` is `no_data`, explaining why; otherwise `null`. |
| `content` | string \| null | The financial digest when `available`; otherwise `null`. |
| `source` | string \| null | Provenance line for the content; `null` when no data matched. |

When no reference data matches, the tool returns a successful response with
`status: "no_data"` and a human-readable `message` rather than an error.
Unknown listing ids return `LISTING_NOT_FOUND`.


# get_listing
Source: https://docs.brightplace.ai/reference/tools/get-listing

Read full detail for one listing snapshot.

`get_listing` returns full detail for one listing returned by
`search_listings`.

## Input

```json theme={null}
{
  "listing_id": "listing-record-id"
}
```

| Field | Type | Required | Notes |
| - | - | - | - |
| `listing_id` | string | Yes | A listing snapshot id returned by `search_listings`. |

## Output

The tool returns `ListingDetail`.

```json theme={null}
{
  "listing_id": "listing-record-id",
  "unit_id": "unit-id",
  "property": {
    "name": "Example Apartments",
    "address": "123 Main St",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11201",
    "latitude": 40.7128,
    "longitude": -74.006,
    "building_type": "apartment",
    "year_built": 2019,
    "description": "Modern apartment community.",
    "amenities": ["Pool", "Fitness center"],
    "images": ["https://example.com/property.jpg"]
  },
  "unit": {
    "name": "Apt 5B",
    "floor_plan": "A1",
    "beds": 1,
    "baths": 1,
    "sqft": 720,
    "floor": 5,
    "amenities": ["In-unit laundry"],
    "images": {
      "photos": ["https://example.com/unit.jpg"],
      "floorplans": [],
      "other": []
    }
  },
  "economics": {
    "rent": 3400,
    "rent_max": null,
    "deposit": 500,
    "concessions": "1 month free",
    "lease_term": 12,
    "available_at": "2026-07-01",
    "fees": [],
    "listing_url": "https://operator.example/listing"
  },
  "ratings": {
    "brightplace_grade": "A",
    "review_confidence": "high",
    "walking_grade": "A",
    "transit_grade": "B+",
    "biking_grade": "B",
    "schools_grade": null
  },
  "reviews_summary": "Residents mention responsive maintenance.",
  "nearby_schools": []
}
```

Unknown listing ids return `LISTING_NOT_FOUND` with the offending
`listing_id` in `error.details`.

## brightplace grades

The `ratings` block summarizes a listing's quality and location as letter
grades on a shared scale. Any grade can be `null` when the underlying data is
not available for that listing, so treat a missing grade as "unknown," not
"bad." Present them to renters as a helpful summary, not as the sole basis for
a decision.

| Grade | What it measures |
| - | - |
| `brightplace_grade` | Overall resident-satisfaction quality of the property. |
| `review_confidence` | Confidence of rating based on review volume. |
| `walking_grade` | How walkable the surrounding area is. |
| `transit_grade` | Access to public transit. |
| `biking_grade` | How bike-friendly the area is. |
| `schools_grade` | Quality of nearby schools. |

`review_confidence` is a separate signal, not a letter grade — read it
alongside `brightplace_grade`. An `A` backed by `low` confidence rests on few
reviews.


# get_neighborhood_guide
Source: https://docs.brightplace.ai/reference/tools/get-neighborhood-guide

Get curated neighborhood context for a listing's area.

`get_neighborhood_guide` returns neighborhood information for a listing's
immediate area, extracted from curated local renter-forum research. It covers
select major US metros and may take several seconds to return.

## When to use it

Use it after `search_listings` or `get_listing` when a renter wants to
understand what living near a specific listing is like — local character,
getting around, what residents say about the area.

The guide is descriptive, not a steering tool. Requests that ask about the
demographic makeup of an area or otherwise touch protected classes are blocked
by Fair Housing guardrails and return `FAIR_HOUSING_VIOLATION`.

## Input

```json theme={null}
{
  "listing_id": "listing-record-id"
}
```

| Field | Type | Required | Notes |
| - | - | - | - |
| `listing_id` | string | Yes | A listing snapshot id returned by `search_listings`. |

## Output

```json theme={null}
{
  "guide_status": "available",
  "coverage": "neighborhood",
  "listing_id": "listing-record-id",
  "city": "Brooklyn",
  "state": "NY",
  "message": null,
  "content": "Park Slope is known for tree-lined blocks, the Prospect Park edge, and...",
  "source": "Curated renter forum research for Brooklyn"
}
```

| Field | Type | Notes |
| - | - | - |
| `guide_status` | string | `available` when a guide was found; `no_guide_for_city` when none exists for the listing's city. |
| `coverage` | string \| null | When `available`: `neighborhood` means the content is specific to the listing's immediate area; `city` means no area-specific material was found, so the content is general city-level highlights. `null` when no guide is available. |
| `listing_id` | string | Echoes the requested id. |
| `city` | string | The listing's city (may be empty if none is on record). |
| `state` | string \| null | The listing's state, if known. |
| `message` | string \| null | Set when `guide_status` is `no_guide_for_city`, explaining why; otherwise `null`. |
| `content` | string \| null | The neighborhood digest when `available`; otherwise `null`. |
| `source` | string \| null | Provenance line for the content; `null` when no guide is available. |

When no guide exists for the city, the tool returns a successful response with
`guide_status: "no_guide_for_city"` and a human-readable `message` rather than
an error. Unknown listing ids return `LISTING_NOT_FOUND`.


# get_tour_availability
Source: https://docs.brightplace.ai/reference/tools/get-tour-availability

Check tour slots for one listing.

`get_tour_availability` checks available tour slots for one listing snapshot.

## Input

```json theme={null}
{
  "listing_id": "listing-record-id",
  "date_range": {
    "start": "2026-07-01",
    "end": "2026-07-14"
  }
}
```

| Field | Type | Required | Notes |
| - | - | - | - |
| `listing_id` | string | Yes | A listing snapshot id returned by `search_listings`. |
| `date_range.start` | date | No | ISO date. |
| `date_range.end` | date | No | ISO date on or after `start`. |

When `date_range` is omitted, brightplace checks a 14-day window starting on
the current date.

## Output

```json theme={null}
{
  "availability_status": "available",
  "message": null,
  "slots": [
    {
      "slot_id": "slot-id-from-provider",
      "starts_at": "2026-07-02T10:00:00Z",
      "ends_at": "2026-07-02T10:30:00Z",
      "tour_type": "self_guided"
    }
  ]
}
```

| Status | Meaning |
| - | - |
| `available` | One or more slots are available. |
| `no_slots` | The provider was checked but had no matching slots. |
| `tours_not_available` | Tours are not available for the listing. |

Unknown listing ids return `LISTING_NOT_FOUND`.


# search_listings
Source: https://docs.brightplace.ai/reference/tools/search-listings

Search apartment listings with objective filters.

`search_listings` searches apartment listings through brightplace using
objective renter criteria.

## When to use it

Use `search_listings` when a renter asks for apartments matching objective
criteria such as price, location, bedrooms, bathrooms, amenities, or move-in
timing.

Do not use it for protected-class or demographic steering requests. Those
requests return `FAIR_HOUSING_VIOLATION`.

## Input

```json theme={null}
{
  "query": "rooftop pool near transit",
  "filters": {
    "locations": [{ "city": "brooklyn", "state": "ny" }],
    "names": ["greystar"],
    "beds": 1,
    "baths": 1,
    "minPrice": 2500,
    "maxPrice": 4500
  },
  "limit": 20
}
```

| Field | Type | Required | Notes |
| - | - | - | - |
| `query` | string | No | Semantic search text. Empty strings are treated as omitted. |
| `filters.locations` | array | No | City/state filters. Use lowercase city and two-letter state. |
| `filters.names` | array | No | Property manager brands or specific building names. See below. |
| `filters.beds` | number | No | Exact bedroom count. |
| `filters.baths` | number | No | Minimum bathroom count. |
| `filters.minPrice` | number | No | Minimum monthly rent. |
| `filters.maxPrice` | number | No | Maximum monthly rent. |
| `limit` | integer | No | Defaults to 20. Maximum 50. |

Filter-only searches are allowed. When `query` is omitted, brightplace ranks
results from the objective filters provided by the renter.

### Searching by manager or building name

Each entry in `filters.names` is matched case-insensitively as a substring of
both the property manager's name and the building's name, so you can pass a
renter's phrasing without deciding which one they meant: `["greystar"]` reaches
`Greystar Real Estate Partners`, and `["roosevelt collection"]` reaches
`Roosevelt Collection Lofts`. Pass only the distinctive part of the name, not
`"greystar apartments"`. Multiple entries widen the search to any of them, and
the filter combines with location and price as an AND. An empty result means
brightplace holds no inventory under that name.

## Output

The tool returns `ListingSummary[]`.

```json theme={null}
[
  {
    "listing_id": "listing-record-id",
    "unit_id": "unit-id",
    "property_name": "Example Apartments",
    "unit_name": "Apt 5B",
    "latitude": 40.7128,
    "longitude": -74.006,
    "beds": 1,
    "baths": 1,
    "sqft": 720,
    "rent": 3400,
    "concessions": ["1 month free on select lease terms"],
    "fees": [
      {
        "name": "Application fee",
        "amount": 75,
        "frequency": "one_time"
      }
    ],
    "available_at": "2026-07-01",
    "primary_photo_url": "https://example.com/photo.jpg"
  }
]
```

`listing_id` is the listing snapshot id to pass into `get_listing`,
`get_tour_availability`, and `book_tour`.


# OAuth and Scopes
Source: https://docs.brightplace.ai/security/oauth-scopes

Authentication requirements, account consent, and token recovery for brightplace Connect.

## Account and access requirements

Sign in to a brightplace account and authorize your MCP client before using any
tool. The server permits `initialize` and `tools/list` before sign-in so clients
can discover the connector; discovery alone does not grant tool access.

A tool call without an authenticated renter identity receives HTTP `401` with a
`WWW-Authenticate` header pointing to OAuth discovery metadata. Complete the
sign-in flow, then retry the request. Opening an anonymous connection or removing
an expired token does not restore tool access.

## Discovery and registration

Use this exact production server URL and OAuth resource/audience:

```text theme={null}
https://mcp.brightplace.ai/mcp
```

Protected-resource metadata is available at both paths:

```text theme={null}
https://mcp.brightplace.ai/.well-known/oauth-protected-resource/mcp
https://mcp.brightplace.ai/.well-known/oauth-protected-resource
```

Discover the issuer from `authorization_servers`; do not hard-code an AuthKit
hostname. The issuer serves its own authorization-server metadata. The MCP origin
also exposes a proxy at `/.well-known/oauth-authorization-server`.

| Item | Configuration |
| - | - |
| Grant | Authorization Code with PKCE (`S256`) |
| Resource/audience | `https://mcp.brightplace.ai/mcp` |
| Client registration | AuthKit advertises Client ID Metadata Documents (CIMD) and Dynamic Client Registration (DCR). |
| Client authentication | Discover supported methods from the issuer metadata. |

[Claude's authentication documentation](https://claude.com/docs/connectors/building/authentication)
says Claude selects CIMD when the issuer advertises both
`client_id_metadata_document_supported: true` and `none` in
`token_endpoint_auth_methods_supported`; otherwise it can fall back to DCR.
Both values are advertised by brightplace's production and staging issuers as of
September 14, 2026; production was rechecked on October 1, 2026. This establishes
discovery compatibility, not a guarantee
that a particular client has completed login. Leave manually entered client
credentials empty for the standard Claude connection flow.

In Claude's custom connector setup, select **Sign in now** and **Use Claude’s
published identity**, and leave **Request headers** empty. Sign-in is required
for all tools even if Claude detects **No sign-in** during public tool discovery.
In the standard organization setup, each member connects their own brightplace
account; adding the connector does not share an administrator's login. See
[Install in Claude](/install/claude) for the setup steps and authentication choices.

DCR-capable clients discover `registration_endpoint` from the issuer. Registration,
consent, token exchange, and refresh are handled by AuthKit and the MCP client;
brightplace Connect validates the access token for the configured issuer and audience.

## Identity scopes and consent

| Scope | Purpose |
| - | - |
| `openid` | Establishes an authenticated identity. |
| `email` | Resolves the connected account's email when available. |
| `profile` | Resolves the connected account's name when available. |

The identity is used to attribute tool calls to the renter. Tour requests may use
the signed-in account's name and email; confirm the contact details and intent to
send them to the property before submitting a request. These scopes do not imply
separate read-only or booking-only permissions: review the tool's action before
approving it.

Consent does not authorize signing a lease, submitting an application, or
contacting a property outside the explicit tool flow. Use must follow
[Acceptable Use](/policies/acceptable-use).

## Token lifecycle and reconnecting

The protected resource advertises `openid`, `email`, and `profile`. AuthKit also
advertises `offline_access` and the refresh-token grant. Claude may append
`offline_access` to obtain a refresh token. Token issuance and lifetime depend on
the authorization server and client configuration; refresh is not guaranteed for
every client.

When an access token expires, the client should refresh it if supported. If
refresh fails or is unavailable, reconnect and sign in again before retrying the
tool. The HTTP authentication challenge uses `invalid_token` / `Authentication
required`; clients must not rely on receiving a distinct `TOKEN_EXPIRED` tool error.

Disconnect in the client's connector settings to remove that client's connection.
Clients should discard their stored credentials. Disconnecting does not itself
prove an already-issued token was revoked at AuthKit; provider-side revocation and
token expiry are separate from removing a connector.

See [Errors & Troubleshooting](/errors-troubleshooting) for recovery steps.

## Client guidance

* Send tokens only in the `Authorization: Bearer` header, never in URLs.
* Store credentials securely within the consenting account's client connection.
* Use the stage-correct MCP URL as the OAuth resource and audience.
* Do not put tokens into prompts, logs, analytics, or tool outputs.
* Show the [Privacy Policy](https://www.brightplace.ai/privacy) and
  [Terms of Service](https://www.brightplace.ai/terms) during connection.

## Related policies

* [Privacy Policy](https://www.brightplace.ai/privacy)
* [Terms of Service](https://www.brightplace.ai/terms)
* [Fair Housing commitment](https://www.brightplace.ai/fair-housing)


# Usage
Source: https://docs.brightplace.ai/usage

How to drive brightplace Connect and read its tool results.

## Get started

1. Add the remote MCP server URL in your AI client. See [Install](/install/claude)
   for client-specific steps.
2. Sign in and complete the brightplace consent flow before calling tools.
3. Ask the client to use brightplace Connect for an apartment search.
4. Review listing details, tour slots, and any tour request before acting on
   them.

## Typical flow

A renter conversation usually walks through the tools in this order:

1. `search_listings` — find listings matching objective criteria.
2. `get_listing` — read full detail, including brightplace grades, for a result.
3. `get_neighborhood_guide` / `get_financial_guide` — add neighborhood context
   and affordability detail for a listing.
4. `get_tour_availability` — check open tour slots.
5. `book_tour` — submit a tour request for a chosen slot.

Only `book_tour` performs a write. Review the renter name, email, phone,
listing, and slot before allowing it.

## Example workflow

A full renter conversation, with the tool each turn triggers:

1. **Search.** The renter asks:

   ```text theme={null}
   Use brightplace Connect to search for one-bedroom apartments in Brooklyn under $4,500 that are pet friendly and near the subway.
   ```

   The client calls `search_listings` and returns a list of matches.

2. **Inspect a result.** The renter asks to see one of them:

   ```text theme={null}
   Show me the full details for the second result.
   ```

   The client calls `get_listing` with that `listing_id`, including its
   brightplace grades.

3. **Add context.** The renter wants more than the snapshot:

   ```text theme={null}
   What's the neighborhood like, and is the rent affordable on a $120k salary?
   ```

   The client calls `get_neighborhood_guide` and `get_financial_guide` for the
   listing.

4. **Find a tour.** The renter asks:

   ```text theme={null}
   Are any tours available this weekend?
   ```

   The client calls `get_tour_availability` and lists open slots.

5. **Book it.** The renter picks a slot:

   ```text theme={null}
   Book the Saturday 11am tour. My name is Jordan Lee, jordan@example.com.
   ```

   The client calls `book_tour`. Confirm the renter name, email, phone,
   listing, and slot before allowing this write.

## Tool results

Tool responses use a consistent envelope:

```json theme={null}
{
  "ok": true,
  "data": {},
  "latency_ms": 42
}
```

Errors use the same envelope with an `error` object:

```json theme={null}
{
  "ok": false,
  "error": {
    "error_code": "VALIDATION_ERROR",
    "message": "Tool input failed validation.",
    "details": {}
  },
  "latency_ms": 2
}
```

See [Errors & Troubleshooting](/errors-troubleshooting) for the public error
set and how to handle each code.