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, the connector list in ChatGPT or Claude. Not listed means the client config is the problem — the server has not been reached. - Does it show tools? A read-only connection shows 12 or 13 tools; a read and write connection shows 44. 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 wrong address. Clients that take an API key use https://aov-cart-drawer.firebaseapp.com/mcp.
ChatGPT and Claude on the web use the OAuth address from Settings → MCP connectors, which ends
in /oauth/mcp. The address is shown in the app next to each connection.
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 in the AOV Cart Drawer app | The key was not accepted — see below | Check the header first |
| Connecting this store to AI tools isn't included in this store's current subscription | The subscription does not include it, or it lapsed | Change the plan; the same connection resumes working |
| This connection hit its limit of 60 requests per minute | Too many calls in one minute | Wait about a minute |
| This key was issued for a different surface | A Store API key (aov_sk_) was used for MCP | Create a key in Settings → MCP connectors and use that |
"This connection was revoked" covers more than a revoked key. The same message is returned when the client sends no key at all, and when the key is unknown or expired.
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 key the one that was shown when you created the connection, copied whole?
- Was the connection revoked in Settings → MCP connectors? The connections list shows it.
Only after those three is creating a new key the right move. Revoking is not reversible, so a key destroyed on a wrong guess does not come back.
The assistant will not change anything
"This connection is read-only, so it cannot change cart drawer settings." The connection was created with Read only access. The access level cannot be changed afterwards. Create a new connection with Read and write, and use that one in your client. Then revoke the old one if you no longer need it.
The write tools are missing even on a read and write connection. Two things hide them. The drawer's settings have never been saved — open the Cart Editor, save once, and reconnect or ask again (the message is "Open Cart Editor, save its initial settings, then try again."). Or the tool belongs to the other drawer generation: some tools exist only for the earlier (v1) drawer and others only for v2. A tool that does not apply is not offered at all, so an assistant asked for it says it cannot find it. See what depends on your drawer version.
"Cart drawer configuration changed from revision X to Y. Read it again before retrying." Settings changed — in the app or by another connection — after the assistant last read them. Nothing was overwritten. Ask the assistant to read the settings again and repeat the request.
"Another change to this store is still being saved." Only one change to a store is saved at a time. Wait a few seconds and ask again.
The write limit. A connection can make 20 changes a minute. A long list of edits should be spread out, or batched into fewer calls.
"The change was saved and storefront publication is queued for retry." The change is stored but has not reached the storefront yet. Ask the assistant to check the operation status and retry the publication. If it still does not appear, open the Cart Editor and publish from there.
Sign-in (ChatGPT and Claude on the web)
The connection stays "Incomplete". The sign-in was started but not approved. Start the connection again from ChatGPT or Claude, and approve the request in the app with the one-time code. The code is 8 characters and valid for 10 minutes.
The one-time code does not work. Check that you are using the newest code — each sign-in attempt issues its own — and that it has not been more than 10 minutes. Approve only a code you just asked for.
The connection shows "Expired". The sign-in has lapsed. Connect again.
It connected but only reads. You approved Read only. Start a new connection and choose Read and write on the approval screen.
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. Name each after its store — aov-cart-drawer-your-store — 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. A range that starts before reward-bar tracking began
leaves that row out, and the result says so.
Order count looks too low. totalOrders counts orders this app recorded as going through the
cart drawer. It is not the store's total order count and will not match Shopify's.
A language shows no translations. That language has no override of its own, so shoppers see the base text. Your store's primary language usually has none, and that is normal.
The answer is cut off
Results are capped at 16,000 characters, and anything longer is truncated with a note saying so.
The payload that overflows is usually get_translations on a multi-language store, or
get_drawer_settings with every section on a busy store. Ask for one locale, or one section.
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.
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. If a key has appeared anywhere it should not have, revoke it and create a new one.