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

# Troubleshooting

> Common issues and how to resolve them when using the Birdeye MCP Server.

## Connection Issues

### "Failed to connect to MCP server"

The AI client cannot reach `https://mcp.birdeye.com/mcp`.

* Verify the URL is entered exactly as: `https://mcp.birdeye.com/mcp`
* Check that your network allows outbound HTTPS connections
* Try disconnecting and re-adding the connector in your AI client

### "MCP server not responding"

The server may be temporarily unavailable. Wait a few minutes and retry.

***

## Authentication Issues

### "Authorization failed" or OAuth redirect not completing

* Ensure you are signing in with the correct Birdeye account credentials
* Check that your browser allows pop-ups from `mcp.birdeye.com`
* Try the connection flow in an incognito/private browser window

### "Token expired" or tools stop working after some time

OAuth access tokens have a limited lifetime. Most AI clients automatically refresh tokens in the background. If your client does not:

1. Disconnect the Birdeye connector from your AI client settings
2. Reconnect and complete the OAuth flow again to issue a new token

### Using an MCP client other than Claude or ChatGPT

Non-standard clients require a pre-registered redirect URI. Contact Birdeye Support with your client's redirect URI to get it authorized.

***

## Tool Errors

### "Tool returned no data" or empty response

* The date range or filters may be too restrictive — try widening the date range or removing filters
* Your account may not have data for the requested category (e.g., no surveys created yet)
* Some tools require `businessNumbers` from `get_child_locations` — confirm that step completed first

### "Missing required parameter"

Check the tool's parameter table in this documentation. Required parameters must be provided before the tool can execute.

### Tools work but return stale data

The Birdeye MCP Server returns live data on every call — there is no caching layer. If data appears stale, the underlying Birdeye account data may not have updated yet. Review ingestion times in your Birdeye dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.