Skip to main content
This guide covers common issues you might encounter when using add-mcp and how to resolve them.

​
Common Issues

Symptoms:
  • MCP server appears in config file but doesn’t work
  • Agent doesn’t recognize the installed server
  • No error messages shown
Solutions:
  1. Verify the server URL/package is correct 
    # For remote servers, test the URL is accessible
curl -I https://mcp.example.com/mcp

# For npm packages, verify the package exists
npm view @modelcontextprotocol/server-postgres
  2. Check configuration file syntax
    • Locate your agent’s config file:
      • Cursor: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
      • VS Code: .vscode/mcp.json (project) or ~/Library/Application Support/Code/User/mcp.json (global)
      • Claude Code: .mcp.json (project) or ~/.claude.json (global)
      • OpenCode: opencode.json (project) or ~/.config/opencode/opencode.json (global)
    • Validate JSON/YAML/TOML syntax using a validator
    • Ensure no trailing commas or formatting errors
  3. Verify server name doesn’t conflict
    • Check if a server with the same name already exists
    • Running add-mcp again will overwrite the existing configuration
    • Use --name flag to specify a different name: 
      npx add-mcp @modelcontextprotocol/server-postgres --name my-postgres
  4. Restart your coding agent
    • Most agents need to be restarted to pick up config changes
    • For VS Code/Cursor: Reload window (Cmd/Ctrl + Shift + P → “Reload Window”)
    • For Claude Desktop: Completely quit and restart the application
Symptoms:
  • Error: EACCES: permission denied
  • Error: EPERM: operation not permitted
  • Installation fails when writing config files
Solutions:
  1. Check write permissions on config directory 
    # For project installations
ls -la .cursor/ .vscode/ .mcp.json

# For global installations
ls -la ~/.cursor/ ~/.config/opencode/ ~/Library/Application\ Support/Code/
  2. Fix directory permissions 
    # Make config directory writable
chmod u+w ~/.cursor/

# Or for project directory
chmod u+w .cursor/
  3. Avoid using sudo
    • Don’t run add-mcp with sudo unless absolutely necessary
    • If you used sudo previously, fix ownership: 
      sudo chown -R $USER:$USER ~/.cursor/
  4. Try project-level installation instead 
    # Install to project directory (default)
npx add-mcp https://mcp.example.com/mcp
Symptoms:
  • Error: “The following agents don’t support [transport] transport”
  • Installation blocked for specific agents
Solutions:
  1. Check agent transport compatibility
    • Claude Desktop: Only supports stdio (local servers via config)
      • Use the app’s Settings → Connectors for remote servers
    • All other agents: Support stdio, http, and sse
  2. Use correct transport for remote servers 
    # Default HTTP transport (recommended)
npx add-mcp https://mcp.example.com/mcp

# Use SSE if server requires it
npx add-mcp https://mcp.example.com/sse --transport sse
  3. Skip incompatible agents with —all flag
    • When using --all, incompatible agents are automatically skipped
    • You’ll see a warning message but installation continues
    npx add-mcp https://mcp.example.com/mcp --all
# Warning: Skipping agents that don't support http transport: Claude Desktop
  4. Install local servers to all agents 
    # Local/stdio servers work with all agents
npx add-mcp @modelcontextprotocol/server-postgres --all
Symptoms:
  • Error: “Invalid —header value(s)”
  • Installation fails with custom headers
Solutions:
  1. Use correct header format 
    # Correct: "Key: Value"
npx add-mcp https://mcp.example.com/mcp --header "Authorization: Bearer TOKEN"

# Wrong: missing colon or space
npx add-mcp https://mcp.example.com/mcp --header "Authorization=Bearer TOKEN"
  2. Add multiple headers 
    npx add-mcp https://mcp.example.com/mcp \
  --header "Authorization: Bearer TOKEN" \
  --header "X-Custom-Header: value"
  3. Use environment variables in headers 
    npx add-mcp https://mcp.example.com/mcp \
  --header "Authorization: Bearer $API_KEY"
  4. Headers only work with remote servers
    • If you specify --header with a local package, you’ll see a warning
    • Headers are ignored for stdio servers
Symptoms:
  • add-mcp doesn’t detect your installed agent
  • Prompts to select from all agents instead of showing detected ones
Solutions:
  1. Check agent detection paths 
    # For project detection, ensure these exist:
