Troubleshooting

Server crashes immediately with "Failed to spawn process: No such file or directory"

‍Cause: Claude Desktop cannot locate the npx binary. Either Node is not installed, or it was installed via nvm or Homebrew on a path Claude Desktop does not inherit. This happens before the connection is attempted, so the error is identical regardless of which endpoint URL you use.Fix:

1. Confirm Node is installed and resolves in a terminal: node -v (must be 20.18.1 or higher).
2. Get the absolute path to npx: which npx
3. In your Claude Desktop config, replace "command": "npx" with the full path, for example "command": "/Users/<you>/.nvm/versions/node/v22.22.3/bin/npx".
4. Fully quit Claude Desktop (Cmd+Q) and relaunch.

Server crashes on startup with "ReferenceError: File is not defined"

Cause: Node.js version is below 20.18.1. The mcp-remote package requires Node 20.18.1 or higher.

Fix:

Check your Node version:

node -v

If below 20.18.1, install Node 22 via nvm:

nvm install 22
nvm alias default 22

Get the absolute path to Node 22's npx:

which npx

Update your Claude Desktop config to use the absolute path instead of just "npx":

"command": "/Users/<you>/.nvm/versions/node/v22.22.3/bin/npx"

Claude Desktop doesn't inherit your shell's nvm environment, so a bare npx can resolve to the wrong Node version.

Clear the stale npx cache:

rm -rf ~/.npm/_npx

Optional cleanup: if you no longer need the old Node version, remove it (replace 18.20.8 with whatever version node -v showed). This is not required once the config uses the absolute path above.nvm uninstall 18.20.8

Replace 18.20.8 with whatever old version node -v showed.

Fully quit Claude Desktop (Cmd+Q) and relaunch.

Server crashes, log says "Node.js v18.x.x" at the bottom

Cause: Even after upgrading Node, the old version is still being resolved at runtime because it's first on PATH.

Fix: Uninstall the old version with nvm uninstall 18.20.8 (substitute the version you have). Then clear the npx cache with rm -rf ~/.npm/_npx and relaunch Claude Desktop.

Changes to the config don't seem to take effect

Cause: Closing the Claude Desktop window doesn't restart the app. The MCP server only re-reads its config on a full app restart.

Fix: On macOS, use Cmd+Q or Claude, then Quit Claude from the menu bar. On Windows, right-click the system tray icon and select Quit. Then reopen.

Server connects but no tools appear

This covers the case where no tools show up at all. If the tools appear but a tool call fails with a 403 error, see Authentication errors (401 or 403) below instead.

Possible causes:

• PAT missing scopes. Verify your token has the scopes for the tools you expect. See Authentication and PAT Setup.
• PAT expired or revoked. Generate a new one.
• Cached tool list. In Copilot Studio, re-save and republish the connector. In Claude Desktop, fully quit (Cmd+Q) and relaunch.

Authentication errors (401 or 403)

If the handshake and the tool list succeed but every tool call returns a 403, the cause is almost always one of these two:

Token created on the Directory Account. MCP tool calls expect a support domain account token. Create a new PAT from a support domain account and use that. (A Directory Account token can also work if you pass the target account in the X-Xurrent-Account header, but the recommended setup is a support domain account token.)

Sera AI not enabled. Enable it under Settings, Self Service Settings, Enable Sera AI, on the account the MCP server connects to.

If you still see 401 or 403 after checking both:

Verify the Authorization header value starts with "Bearer " (with a space).Verify the PAT is current. Log into Xurrent and check My Profile, then Personal Access Tokens.

Server connects then disconnects after about 30 seconds

Cause: Likely a network or proxy issue blocking the long-lived MCP connection.

Fix: Check whether your corporate VPN or proxy is interfering with the MCP endpoint. The MCP connection is long-lived; proxies that terminate idle connections after ~30 seconds will break it. If you are behind a corporate proxy, allowlist the relevant endpoint (mcp.xurrent.com, mcp.xurrent-demo.com, or mcp.xurrent.qa) and confirm long-lived HTTPS connections are not being dropped.

"Server transport closed unexpectedly" in the log

This is a generic message that the MCP server process exited. Look further up in the log for the actual error. Common causes:

• Node version mismatch (see above)
• Stale npx cache from a previous failed install. Clear with rm -rf ~/.npm/_npx
• PAT formatting issue (missing "Bearer " prefix, extra whitespace)

Rate limiting or "too many requests" errors

The Xurrent MCP server enforces rate limits to protect platform stability. Heavy use across many concurrent users may hit platform rate limits. If you hit limits regularly, contact your CSM to discuss your use case and expected volume.

Where to find logs

Claude Desktop (macOS):

~/Library/Logs/Claude/mcp-server-<your-server-key>.log

The filename matches the key you used in your config. For the QA setup (xurrent-mcp-qa), the file is mcp-server-xurrent-mcp-qa.log.

Claude Desktop (Windows):

%APPDATA%\Claude\logs\mcp-server-<your-server-key>.log

The filename matches the key you used in your config. For the QA setup (xurrent-mcp-qa), the file is mcp-server-xurrent-mcp-qa.log.

Before sharing logs

Scrub your Bearer token first. It appears in plaintext in the args of every log entry. Replace it with "Bearer REDACTED" before pasting into a ticket, Slack message, or doc.

Still stuck?

Contact your CSM or open a request in Xurrent. Include:

• Which MCP client (Claude Desktop, Copilot Studio, etc.) and version
• Your Xurrent environment (.com or .qa)
• The full error message from the log (with token scrubbed)
• What you've already tried

‍

‍