Troubleshooting

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

Remove the old Node version (or at minimum make sure Node 22 is first on PATH):

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

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)

• 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.
• For Copilot Studio: try regenerating the PAT with scopes in a different order.

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 mcp.xurrent.com. [TODO: link to network requirements doc if one exists.]

"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 the WAF or ALB rate limit. [TODO: document the exact rate limits.]

If you hit limits regularly, contact your CSM to discuss your use case.

Where to find logs

Claude Desktop (macOS):

~/Library/Logs/Claude/mcp-server-xurrent-mcp.log

Claude Desktop (Windows):

%APPDATA%\Claude\logs\mcp-server-xurrent-mcp.log

Copilot Studio: Tool call traces are available in the Copilot Studio agent's run history. [TODO: link to MS docs on viewing agent runs.]

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

‍

‍