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. No apologies 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. Nobody can 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. The permission requirements can't be lowered — that's FluentCart's design decision.

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, the server strips 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 The 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." Every list tool supports 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 design choice.
   • 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." The currency format is documented in every tool description so the AI knows to convert, but occasionally it shows the raw value.

Some things break because of upstream FluentCart issues, not the MCP server. They're documented here so you don't file a bug report that can't be fixed from the MCP side.

Attribute Term Creation — POST /options/attr/group/:id/term returns "Information mismatch". FluentCart queries the wrong table when validating. Create terms via the admin UI instead.

Variant Listing Without Product ID — Calling variant_list without a product_id crashes the server. Use product_pricing_get to list variants for a specific product instead.

Price 100x Multiplier — FluentCart's Helper::toCent() multiplies by 100 again internally. When passing prices via MCP, pass them in cents (e.g. 4999 for $49.99) — the API handles the rest. If prices look 100x too large, this is why.

Some Report Endpoints Missing — A handful of report endpoints (cart-report, order-value-distribution, sales-report, license-chart, license-pie-chart) aren't registered in FluentCart 1.3.9. The tools exist in MCP for forward compatibility, but they'll return errors on older FluentCart versions. Use the alternative report tools mentioned in each tool's description.

Customer Address Select — The customer_address_select endpoint is scoped to frontend sessions (cookie auth), not the REST API. Use customer_addresses to get all addresses and filter client-side.

For the full list of 14 documented upstream bugs, check the GitHub repository.