MCP Troubleshooting

This guide helps you resolve common issues when using Browserman with the Model Context Protocol (MCP).

Connection Issues

MCP Server Not Responding

Symptoms:

• AI assistant says "Cannot connect to Browserman MCP server"
• Timeout errors
• Tools not responding

Solutions:

1. Verify Server URL and API Key

   {
     "mcpServers": {
       "browserman": {
         "url": "https://mcp.browserman.run",
         "headers": {
           "X-API-Key": "YOUR_API_KEY_HERE"
         }
       }
     }
   }

   Ensure there are no typos or extra characters.

2. Check Internet Connection

   • Ensure you have a stable internet connection
   • Try accessing https://mcp.browserman.run in your browser

3. Restart Your MCP Client

   • Claude Code: No restart needed, changes take effect immediately
   • Cursor/Codex: Close and reopen the application
   • Claude Desktop: Completely close and reopen

Authentication Failures

Symptoms:

• "Authentication failed" errors
• "Invalid API key" messages
• 401 Unauthorized responses

Solutions:

1. Verify API Key Format

   The correct header is X-API-Key:

   {
     "mcpServers": {
       "browserman": {
         "url": "https://mcp.browserman.run",
         "headers": {
           "X-API-Key": "YOUR_API_KEY_HERE"
         }
       }
     }
   }

   • No "Bearer " prefix needed for X-API-Key
   • Check for extra spaces or newlines
   • Verify the key hasn't expired

2. Generate New API Key

   • Visit app.browserman.run
   • Click on API Keys in the left sidebar
   • Click + New Key
   • Generate new key
   • Update your configuration

Tool Execution Issues

"Account not found" Errors

Symptoms:

Error: Account 'account-name' not found for platform 'twitter'

Solutions:

1. List Available Accounts Ask your AI assistant: "Show me all my connected accounts"

2. Verify Account Name

   • Account names are case-sensitive
   • Check for typos or extra spaces
   • Use the exact name from your account list

3. Bind the Account

   • Visit app.browserman.run
   • Go to Accounts > Add Account
   • Follow the Account Binding Guide

Task Timeout Errors

Symptoms:

• "Task execution timeout" errors
• Long-running tasks never complete
• No response after several minutes

Solutions:

1. Increase Timeout Settings

   {
     "mcpServers": {
       "browserman": {
         "url": "https://mcp.browserman.run",
         "headers": {
           "X-API-Key": "YOUR_API_KEY"
         },
         "timeout": 300000
       }
     }
   }

   Note: Timeout is in milliseconds (300000 = 5 minutes)

2. Use Full Mode for Complex Tasks For tasks that need more processing time, specify preferredEngine: "full".

Configuration Issues

Can't Find Configuration File

Symptoms:

• AI assistant doesn't recognize Browserman tools
• Configuration changes don't take effect

Solutions:

1. Find the Correct Config File

   Claude Code (recommended):

   • Use CLI command: claude mcp add --transport http browserman https://mcp.browserman.run --header "X-API-Key: YOUR_KEY"
   • Verify with: claude mcp list

   Cursor:

   • macOS/Linux: ~/.cursor/mcp.json
   • Windows: %USERPROFILE%\.cursor\mcp.json

   Claude Desktop:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Validate JSON Syntax Use a JSON validator to check your configuration:

   {
     "mcpServers": {
       "browserman": {
         "url": "https://mcp.browserman.run",
         "headers": {
           "X-API-Key": "YOUR_API_KEY"
         }
       }
     }
   }

Changes Not Taking Effect

Solutions:

1. Restart Your Application

   • Claude Code: Changes take effect immediately, no restart needed
   • Cursor/Codex: Restart the application
   • Claude Desktop: Must restart after making changes

2. Check File Permissions Ensure the configuration file is readable

Getting Help

Before Contacting Support

1. Gather Information

   • Task ID of the failed task
   • Error messages (exact text)
   • Your configuration (without API key)
   • Steps to reproduce

2. Check Documentation

   • API Reference
   • MCP Configuration
   • Account Binding Guide

Contact Support

Console Support:

• Visit app.browserman.run
• Go to Support > Submit Ticket
• Include detailed information

Community:

• Check community forums through the console
• Share solutions and get help from other users

Common Error Codes

Code	Meaning	Solution
401	Unauthorized	Check API key
403	Forbidden	Check account permissions
404	Not Found	Verify account/task ID
429	Rate Limited	Wait and retry
500	Server Error	Retry or contact support

Client-Specific Issues

Claude Code

Issue: Command not found

• Solution: Install Claude Code: npm install -g @anthropic-ai/claude-code

Issue: MCP server not listed

• Solution: Verify with claude mcp list and re-add if needed

Cursor

Issue: MCP config not loading

• Solution: Ensure mcp.json is in the correct location and has valid JSON syntax

Claude Desktop

Issue: "mcp-remote" not found

• Solution: Install with npx mcp-remote or use Claude Code instead

Next Steps

• View MCP Configuration Guide
• Explore Usage Examples
• Read API Documentation