Troubleshooting

Start at the first stage that fails. A green client indicator confirms only that client’s local configuration; returned store data is the useful proof.

1. Credential setup failed

Run the setup wizard again before changing client configuration:

npx -y fluentcart-mcp setup

It needs the WordPress site root, login name, and Application Password. The URL must not include /wp-admin/ or /wp-json/. WordPress shows an Application Password once; if it was lost, create a new one rather than trying to recover it from the ether.

2. The client cannot start the server

Local npx clients need Node.js 24 or newer:

node --version

If npx cannot be found, use which npx on macOS/Linux or where npx on Windows, then configure the returned absolute path. Windows JSON needs doubled backslashes or forward slashes. Claude Desktop MCPB users do not need a separate Node installation because Claude Desktop supplies it.

For a JSON configuration file, validate locally instead of uploading credentials to a website:

python3 -m json.tool ~/.cursor/mcp.json >/dev/null

Check the client’s actual file location: ChatGPT Desktop, Codex CLI, and Codex IDE extension share ~/.codex/config.toml; Cursor uses its global mcp.json; VS Code uses workspace .vscode/mcp.json or the user MCP configuration. Restart or reload the client after changing its command.

3. The store connection or startup discovery failed

The server reads the FluentCart REST index before it registers tools. An unreachable site, blocked /wp-json/, bad URL, or unavailable FluentCart route therefore stops startup instead of creating a server that fails later on every call.

An optional advanced check prompts for the Application Password instead of putting it in shell history or documentation:

curl --user "fluentcart-reader" https://your-store.com/wp-json/fluent-cart/v2/app/init

curl prompts for the password. JSON with store data means connection and authentication work; 401 means the username or Application Password is wrong, 403 means a missing FluentCart permission, 404 usually means the URL or FluentCart installation is wrong, and a refused connection is a network or server problem.

4. WordPress authentication returned 401

Use the WordPress login name, not the display name. Copy the Application Password exactly, including its spaces. Check that Application Passwords have not been disabled by a security plugin or host policy. Regenerating one invalidates the previous value, so update the credential source and restart the MCP process after rotation.

WordPress normally requires HTTPS for Application Passwords. For a legitimate local development site, configure WordPress as local rather than weakening a production connection.

5. WordPress permission returned 403

The server inherits the configured WordPress user’s FluentCart permissions. A narrow role that can read reports but not customer records is valid; a 403 for the latter is expected. If every tool returns 403, give the user the required FluentCart capability. This is separate from FLUENTCART_WRITE_MODE: a WordPress role cannot enable a write that product policy omits.

6. FluentCart returned 404

Confirm FluentCart is installed and active, use the site root as FLUENTCART_URL, and set WordPress permalinks to anything except Plain. Security plugins or server rules can also block /wp-json/. Older FluentCart builds can legitimately lack a route; startup discovery removes its dependent tool instead of advertising a broken call.

7. The expected tool is missing

The tool list is filtered before registration by write policy, the connected WordPress principal, and the store’s discovered routes. With FLUENTCART_WRITE_MODE=disabled, writes cannot be listed, searched, described, or called. reversible adds only reviewed reversible creates and updates.

Refunds, subscription cancellation, deletion, bulk actions, order-status changes, marking an order paid, dispute handling, role changes, integration credentials, uploads, email, and login actions are absent in every mode. A missing unsupported action is not a hidden checkbox. See the tool guide for the exact boundary.

8. The private HTTP endpoint returned 401

This is the MCP bearer key, not WordPress authentication. The private endpoint needs Authorization: Bearer <key> matching FLUENTCART_MCP_API_KEY. Missing, malformed, and incorrect keys intentionally produce the same {"error":"Unauthorized"} response.

If the container refuses to start, confirm the retained key is at least 32 characters and that both FLUENTCART_MCP_ALLOWED_HOSTS and FLUENTCART_MCP_ALLOWED_ORIGINS name the public hostname. The private profile checks those values before listening. See private HTTP deployment.

9. The response is too large or times out

RESPONSE_TOO_LARGE means the server refused to return a payload that would be quietly truncated. Ask for a smaller date range, a known ID, fewer fields, or the specific tool’s documented limit. Do not assume every list schema supports the same page or per_page parameters; inspect the tool’s schema first.

For timeouts, first check whether the WordPress site responds at all:

curl https://your-store.com/wp-json/

If the site is slow, increase FLUENTCART_TIMEOUT within the supported configuration range and narrow the request. Ten thousand orders is not a debugging strategy.

10. Certificate verification failed

Use a valid TLS certificate or a trusted local CA first. For Cloudflare, use a valid origin certificate and Full (strict) where appropriate. Repair the certificate chain rather than making certificate verification someone else’s problem.

NODE_TLS_REJECT_UNAUTHORIZED=0 is only a final temporary local diagnostic after those checks. If you use it to isolate a local CA issue, remove it immediately after the test and restore normal verification before connecting to any non-local store. Restart the affected MCP server or client after removing the bypass so the restored setting takes effect. Never leave it in a deployment environment.

11. The AI does not use FluentCart tools

Confirm the server is enabled in the selected client, start a new chat where required, and ask a specific question such as Show me the FluentCart dashboard stats. Disable unrelated MCP servers temporarily if the client has per-server or per-tool controls. A client can be connected yet still need an explicit request to use the FluentCart tools.

12. Prices look 100 times too large

FluentCart stores money in the smallest currency unit. 4999 means $49.99; raw values are not a new economic theory. Ask the client to format prices in the store currency.

13. An upstream FluentCart issue is involved

Attribute-term creation can return Information mismatch; use the FluentCart admin until upstream fixes it. Variant listing without a product ID can fail; use product pricing for a specific product. Some older stores omit report routes, which startup discovery removes. Customer address selection is frontend-session scoped; use the read-only customer-addresses route instead.

Still stuck?

Check GitHub Issues, then open an issue with the error message, Node.js version, AI client, and steps tried. Redact URLs, bearer keys, Application Passwords, cookies, and customer data. Nobody needs a credential-shaped souvenir.