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, selectcopyfy, 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 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 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 forretry_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 includesresets_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.
insufficient_credits or cost_limit_exceeded
generate_ad_image and copy_video_ad spend AI credits on top of the MCP credit.
insufficient_credits: your AI credit balance is too low for this generation. The error givesrequired_credits,remaining_credits, andbuy_credits_url.cost_limit_exceeded: the generation would cost more than themax_ai_creditsyou allowed.
get_usage tool shows it.
A creation job stays running or ends as unknown
Creation tools return a job that you follow with the freeget_job_status, waiting poll_after_seconds between calls. Images usually take under a minute, video remakes 4 to 7 minutes, and Shopify imports a few seconds.
- When a creation tool answers
service_unavailablewith ajob_id, Copyfy could not confirm the start: check that job before trying again, so nothing is created twice. unknownon a Shopify import: check the products in your Shopify admin before importing again, since the product may already exist.unknownwithresults_unavailable: the images or videos were deleted from your Copyfy library.failed: the MCP credit is given back. See Statuses for the AI credits.
shopify_not_connected or shopify_reconnect_required
import_product_to_shopify needs your Shopify store connected to Copyfy. Open the connect_url or reconnect_url from the error, connect the store, then ask again.
Cards do not appear
Cards appear forsearch_products, search_ads, search_ad_scripts, and get_shop in apps that support MCP Apps, such as Claude and ChatGPT. Other clients show the same results as text. If the cards look outdated in Claude Desktop, quit the app fully and open it again.
Empty results
A search that returns"total": 0 is free: the response shows "credits_used": 0. For search_products, the response also explains the empty page in zero_result_help: which filter emptied it, how many products match the keyword in the selected markets and in all of Copyfy, and whether a translated keyword was tried. See Empty results and translated keywords. 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, notUK). - Check the units: revenue and prices are in the store’s currency, and
traffic_growth_pctis a percentage (20means +20%). - Use the words stores write in their product titles: English for most stores, the store language when you filter on a non-English market or language.
- Try the same filters in the Copyfy dashboard. The MCP returns the same results as the dashboard, except when
search_productsreports a translated keyword inquery_rewrite.
Copyfy tools do not appear in the client
- Check that the URL is exactly
https://app.copyfy.io/mcp, withhttpsand the/mcppath. - 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 toapp.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 underhttps://app.copyfy.io/oauth/andhttps://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 instead of OAuth.
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 errorcode. Never include your API key.