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

# Troubleshooting

> Fix connection, sign-in, quota, rate limit, and empty result problems with the Copyfy MCP.

Start with the free `get_usage` tool: ask your assistant *"Check my Copyfy MCP usage."* If it answers with your plan and credits, the connection works and the problem is in the query or the quota.

## 401 Unauthorized or the client keeps asking to sign in

The credential is missing, expired, or revoked.

* **OAuth clients** (Claude, ChatGPT, Cursor, and others): disconnect Copyfy in the client, then connect again and click **Allow access** on the Copyfy consent screen. In Claude Code, run `/mcp`, select `copyfy`, and authenticate again. A client that has not been used for more than 30 days must sign in again.
* **API keys**: check that the header is exactly `Authorization: Bearer cpy_…`, with the full key and no extra spaces or quotes. Check on the [Integrations page](https://app.copyfy.io/dashboard/api) that the key has not been revoked. If you are not sure, create a new key.
* If you revoked the app under **Connected apps**, the client must sign in again.

## plan\_upgrade\_required, trial\_not\_eligible, or subscription errors

The connection works, but your account cannot use the MCP right now. The error message says why: the plan is Starter, the subscription is still in trial, a payment failed, or the subscription is paused. See [Errors](/errors) for the fix. Access comes back automatically once the subscription is active on Growth or Pro.

## rate\_limited

Your account made more than 30 calls in one minute, across all clients and keys. Wait for `retry_after_seconds`, then retry. If an agent loops over many searches, ask it to use larger pages (`per_page` up to 25) and fewer calls.

If the message mentions failed sign-ins from your network, a device on the same network is sending invalid keys. Retry after a minute and remove any old or revoked key from your tools.

## quota\_exceeded

You used all your credits for the current monthly period. The error includes `resets_at`, the date your credits reset. Upgrade from Growth to Pro for 3,000 credits per month, or wait for the reset. See [Quotas and limits](/quotas-and-limits).

## Empty results

A search that returns `"total": 0` costs one credit, like any successful search. To get results:

* Remove filters one at a time. Revenue, traffic, and growth ranges combined with a small niche often leave nothing.
* Check filter values with `list_filter_options`. Niche names must match Copyfy's niche list, and countries use two-letter codes (`GB`, not `UK`).
* Check the units: revenue and prices are in the store's currency, and `traffic_growth_pct` is a percentage (`20` means +20%).
* Try the same filters in the Copyfy dashboard. The MCP returns the same results as the dashboard.

## Copyfy tools do not appear in the client

* Check that the URL is exactly `https://app.copyfy.io/mcp`, with `https` and the `/mcp` path.
* Make sure the Copyfy connector is turned on for the conversation (Claude, ChatGPT, Perplexity) or enabled in the MCP settings (Cursor, VS Code, Devin Desktop).
* In VS Code, use Copilot Chat in **Agent** mode. Tools are not available in Ask mode.
* Restart the client after editing a configuration file.

## Corporate proxy or firewall

Clients that run on your computer (Cursor, Claude Code, Codex, VS Code, Gemini CLI, Devin Desktop) connect to `app.copyfy.io` over HTTPS on port 443. If your company filters traffic:

* Ask your IT team to allow `https://app.copyfy.io/mcp`, `https://app.copyfy.io/.well-known/*`, and the OAuth pages under `https://app.copyfy.io/oauth/` and `https://app.copyfy.io/api/oauth/`.
* The endpoint uses Streamable HTTP. Proxies that buffer or cut long-lived responses can break it; allow streaming (`text/event-stream`) responses for this host.
* If the browser sign-in is blocked, use an [API key](/authentication#api-keys) instead of OAuth.

Claude, ChatGPT, and Perplexity connect from their own servers, so your network settings do not affect them after sign-in.

## Results differ from the dashboard

The MCP and the dashboard use the same data and ranking. Differences usually come from filters: check that the dashboard has no filter left from an earlier search, and compare with the same filters, sort order, and page size.

## Still stuck

Contact Copyfy support from the dashboard. Include the client you use, the time of the call, and the error `code`. Never include your API key.