Troubleshooting

Symptom, cause, fix — including the errors that look alarming but are working as designed.

​

Connection problems

What you see	Why	Fix
The client can’t find the connector	The URL is wrong — usually missing /mcp at the end.	Copy the Connector URL from Settings → Developers → AI connectors (MCP).
The connect page says the token has expired, is disabled, or was not recognised	The token can’t be used as pasted.	Expired: create a new token. Disabled: Enable it. Not recognised: copy it again, or create a new one if it was revoked or regenerated.
The connect page says the integration is switched off for that store	The store’s Connector switch is off.	Press Turn on on the Connector card, then connect again.
401 INVALID_MCP_TOKEN / INVALID_TOKEN_FORMAT	The token was revoked or regenerated, or only part of it was pasted.	Copy the whole token. If it was revoked or regenerated, use a new one.
401 MCP_TOKEN_DISABLED	The token is disabled.	Enable it in the Access tokens table.
401 MCP_TOKEN_EXPIRED	The token passed its expiry.	Create a new token and reconnect — an expired token can’t be regenerated.
401 MCP_DISABLED	The store’s Connector switch is off.	Turn on. Reconnecting won’t help until you do.
401 MCP_PLAN_DISABLED	Your plan doesn’t include AI MCP Integration. You can still authorize, but every call is refused.	Change to a plan that includes it on the Plans page.
401 SHOP_NOT_INSTALLED	Notifylyst was uninstalled from that store.	Reinstall the app, then create a new token.
Works in one client, not another	That client may not support remote MCP with a header.	Use the Claude Desktop (older) config from Other AI clients.

​

While using it

What you see	Why	Fix
A tool is missing, or “Forbidden: this token is not allowed to use this tool.”	The token doesn’t allow that tool. A token’s tools can’t be edited.	Create a new token with that tool and reconnect.
429 “Rate limit exceeded”	More requests a minute than your plan allows — usually an agent in a loop.	Wait (the response says how long) and narrow the question. Ask for one report, not all ten.
”Tool execution timed out.”	Very wide date ranges and large pages can take too long.	Narrow the date range or the page size, then ask again.
The AI asks you to confirm before a change	Working as designed — every change is previewed first.	Read the summary and say yes if it’s right. See Security & privacy.
”This confirmation has expired” or “already used”	Confirmation tickets last 5 minutes and work once.	Ask again; the AI previews the change again for you to confirm.
”The arguments do not match…”	The confirming call differed from the preview.	Ask again so the AI previews and confirms the same change.
A plan change “didn’t happen”	No tool changes your plan.	Switch on the app’s Plans page, where Shopify asks you to approve.
A CSV export of best-converting or most-wanted is refused	Those two are only downloadable from the app.	Download them from the Analytics page.
A test notification is refused	Test sends go only to your store’s own addresses, at most 20 an hour, and need credit left. WhatsApp alerts aren’t being sent yet, so WhatsApp tests are refused.	Send to a staff, report or sign-up alert address, wait for the hour to pass, or use another channel.
A test notification never arrived	The channel may not be on.	Ask for get_settings with the channels section to confirm the channel is live, then check spam.
Numbers disagree with the app	Almost always a different date range or channel filter, not a different source — both read the same data.	Ask the agent which range and filter it used, then match it in the app.
Failed to reconnect SSE stream	The client tried to hold a streaming connection open. The connector answers each request and closes.	Restart the client. Point uptime monitors at /healthz, never /mcp.

​

Diagnosing a token without a client

The health check reports exactly what a token allows, which settles most “is it the token or the client?” questions in one command:

curl -s https://notifylyst-mcp.cblyst.com/healthz \
  -H "Authorization: Bearer nl_mcp_…"

• Returns status ready with the store, allowed tools and expiry → the token is fine, the problem is client-side.
• Returns 401 → the token can’t be used: it may be invalid, disabled or expired, the Connector switch may be off, or the plan may not include the connector. The connect page and the error code in a client tell you which.
• Returns 429 → you are over the rate limit. Each check uses one request.

Full list of refusals: Error codes.

​

Still stuck?

Contact Notifylyst support from inside the app, and include:

• Your store domain (your-store.myshopify.com).
• The token’s name — never the token itself.
• The tool you were trying to use, and roughly when, with your time zone.
• The exact error text, or a screenshot with any customer data blurred.

With those four things we can tell you what actually happened rather than guessing.

​

Next

Error codes — every refusal, with the exact message.