Troubleshooting
Three checks that isolate the layer
Work out which of three things is broken before anything else. They have different fixes and look identical from the chat window.
- Does the client list the server?
/mcpin Claude Code, Settings → MCP in Cursor, the tools icon in Claude Desktop. Not listed means the client config is the problem — the server has not been reached. - Does it show 6 tools? Listed with zero tools means it was reached and the key was not accepted.
- Does a question get a real answer? Ask "is my cart drawer working right now?". A refusal here is the server talking.
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.
A space after the colon. Claude Desktop only, and the 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 and the whole file is ignored, including every other server in it. Paste it into a JSON validator before blaming the server.
The config file was replaced rather than added to. If other MCP servers vanished at the same time, this is what happened.
The server appears, but no tools
The server was reached and the key was refused. Ask a question and read the refusal.
| Refusal says | Means | What to do |
|---|---|---|
| This connection was revoked | The key was not accepted — see below | Check the header first |
| Isn't included in this store's current subscription | The subscription lapsed | Renew; the same key resumes working |
| Hit its limit of 60 requests per minute | Too many calls in one minute | Wait about a minute |
"This connection was revoked" covers more than a revoked key. The same message is returned when the client sends no key at all, when the key is unknown or expired, and when the app is no longer installed on the store.
So before you create a replacement, rule out the case a new key cannot fix: check that your client
is actually sending the Authorization header. If it is not, the new key will not be sent either.
Order to check in:
- Is the header present in the client's config, with
Bearerand a single space? - Is the app still installed on the store?
- Was the key revoked in Settings → Connect to AI? The connections list shows it.
Only after those three is minting a new key the right move. Revoking is not reversible, so a key destroyed on a wrong guess does not come back.
The key was accepted but the answers are wrong
Answers are about a different store. You have two stores connected and both configs name the
server aov-cart-drawer. AI clients key their list by name, so the second silently replaced the
first. Give each store a distinct name, remove both entries, and add them back.
Figures do not match the dashboard. Check dateRange and currency in the analytics result.
Dates are read in the store's own timezone.
Order count looks too low. ordersAttributedToDrawer counts orders this app recorded as going
through the cart drawer since install. It is not the store's total order count and will not match
Shopify's.
The answer is cut off
Results are capped at 16,000 characters, and anything longer is truncated with a note saying so.
On this app the payload that overflows is almost always get_translations on a multi-language
store. Ask for one locale. template will not help — the result is already one template.
An assistant that skips past the truncation note will summarise a partial result as though it were complete. If an answer looks thin for a store you know is busy, ask whether the result was truncated.
"No impressions" is not a fault
NO_IMPRESSIONS in the setup health result means the drawer has never been shown to a shopper.
Everything can be configured correctly and still produce it. It points at traffic, or at where the
drawer is set to appear — not at a broken setup.
Reporting a problem
Include:
- The client, and how you connected
- 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 either — the server holds only a fingerprint. If a key has appeared anywhere it should not have, revoke it and create a new one.