> ## Documentation Index
> Fetch the complete documentation index at: https://codebeans-cb-notifylyst.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://codebeans-cb-notifylyst.mintlify.site/mcp/setup/other-clients.md). |

## 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](https://codebeans-cb-notifylyst.mintlify.site/mcp/security.md#changes-need-your-confirmation). |
| "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:

```bash theme={"system"}
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](https://codebeans-cb-notifylyst.mintlify.site/mcp/reference/errors.md).

## 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](https://codebeans-cb-notifylyst.mintlify.site/mcp/reference/errors.md) — every refusal, with the exact message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.