Troubleshooting
Three checks that isolate the layer
Before anything else, work out which of three things is broken. They have different fixes and look identical from the chat window.
- Does the client list the server at all?
/mcpin Claude Code, Settings → MCP in Cursor, the tools icon in Claude Desktop. If it is not listed, the problem is the client config — the server has not been reached yet. - Does it show 10 tools? A server listed with zero tools means it was reached but the key was not accepted.
- Does a question get a real answer? Ask "what free gift campaigns am I running?". A refusal here is the server talking, and the message names the cause.
The server does not appear in the client
Claude Desktop was not fully quit. Closing the window is not quitting on macOS. Quit from the menu or with Cmd+Q, then reopen.
Node.js is missing. Claude Desktop only — the connection runs through mcp-remote, which needs
Node.js 18 or newer. Without it the entry sits in the config and never starts.
A space after the colon. Claude Desktop only, and the single most common mistake:
Authorization:${AOV_MCP_KEY} has no space after the colon. A space breaks how mcp-remote
splits its arguments, and the only symptom is a server that will not connect.
The JSON is invalid. One trailing comma, one unbalanced brace, and the whole file is ignored — including every other server in it. Paste the file into any JSON validator before assuming the server is at fault.
The config file was replaced rather than added to. If other MCP servers disappeared at the same
time, this is what happened. Restore them and add the entry inside the existing mcpServers object.
The server appears, but no tools
The server was reached and the key was refused. Ask a question and read the refusal — it names the reason.
| Refusal says | Means | What to do |
|---|---|---|
| No key was sent with this request | The client is not sending the header at all | Fix the client config. Do not revoke your key — it is not the problem |
| This connection was revoked | The key was turned off in the app | Create a new key in Settings → Connect to AI |
| Isn't included in your current plan | The store is no longer on a paid plan | Upgrade. The same key resumes working, no need to re-mint |
| The app is no longer installed on this store | Free Gift was uninstalled | Reinstall. Revoking and re-minting will not bring the store back |
| Hit its limit of 60 requests per minute | Too many calls in one minute | Wait about a minute |
"No key was sent" and "this connection was revoked" are deliberately different messages, because the fixes are opposites. Revoking cannot be undone — treating a client that is not sending the header as a bad key destroys a perfectly good credential and leaves the real problem in place.
The key was accepted but the answers are wrong
Answers are about a different store. You have more than one store connected, and two entries
share a server name. AI clients key their list by name, so the second config silently replaced the
first. Give each store its own name — aov-upsell-your-store — remove both entries, and add them
back.
Figures do not match the dashboard. Check the period and timezone in the result. Analytics uses the store's own timezone, so its "yesterday" may not be yours. A window that includes today is marked partial and will not match a completed-day figure.
A percentage change is missing. The previous window was zero. There is no meaningful change from nothing; use the raw figures.
The answer is cut off
Results are capped at about 16,000 characters. Anything longer is truncated with a note saying so and suggesting a narrower request.
Narrow it: one campaign instead of every campaign, one widget type instead of all of them, one language instead of every language. Every tool that can return a lot takes a parameter that makes it return less.
The truncation note matters. An assistant that skips past it will summarise a partial result as though it were the whole picture — the numbers will look plausible and be wrong. If an answer feels suspiciously short on detail for a store you know is busy, ask whether the result was truncated.
"Not customised" is not "empty"
get_translations reports customised strings only. A store that has never edited its wording
comes back with nothing listed and a message saying so. That means the app's built-in wording is in
use — the widget is not blank, and nothing is broken.
"Connected" disappeared
Connected means the key was used in the last 15 minutes. AI clients do not hold a connection open; they call the server when they need something and then go quiet. A client sitting idle stops showing as connected while remaining perfectly usable. Ask it a question and the badge comes back.
Reporting a problem
Include:
- The client and how you connected — Claude Code, Cursor, Claude Desktop
- The exact refusal message, read back from the assistant
- The connection name, and when it was last used, from the connections list
- What you asked
Never include the key itself, in a ticket, a screenshot, or a chat log. Support cannot read it back to you either — the server stores only a fingerprint. If a key has appeared anywhere it should not have, revoke it and create a new one.