Skip to content

MCP troubleshooting

Start with the server’s own output. It writes diagnostics to stderr, which clients show in their MCP logs: Claude Code with claude mcp list or /mcp, Claude Desktop in its logs folder (Settings → Developer → Open Logs Folder), Cursor and VS Code in their MCP output panel.

You can also run the server by hand to see what happens:

Terminal window
SMSFABRIC_API_KEY=sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx npx -y @smsfabric/mcp-server

A working server prints smsfabric-mcp: connected (https://api.smsfabric.com) and waits. Stop it with Ctrl+C.

Message or symptom Cause Fix
smsfabric-mcp: set SMSFABRIC_API_KEY (sf_live_… or sf_test_…) The key is not in the server’s environment. Add SMSFABRIC_API_KEY to the env block of the client configuration. A key exported in your shell does not reach an app started from the dock or Start menu.
spawn npx ENOENT, or command not found: npx The client can’t find Node.js. Apps started from a desktop often have a shorter PATH than your terminal. Install Node.js 20 or newer. Then use the full path to npx as the command (find it with which npx, or where npx on Windows).
The server starts on macOS or Linux but not on Windows Some clients can’t run npx.cmd directly. Use the command cmd with the arguments /c, npx, -y, @smsfabric/mcp-server.
SyntaxError or Unsupported engine at start Node.js is older than 20. Run node --version and upgrade.
Nothing happens and the client times out The first npx run is still downloading the package, or a proxy blocks npm. Run the command above once in a terminal to fill the cache, then restart the client.
  • Restart the client completely after you edit its configuration. Claude Desktop must be quit, not just closed.
  • Check the JSON: a trailing comma or a missing brace makes most clients ignore the whole file. VS Code uses servers as the top-level key; the other clients use mcpServers.
  • Check that the server is enabled in the client’s MCP settings, and in VS Code that its tools are selected in the agent mode tool list.

Tool errors read SMSFabric error <status> (<code>): <detail>. The common ones:

Error Meaning Fix
401 (unauthorized) The key is wrong, expired or revoked. Copy the key again from the portal, or create a new one.
403 (forbidden) The key lacks the scope this tool needs. Add the scope listed in Tools, or use a key made for this use case.
400 (validation_failed) An input is invalid, often a number that is not E.164. The field errors follow on the next line. Ask the assistant to fix the input, for example +201001234567.
403 (verify_country_not_allowed) Verify is not enabled for the number’s country. Allow the country under Verify settings in the portal.
429 (verify_resend_limited) 3 codes were sent to this number in the last 10 minutes. Wait the time given in Retry after <n> s., or use the code already sent.
409 (invalid_campaign_state) The campaign is not in a state that allows this action, for example starting a running campaign. Ask for the campaign’s status with get_campaign.
422 (campaign_audience_empty) No contact matches the campaign’s groups and tags. Check the groups and tags with find_contacts.
SMSFabric network error (network_error): … The server could not reach the API. The end of the line names the cause, such as ECONNREFUSED (nothing listens at that address), ENOTFOUND (DNS), a certificate error or timed out after 30000 ms. Check the network and any proxy. If you set SMSFABRIC_BASE_URL, check its value; an empty value is ignored and the default API is used.

The full list of codes is in Error codes.

send_sms succeeds when SMSFabric accepts the message; a phone still has to send it. If messages stay queued, ask the assistant to run list_devices: a phone that is offline or disabled can’t take work. See Gateway phone troubleshooting.