Skip to main content
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 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 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.

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 gives required_credits, remaining_credits, and buy_credits_url.
  • cost_limit_exceeded: the generation would cost more than the max_ai_credits you allowed.
Nothing is charged in either case. Ask “What is my Copyfy AI credit balance?”: the free get_usage tool shows it.

A creation job stays running or ends as unknown

Creation tools return a job that you follow with the free get_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_unavailable with a job_id, Copyfy could not confirm the start: check that job before trying again, so nothing is created twice.
  • unknown on a Shopify import: check the products in your Shopify admin before importing again, since the product may already exist.
  • unknown with results_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 for search_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, not UK).
  • Check the units: revenue and prices are in the store’s currency, and traffic_growth_pct is a percentage (20 means +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_products reports a translated keyword in query_rewrite.

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