Troubleshooting

What you see: Claude Desktop has no hammer icon. Cursor shows a red dot. The AI says it can't find any FluentCart tools.

What's actually wrong (in order of likelihood):

1. Node.js missing or too old

   node --version

   The MCP server needs v22.0.0 or higher. If you don't have Node at all, get it from nodejs.org. If you have an older version, upgrade. I won't apologise for requiring modern JavaScript.

2. npx not found It comes with Node.js. If which npx returns nothing, your Node installation is broken. Reinstall.

3. JSON syntax error The number one cause of "it just doesn't work." A trailing comma, a missing quote, a rogue bracket. Paste your config into jsonlint.com and see what it says. I can't debug your JSON for you.

4. Wrong config file location

   • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
   • Cursor: Check Settings → MCP for the path

5. Didn't restart the app Claude Desktop, Cursor, and VS Code don't hot-reload MCP configs. Close the app completely (not just the window — quit it) and reopen.

What you see: Errors about "authentication failed", "invalid credentials", or HTTP 401.

What's actually wrong:

1. Wrong Application Password The password has spaces between groups: aBcD eFgH iJkL mNoP. Include the spaces. It's case-sensitive. Copy it exactly.

2. Wrong username Use the WordPress login name, not the display name. If your display name is "John Smith" but your login is "john", use john. Check Users → Profile in WordPress admin.

3. Application Passwords disabled Security plugins love disabling things. Wordfence, iThemes Security, Solid Security — any of them might have turned off Application Passwords. Check your security plugin settings.

   Some managed hosts (WP Engine, Kinsta, etc.) also disable them by default. Check with your host.

4. HTTP instead of HTTPS WordPress blocks Application Passwords over plain HTTP. If you're on a local dev site, add this to wp-config.php:

   define('WP_ENVIRONMENT_TYPE', 'local');

5. Password was deleted or regenerated If you made a new Application Password in WordPress, update it in your MCP config and restart the client. The old one is dead.

What you see: "permission denied", "forbidden", HTTP 403.

What's wrong: Your WordPress user isn't an Administrator.

Fix: Go to Users in WordPress admin and check the role. FluentCart's REST API needs admin capabilities for nearly everything. Using an Editor or Subscriber account won't work. I can't lower the permission requirements — that's FluentCart's decision, not mine.

What you see: "not found", "route not found", HTTP 404.

What's actually wrong:

1. FluentCart not installed Check Plugins in WordPress admin. FluentCart must be installed and activated. The MCP server talks to FluentCart endpoints — if FluentCart isn't there, those endpoints don't exist.

2. Wrong URL The URL should be the root of your WordPress site:

   • Correct: https://shop.example.com
   • Wrong: https://shop.example.com/wp-admin/
   • Wrong: https://shop.example.com/wp-json/
   • Wrong: https://shop.example.com/ (trailing slash is technically fine, I strip it)

3. Permalinks set to "Plain" WordPress REST API needs pretty permalinks. Go to Settings → Permalinks and pick literally anything except "Plain". Hit Save even if you don't change anything — this flushes rewrite rules.

4. REST API blocked Security plugins and .htaccess rules sometimes block /wp-json/. Check your security plugin settings and server config.

What you see: Requests die after 30 seconds. "timeout", "aborted", "ETIMEDOUT".

What to do:

1. Increase the timeout My default is 30 seconds. If your server is slow, bump it up via the FLUENTCART_TIMEOUT env var (milliseconds):

   "env": {
     "FLUENTCART_URL": "https://your-store.com",
     "FLUENTCART_USERNAME": "admin",
     "FLUENTCART_APP_PASSWORD": "...",
     "FLUENTCART_TIMEOUT": "60000"
   }

2. Check your server Run curl https://your-store.com/wp-json/. If curl also hangs, that's a network or server problem. Not something the MCP server can fix.

3. Ask for less data Listing 10,000 orders in one request will be slow on any server. Use pagination — "Show me the last 10 orders" instead of "Show me all orders." I designed every list tool to support per_page and page parameters for exactly this reason.

What you see: The AI doesn't mention FluentCart. It says it can't access your store. It just... doesn't use the tools.

What's happening:

1. Server not connected Verify the connection:

   • Claude Desktop: Settings → Developer — is fluentcart green?
   • Cursor: Settings → MCP — green dot = connected
   • Claude Code: claude mcp list

2. Too many MCP servers Some clients choke when you have 15 MCP servers connected. Try disabling the ones you're not using right now.

3. Wrong mode

   • VS Code Copilot: You must be in Agent mode. Regular Chat won't use MCP tools. That's Microsoft's restriction, not mine.
   • Some clients have "tool use" toggles — make sure it's on.

4. The AI just needs a nudge Sometimes the AI doesn't realise it has FluentCart tools until you mention them explicitly: "Use the FluentCart tools to show me my recent orders." After the first use, it remembers.

What you see: UNABLE_TO_VERIFY_LEAF_SIGNATURE, certificate chain errors, SSL handshake failures.

What to do:

1. Self-signed certs (local dev) If your local WordPress has a self-signed cert, add this env var:

   "env": {
     "NODE_TLS_REJECT_UNAUTHORIZED": "0"
   }

   Local Development Only

   Do not use this in production. It disables all SSL verification. You know this, but I'm contractually obligated to say it.

2. Cloudflare issues If you're behind Cloudflare with "Full (strict)" SSL, your origin server needs a valid cert. "Full" (without strict) is more forgiving.

What you see: A $49.99 product shows as 4999. Totals are 100x too large.

That's correct. FluentCart stores money in the smallest currency unit — cents, pence, grosze. 4999 = $49.99. 10000 = €100.00. 4000 = 40.00 PLN.

The AI usually converts these for you. If it doesn't, tell it: "Show prices in dollars, not cents." I documented the currency format in every tool description so the AI knows to convert, but occasionally it shows the raw value.