Troubleshooting

​

Connection Issues

​

Tools not appearing in my AI client

1. Restart your client after making configuration changes
2. Check the endpoint is reachable:
   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
• 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. Wait 60 seconds before retrying.

​

”Quota exceeded” error

Your monthly request quota has been exhausted. Upgrade your plan 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
• Get an API key
• Customer portal