> ## Documentation Index
> Fetch the complete documentation index at: https://qwady.wiki/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for Borough MCP

## Connection Issues

### Tools not appearing in my AI client

1. **Restart your client** after making configuration changes
2. **Check the endpoint** is reachable:
   ```bash theme={null}
   curl -X POST https://borough.qwady.app/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'
   ```
   A `401 Unauthorized` here is expected and **confirms the endpoint is up**: `/mcp` requires authentication. Your MCP client supplies credentials automatically; this manual curl omits them.
3. **Verify your config** file syntax (JSON must be valid)
4. **Check mcp-remote** is installed: `npx mcp-remote --version`

### "Authentication failed" error

* If you are using Claude or another OAuth-capable client, reconnect Borough and complete the Borough auth flow again
* If you are using direct bearer auth, verify your API key starts with `BOROUGH-`
* Check the key is active in the [customer portal](https://polar.sh/qwady-solutions-llc/portal)
* Ensure the `Authorization` header format is exactly `Bearer BOROUGH-<key>`

Free-tier MCP sessions can still authenticate through OAuth even if you do not attach a paid Borough API key.

### "Rate limit exceeded" error

Your plan's per-minute rate limit has been reached. Each MCP tool call consumes at least one API request. Searching by neighborhood or borough *name* also spends one extra request per name resolved (the server looks each name up via the areas endpoint). To avoid the extra lookups, pass numeric area IDs directly, or resolve them once with `list_areas`.

| Plan     | Rate Limit |
| -------- | ---------- |
| Free     | 10/min     |
| Starter  | 30/min     |
| Pro      | 60/min     |
| Business | 120/min    |

Wait 60 seconds before retrying.

### "Quota exceeded" error

Your monthly request quota has been exhausted.

| Plan     | Monthly Quota |
| -------- | ------------- |
| Free     | 100           |
| Starter  | 5,000         |
| Pro      | 25,000        |
| Business | 100,000       |

[Upgrade your plan](https://qwady.wiki/borough/tiers-and-pricing) for more requests.

## Tool-Specific Issues

### "Requires Starter plan" when calling get\_property

Property detail, building, and building listing tools require a Starter plan (\$19/mo) or higher. Free-tier users can use `search_rentals`, `search_sales`, `list_areas`, `get_market_snapshot`, `get_market_trends`, and `compare_neighborhoods`.

### "Requires Starter plan" for building or property tools

Property and building detail tools require a Starter plan (\$19/mo) or higher. Market tools are available to authenticated free-tier MCP users.

### Empty search results

* Try broader filters (remove price or bedroom constraints)
* Try an exact borough or neighborhood name directly, or lock the area ID first with `list_areas`
* Borough IDs: Manhattan=100, Bronx=200, Brooklyn=300, Queens=400, Staten Island=500

### Location name resolves to multiple areas

If Borough returns a short clarification list, choose one of the suggested IDs or provide a more specific location name. This usually happens with names that exist at multiple levels or in multiple contexts. Borough does not silently auto-pick in these cases because the MCP tools are optimized for certainty first.

### Photos do not render in my client

* Borough search results return `leadPhotoUrl` and `renderHints.imageUrl`, but this version does not send inline MCP image blocks
* Some clients render the proxied image URLs automatically; others may only use the text and map fields
* The most render-friendly fields to look for are `price`, `displayPrice`, `geoPoint`, `leadPhotoUrl`, and `renderHints`

### Amenity search returns few results

Amenities such as `DISHWASHER` and `WASHER_DRYER` are supported, but Borough may need to refine a small candidate set using listing detail before returning final matches. If your search is very narrow, try:

* widening the budget
* expanding to nearby neighborhoods
* reducing the required amenity set to one must-have amenity first

## Getting Help

* [Full Borough docs](https://qwady.wiki/borough/introduction)
* [Get an API key](https://qwady.wiki/borough/tiers-and-pricing)
* [Customer portal](https://polar.sh/qwady-solutions-llc/portal)