Skip to main content
Start by identifying whether the failure is in client setup, authentication, a tool call, or the interpretation of the returned data.

​
Connection checklist

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 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. 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 and Errors 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 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.