ls -la .cursor/ .vscode/ .mcp.json opencode.json .codex/ .gemini/ .zed/

# For global detection (with -g flag):
ls -la ~/.cursor/ ~/.config/opencode/ ~/Library/Application\ Support/Claude/
  2. Use explicit agent flag 
    # Specify the agent directly
npx add-mcp https://mcp.example.com/mcp -a cursor

# Multiple agents
npx add-mcp https://mcp.example.com/mcp -a cursor -a vscode
  3. Create project config directory 
    # Create the directory to enable project detection
mkdir -p .cursor

# Then run add-mcp
npx add-mcp https://mcp.example.com/mcp
  4. Use —all flag to install everywhere 
    # Install to all project-capable agents (default)
npx add-mcp https://mcp.example.com/mcp --all

# Install to all agents globally
npx add-mcp https://mcp.example.com/mcp --all -g
Symptoms:
  • Agent shows JSON/YAML/TOML parsing errors
  • Config file appears corrupted after installation
  • Existing servers stop working
Solutions:
  1. Validate config file format 
    # For JSON files (Cursor, VS Code, Claude Code, etc.)
cat ~/.cursor/mcp.json | jq .

# For YAML files (Goose)
cat ~/.config/goose/config.yaml | yq .

# For TOML files (Codex)
cat ~/.codex/config.toml | toml-test
  2. Back up config before installation 
    # Backup existing config
cp ~/.cursor/mcp.json ~/.cursor/mcp.json.backup

# Run installation
npx add-mcp https://mcp.example.com/mcp -a cursor

# Restore if needed
cp ~/.cursor/mcp.json.backup ~/.cursor/mcp.json
  3. Reinstall if config is corrupted
    • Delete the corrupted config file
    • Run add-mcp again to recreate it
    rm ~/.cursor/mcp.json
npx add-mcp https://mcp.example.com/mcp -a cursor
  4. Check for special characters
    • Ensure server URLs don’t contain unescaped special characters
    • Use proper JSON string escaping

​
Verification Steps

After installation, verify everything is working:

​
1. Check Configuration File

# View the installed server config
cat .cursor/mcp.json
# or
cat ~/.cursor/mcp.json
Look for your server name in the mcpServers section: 
{
  "mcpServers": {
    "your-server-name": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

​
2. Restart Your Agent

  • VS Code/Cursor: Cmd/Ctrl + Shift + P → “Reload Window”
  • Claude Desktop: Quit and restart the application
  • OpenCode: Restart the CLI session

​
3. Verify Server Connection

  • Check your agent’s MCP server status UI
  • For Cursor: Look for MCP server indicator in status bar
  • For VS Code: Check Output panel → MCP Servers
  • Test a tool from the server to ensure it’s working

​
Debugging Tips

Check your agent’s logs for detailed error messages:
  • VS Code: Help → Toggle Developer Tools → Console tab
  • Cursor: View → Output → Select “MCP” from dropdown
  • Claude Desktop: View logs at ~/Library/Logs/Claude/
Look for errors related to:
  • Server connection failures
  • Transport protocol issues
  • Authentication/header problems
For remote servers, test the endpoint:
# Test HTTP endpoint
curl -v https://mcp.example.com/mcp

# Test with custom headers
curl -v -H "Authorization: Bearer TOKEN" https://mcp.example.com/mcp

# Check SSE endpoint
curl -v -H "Accept: text/event-stream" https://mcp.example.com/sse
For local stdio servers:
# Test package can be installed
npx -y @modelcontextprotocol/server-postgres --help

# Check package version
npm view @modelcontextprotocol/server-postgres version

# List all config directories with permissions
ls -la ~/.cursor/ ~/.config/opencode/ ~/.codex/

# Check project directories
ls -la .cursor/ .vscode/ .codex/

# Verify files are writable
test -w ~/.cursor/mcp.json && echo "Writable" || echo "Not writable"

​
Getting Help

If you’re still experiencing issues:
  1. Check existing GitHub issues: github.com/neondatabase/add-mcp/issues
  2. Create a new issue with:
    • Your operating system
    • The exact command you ran
    • Complete error message
    • Output of npx add-mcp list-agents
    • Agent and version you’re using
  3. Include relevant config files (remove sensitive tokens/URLs)

Build docs developers (and LLMs) love

Get started for freeTalk to us