Skip to main content

Troubleshooting

Common issues when connecting Pulse MCP to Cursor, Claude Desktop, or other MCP clients.

Tool Not Found​

Symptoms​

  • Assistant reports a tool such as list_app_vitals_crash_issues does not exist
  • tools/list shows only five tools

Solution​

Domain tools are not registered at startup. The assistant must call register_tools first with the correct category:

{ "categories": ["crashes"] }

Then retry the domain tool. See the tool categories table in Overview.

Authentication Failed (401)​

Symptoms​

  • MCP server exits on startup with Failed to exchange API key
  • Tool calls return unauthorized errors

Solution​

  1. Confirm PULSE_API_KEY is a personal MCP token (pulse_mcp_…), not the project SDK key from Settings → SDK Configuration.
  2. Create a new token at Profile menu → Personal Access Tokens if the key was revoked or copied incorrectly.
  3. Confirm PULSE_BASE_URL has no trailing slash and points to your Pulse API (for example https://pulse-server.pulse-ux.com).
  4. Keep PULSE_API_KEY in the MCP client env — the server re-exchanges it automatically on token expiry.

Permission Denied (403)​

Symptoms​

  • Tools return HTTP 403, often on crash lists, metrics, or heatmap data
  • Message mentions missing permission or forbidden access

Solution​

  1. Confirm your Pulse user has view access to the target project.
  2. Check team role under Settings → Team — Viewer and Member roles can query data; confirm you have access to the target project.
  3. For heatmaps, verify heatmap capture is enabled in the active SDK config — call register_tools with categories: ["sdk"] and inspect get_active_sdk_config.

Node Version Error​

Symptoms​

  • npx fails or MCP server refuses to start
  • Engine mismatch warnings for Node

Solution​

Pulse MCP requires Node.js 18+. Upgrade Node on the machine where the MCP client runs the server subprocess:

node --version

Use nvm or your system package manager if the version is below 18.

Session Listing Timeout​

Symptoms​

  • list_session_replays hangs or returns a timeout message
  • Error suggests narrowing the time range

Solution​

  1. Provide both startTime and endTime together, or omit both for the default last-seven-days window.
  2. Narrow the time range — large windows with high pageSize can be slow.
  3. Reduce pageSize (maximum 100).

Wrong API Key Type​

Symptoms​

  • Exchange succeeds but tools return empty or unexpected data
  • SDK initialization key was reused for MCP

Solution​

Key typeCreated inUsed for
Project SDK keySettings → SDK ConfigurationMobile SDK initialize()
Personal MCP tokenProfile menu → Personal Access TokensCursor, Claude Desktop, Pulse MCP

Create a personal token and update the PULSE_API_KEY env var in your MCP client config.

Still Having Issues?​

If you are still blocked:

  1. Re-check your Cursor or Claude config and confirm the server shows as connected
  2. Revoke and recreate the personal access token
  3. Contact Pulse support at support@pulse-ux.com

Next Steps​

  • Setup — Full installation and client configuration
  • Team and Settings — Tokens, roles, and project access