MCP Troubleshooting

Common Issues

Here are solutions to the most common MCP server problems.

"MCP server not recognized" or "Command not found"

Cause: Node.js isn't installed or isn't in your PATH.

Solution:

1. Check Node.js is installed: node --version (should be 18+)
2. If not installed, download from nodejs.org
3. Restart your AI tool after installing

"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

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 multisite-cms-mcp@latest --version

If you're using an old version, the @latest in your config ensures you get updates on restart.

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 multisite-cms-mcp@latest

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"
• "args": ["-y", "multisite-cms-mcp@latest"]
• "env": { "FASTMODE_API_URL": "https://api.fastmode.ai" }

Correct Configuration

{
  "mcpServers": {
    "fastmode": {
      "command": "npx",
      "args": ["-y", "multisite-cms-mcp@latest"],
      "env": {
        "FASTMODE_API_URL": "https://api.fastmode.ai"
      }
    }
  }
}

Getting Help

If you're still stuck:

• Email: [email protected]
• Include: Your OS, AI tool name/version, and the error message

Related Docs

• MCP Server Setup — Installation instructions
• Using the MCP Server — How to prompt effectively
• Common Issues — General troubleshooting