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:
SMSFABRIC_API_KEY=sf_test_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx npx -y @smsfabric/mcp-serverA working server prints smsfabric-mcp: connected (https://api.smsfabric.com) and waits. Stop it with Ctrl+C.
The server does not start
Section titled “The server does not start”| 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. |
The tools don’t appear
Section titled “The tools don’t appear”- 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
serversas the top-level key; the other clients usemcpServers. - 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.
A tool call fails
Section titled “A tool call fails”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.
Messages stay queued
Section titled “Messages stay queued”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.