Docs / Troubleshooting / MCP Troubleshooting
Back to FastMode

MCP Troubleshooting

Common Issues

Here are solutions to the most common MCP server problems.

"MCP server not recognized" or "npx: command not found"

Cause: Node.js or npx isn't in your system PATH. This is common when using nvm, volta, or homebrew to install Node.js, or when your IDE doesn't load your shell's PATH (like Antigravity IDE).

Quick Fix:

  1. Check Node.js is installed: node --version (should be 18+)
  2. Check npx is available: which npx
  3. If not found, try the alternative installation methods below

Alternative Installation Methods:

If npx doesn't work, use one of these methods:

Option 1: Shell Wrapper (Recommended)

This method loads your shell's PATH and works with any Node.js installation:

# macOS/Linux
{
  "mcpServers": {
    "fastmode": {
      "command": "/bin/zsh",
      "args": ["-l", "-c", "npx -y fastmode-mcp"]
    }
  }
}

# Windows
{
  "mcpServers": {
    "fastmode": {
      "command": "cmd",
      "args": ["/c", "npx -y fastmode-mcp"]
    }
  }
}

Option 2: Global Install with Full Path

# Install globally
npm install -g fastmode-mcp

# Find the path
which fastmode-mcp

# Use the full path in your config
{
  "mcpServers": {
    "fastmode": {
      "command": "/path/from/which/command/fastmode-mcp"
    }
  }
}

Option 3: Use Absolute npx Path

Find your npx path and use it directly:

# Find npx location
which npx

# Use in config (example for nvm):
{
  "mcpServers": {
    "fastmode": {
      "command": "/Users/yourname/.nvm/versions/node/v20.10.0/bin/npx",
      "args": ["-y", "fastmode-mcp"]
    }
  }
}

See MCP Server Setup for more detailed installation instructions.

"Authentication failed" or "Unauthorized"

Cause: Your credentials have expired or were never saved.

Solution:

  1. Delete the credentials file: rm ~/.fastmode/credentials.json
  2. Ask your AI to list projects again
  3. Complete the browser authentication flow

Browser Doesn't Open for Authentication

Cause: The MCP server can't open your default browser.

Solution:

  1. Look in your AI tool's output for the URL and code
  2. Manually open https://app.fastmode.ai/device
  3. Enter the code shown in your AI tool

"Connection timeout" or "Network error"

Cause: Can't reach the Fast Mode API.

Solution:

  1. Check your internet connection
  2. Make sure api.fastmode.ai isn't blocked by firewall
  3. Try again in a few minutes (might be temporary)

AI Doesn't Seem to Use the MCP Server

Cause: The server isn't properly configured or loaded.

Solution:

  1. Check your MCP configuration is valid JSON
  2. Restart your AI tool completely (quit and reopen)
  3. Explicitly ask: "Use the Fast Mode MCP server to list my projects"
  4. Check the MCP server list in your AI tool's settings

"Project not found"

Cause: The project name doesn't match or you don't have access.

Solution:

  1. Ask "What Fast Mode projects do I have?" to see exact names
  2. Use the project ID instead of the name
  3. Check you're logged into the right Fast Mode account

MCP Server Starts But Tools Don't Work

Cause: The server may have started but authentication is failing silently.

Solution:

  1. Delete credentials: rm ~/.fastmode/credentials.json
  2. Run the MCP manually to see output: npx fastmode-mcp
  3. Look for authentication prompts in the output
  4. Restart your AI tool

IDE-Specific Issues

Antigravity IDE

Antigravity IDE requires the shell wrapper method because it doesn't load your shell's PATH.

Config file location: ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "fastmode": {
      "command": "/bin/zsh",
      "args": ["-l", "-c", "npx -y fastmode-mcp"]
    }
  }
}

Cursor / Claude Code / Windsurf

These IDEs usually work with the standard npx config. If not, try the shell wrapper method above.

Platform-Specific Issues

macOS

  • Homebrew Node.js: Path is usually /opt/homebrew/bin/npx (Apple Silicon) or /usr/local/bin/npx (Intel)
  • nvm: Path is ~/.nvm/versions/node/vX.X.X/bin/npx

Windows

  • Use npx.cmd instead of npx in some cases
  • Paths should use backslashes or escaped forward slashes
  • Example: "command": "C:\\Program Files\\nodejs\\npx.cmd"

Linux

  • Check with which npx and which node
  • Common paths: /usr/bin/npx or /usr/local/bin/npx

Finding Your Config File

Different IDEs store MCP configuration in different locations:

IDEConfig File Location
Claude Code~/.claude/settings.json
Cursor~/.cursor/mcp.json
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json
Windsurf~/.codeium/windsurf/mcp_config.json
Antigravity~/.gemini/antigravity/mcp_config.json

How to Reset Authentication

If you're having persistent auth issues:

# Delete saved credentials
rm ~/.fastmode/credentials.json

# Then ask your AI to authenticate again
"List my Fast Mode projects"

How to Check MCP Server Version

Run this in your terminal:

npx fastmode-mcp --version

How to View Device Sessions

To see all devices authorized to access your account:

  1. Go to app.fastmode.ai
  2. Navigate to Account → Security
  3. View and revoke any device sessions

Debug Mode

To see detailed logs, you can run the MCP server manually:

npx fastmode-mcp

This will show all incoming requests and responses, helpful for diagnosing issues.

Configuration Checklist

Make sure your configuration includes:

  • Valid JSON syntax (no trailing commas)
  • "command": "npx" (or shell wrapper / full path if npx isn't in PATH)
  • "args": ["-y", "fastmode-mcp"] (when using npx)

Standard Configuration

{
  "mcpServers": {
    "fastmode": {
      "command": "npx",
      "args": ["-y", "fastmode-mcp"]
    }
  }
}

Getting Help

If you're still stuck:

Related Docs

Built in Fast Mode