> ## Documentation Index > Fetch the complete documentation index at: https://docs.1eye.ai/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Diagnose MCP authentication, missing tools, search errors, pagination, and data mismatches. Start by identifying whether the failure is in client setup, authentication, a tool call, or the interpretation of the returned data. ## Connection checklist | Setting | Expected value | | - | - | | URL | `https://mcp.1eye.ai/mcp` | | Transport | Streamable HTTP / HTTP, according to the client's label | | Header name | `Authorization` | | Header value | `Bearer ` followed by the complete active API key | | Test tool | `get_workspace` with `{}` | Do not use a browser visit to the server as the only health check. A browser does not normally send your API-key header or perform the MCP handshake. A successful `get_workspace` call is a stronger connection check than a saved server entry. ## Authentication fails If the connection returns `401` or the client reports an authentication failure: 1. Verify the URL includes `/mcp`. 2. Verify the header contains `Bearer`, one space, and the full key. 3. Check that the key is active and has not been rotated or revoked. 4. If using a secret reference, verify the client process can resolve it. 5. Reconnect the client after changing the key or its configuration. A terminal export may not be visible to an already-running desktop application. In remote development, provide the variable to the host that establishes the MCP connection. Do not paste the secret into a support request to demonstrate it is set. These setup instructions use API-key authentication. Follow the [quickstart](https://docs.1eye.ai/mcp/quickstart.md) header configuration rather than an unrelated OAuth sign-in flow. ## The server is configured but tools are missing Confirm the server is enabled, the project or user configuration is the one the client actually loads, and no administrator policy or tool allow list is hiding it. Reload or reconnect the server if the catalog has changed. The current catalog contains 30 tools. Clients may show qualified names such as a server prefix plus `search_buyers`. Use the client's tool picker or MCP status view to inspect the live catalog. For Codex, `codex mcp get oneeye` checks the saved entry; an actual `get_workspace` call checks the live path. For Claude Code, inspect `/mcp`. Other clients expose their own server status and diagnostic logs. ## Wrong workspace or missing record Call `get_workspace` and compare the returned workspace with the one you intended. The key determines workspace scope. Copy resource IDs from a search or list in that workspace; do not substitute a company name, email, or ID from another resource type. If a record is unavailable, verify it is still present and visible in the current workspace. Do not infer that an unavailable ID exists elsewhere. ## Invalid search arguments Use only the [documented fields and operators](https://docs.1eye.ai/mcp/search-and-pagination.md). In particular: * `search_signals` requires at least one filter rule. * Type-specific signal fields and `trigger` require a compatible `signal_type` rule in the top-level `all` group. * `in` and `not_in` take non-empty arrays. * `between` takes two boundary values. * `in_last` takes an object such as `{"unit":"day","value":7}`. * Timestamps use RFC 3339; boolean fields take `true` or `false`. Buyer search supports attribution filters. Signal search exposes UTM and click-ID fields, but does not expose `attribution_type` or `attribution_source` as filters. ## Query timeout If a tool returns `query_timeout`, reduce the date range, choose a specific signal type, or add relevant buyer filters before retrying. Repeating the same broad query is unlikely to resolve a query-size problem. A small page size alone does not necessarily reduce the cost of finding and counting matches. ## Pagination fails or results appear incomplete Pass `next_cursor` back unchanged with the same tool, filter, and sort order. Restart the query after changing the search conditions. Read `total` for the complete match count and `data` for the current page. One page of signals cannot establish a complete buyer list or source breakdown when a continuation cursor remains. Deduplicate `buyer_id` before counting distinct buyers. ## Counts disagree with expectations Check which timestamp was used, the time zone, whether the count is buyers or signals, and whether the answer includes all result pages. Buyer creation time can be later than signal occurrence time. Lifetime signal counts on a buyer are not the same as activity counts within a particular week. For paid traffic, distinguish buyer attribution from the attribution of a particular website visit. A social or organic source is not sufficient evidence that a visit was paid. ## Rate limits or temporary failures If the client surfaces a rate-limit response, reduce concurrency and follow any retry guidance returned by the server, including `Retry-After` when present. For a temporary read failure, retry with backoff. Before retrying a write whose outcome is unclear, retrieve the affected record to check whether it already succeeded. The REST [Rate Limits](https://docs.1eye.ai/api-reference/rate-limits.md) and [Errors](https://docs.1eye.ai/api-reference/errors.md) pages describe the REST API. MCP clients may present protocol and tool errors differently; preserve the actual MCP error text instead of assuming the same response envelope or numerical quota. ## Contact support Email [hi@1eye.ai](mailto:hi@1eye.ai) with the client and version, tool name, time and time zone, redacted arguments, error message, and request ID if one was returned. Remove API keys, authorization headers, buyer contact data, and other private values from shared diagnostics. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.