Technical troubleshooting

First step in every case: ask Claude to run ps_get_shop_info and ps_check_shop_health. Together they report versions, connector type (daily or service), read-only mode, enabled blocks, missing employee permissions and modules hooked into saves.

Connection

The connector doesn't connect from Claude.ai.

Check in this order:

1. The address is https://your-shop.com/module/tellmyshop/mcp with the full token. The endpoint refuses plain HTTP.
2. "Test connection" in the module works (test token, valid 2 minutes).
3. Nothing in front of the shop blocks POST to /module/tellmyshop/mcp: basic auth, maintenance page, WAF, Cloudflare Bot Fight Mode or managed challenges. Add a skip rule for that path only.
4. The master kill switch in the module is on.
5. The daily IP allowlist, if set, includes Anthropic's range (160.79.104.0/21).

403 Forbidden.

Likely causes:

• Origin. Requests with an Origin header are accepted only from claude.ai and claude.com. A browser-based test tool or a custom client with another Origin is refused.
• IP allowlist. The service token works only from listed IPs; the daily token too, if you set a daily list.
• IP lockout. 20 failed authentication attempts from one IP within 10 minutes lock that IP out. Typical cause: an old token still configured in Claude or in a monitoring script. Fix the token, then wait for the lockout to expire.

Authentication fails after a token was regenerated.

Only the hash and prefix of the current token are stored. A new token replaces the old one. Update the connector URL in Claude, or the Authorization: Bearer header in Claude Code / Claude Desktop config.

Claude Code or Claude Desktop (local) can't connect.

Use --header "Authorization: Bearer <token>" instead of a URL token. The endpoint needs HTTPS even locally (mkcert). Whether requests without an Origin header pass:.

Tools missing

Theme tools are missing.

Block 3 tools exist only on the service connector. Check: service token generated, service connector added in Claude as a separate connector, the request comes from an allowlisted IP, and block 3 is switched on. Through the daily connector they never appear.

Write tools are missing, only reads are visible.

READ_ONLY is on (the default after install). ToolRegistry::visible() hides every write tool while it is on. Turn read-only mode off. Once licensing ships (0.4.0), an inactive licence will have the same effect.

Blog tools are missing.

The 5 blog tools (ps_list_blog_posts, ps_get_blog_post, ps_list_blog_categories, ps_save_blog_post, ps_update_blog_category) are registered only when SmartBlog is detected. Other blog modules are not supported. ps_check_shop_health reports "no blog" as info.

Commerce tools are missing.

Block 2 is off by default. Switch it on; the tools appear on the daily connector.

A tool disappeared mid-conversation.

The block or group is checked on every call. Someone switched it off, or read-only mode was turned on.

Limits

Rate limit reached.

120 tool calls and 60 writes per hour per connector. ps_write_theme_file has its own 20 writes per hour. Split large batches across hours.

Batch refused with a limit error.

Per-call limits: ps_update_product_content 50, ps_update_category_content 20, ps_update_image_legends 100, ps_set_product_categories 200, ps_set_product_features 100, ps_update_prices 100, ps_update_stock 100. Full table: Specification §11.1.

Writes

change_token expired, used or mismatched.

The token is an HMAC of tool, arguments and a hash of the "before" state, valid 30 minutes, single use. Repeat with identical arguments, or make a new preview.

Execution blocked: data changed since the preview.

The "before" state hash no longer matches, for example because of a back-office edit, an import or a feed module. Make a new preview.

Price change refused.

ps_update_prices refuses price 0 and changes above 30% without allow_big_change. ps_manage_specific_prices requires allow_big_change above 90% reduction (warning above 50%). Claude should set the flag only after the merchant approved that size of change.

Cart rule created but not active / can't delete.

ps_manage_cart_rules creates rules inactive by design; use action=set_active. There is no delete action; deactivate instead, or delete in the back office. A rule without a code needs auto_apply.

Validation error on save.

ObjectWriter validates each field with the class rules (validateField, isCleanHtml, lengths). Product names can't contain <>;=#{} and are limited to 128 characters. The message names the field.

Another module doesn't react to Claude's change.

ObjectWriter calls update(), which fires actionObject<Class>Update* (and actionProductSave / actionProductUpdate for products). Modules that listen only to back-office form hooks won't see the change. ps_check_shop_health lists them.

Permission denied.

ExecutionContext::requirePermissions checks the connector employee per tab and action, for example AdminCartRules add/edit. ps_get_shop_info lists missing permissions.

URLs

URL change blocked.

ps_change_url refuses when the canonical redirect is 302 (Shop Parameters > Traffic & SEO, set 301), developer mode is on (_PS_MODE_DEV_), or a module overrides routes (UrlGuard; ps_check_shop_health names it). Undo a URL change with a new ps_change_url, not ps_revert_change.

Theme and cache

Change not visible after a theme write.

Run ps_clear_cache (block 3, scope smarty; all also clears Symfony cache). Purge full-page cache modules and CDN cache separately.

Smarty validation error.

Only whitelisted tags and modifiers are allowed, then a test compile; {php}, {include_php} and static class access are refused. Nothing was saved.

"search must appear exactly once".

Use a longer fragment or write the whole file with content.

Restore a broken template.

ps_list_file_backups, then ps_restore_file_backup (backs up the current version first), then ps_clear_cache.

Known issues in 0.3.0

Report a problem

Send to support@tellmyshop.pl: domain, PrestaShop and PHP versions, module version (0.3.0), connector type, tool name, exact error text, time. Send only the token prefix, never the full token.

---

PrestaShop is a registered trademark of PrestaShop SA. Claude is a trademark of Anthropic. TellMyShop is not affiliated with either.