claude-mcp-server-troubleshooting-gist.md

Setting up MCP Servers with Claude - Troubleshooting Guide

A comprehensive guide for configuring Model Context Protocol (MCP) servers with Claude, with focus on Supabase MCP server setup

Overview

This guide covers common issues and solutions when setting up MCP servers for Claude integration, specifically addressing Node.js compatibility and path configuration problems.

Common Error Patterns

Node.js Compatibility Issues

Error: parseArgs Not Available

SyntaxError: The requested module 'node:util' does not provide an export named 'parseArgs'

Cause: Node.js version < 18.17 Solution: Upgrade to Node.js ≥18.17

Error: Function Not Available

TypeError: args.at is not a function

Cause: Mixed Node.js versions or npm compatibility issues Solution: Use explicit Node.js binary path in MCP configuration

Path Configuration Issues

Error: Module Not Found

Error: Cannot find module '[path]/dist/index.js'

Cause: Incorrect path to MCP server executable Solution: Use correct path to transport file (usually dist/transports/stdio.js)

Working Configuration Example

MCP Server Configuration

{
  "server-name": {
    "command": "~/.nvm/versions/node/v18.20.8/bin/node",
    "args": ["./packages/mcp-server-name/dist/transports/stdio.js"],
    "env": {
      "SUPABASE_ACCESS_TOKEN": "your_token_here"
    }
  }
}

Key Configuration Elements

1. Explicit Node.js Path: Use full path to Node 18+ binary

   • Avoids system default version conflicts
   • Format: ~/.nvm/versions/node/v18.x.x/bin/node

2. Correct Executable Path: Point to transport file, not main index

   • Usually: ./packages/server-name/dist/transports/stdio.js
   • Check package.json bin field for confirmation

3. Environment Variables: Include required tokens/keys

   • Server-specific authentication credentials
   • API keys or access tokens

Directory Structure

Typical MCP Server Repository Layout

./your-mcp-server/
├── packages/
│   ├── mcp-server-name/
│   │   ├── dist/
│   │   │   ├── transports/
│   │   │   │   └── stdio.js          # <- Actual executable
│   │   │   └── index.js
│   │   ├── src/
│   │   └── package.json              # Check bin field here
│   └── utils/
└── package.json

Troubleshooting Steps

1. Verify Node.js Version

node --version  # Should be ≥18.17

2. Find Correct Node.js Binary

which node
# If using nvm:
nvm which 18

3. Check MCP Server Build

ls -la ./packages/mcp-server-name/dist/transports/stdio.js

4. Verify Package Configuration

cat ./packages/mcp-server-name/package.json | grep -A 3 '"bin"'

5. Test Manual Execution

~/.nvm/versions/node/v18.20.8/bin/node ./packages/mcp-server-name/dist/transports/stdio.js --version

6. Check MCP Logs

# Mac/Linux - adjust path for your system
tail -f ~/Library/Logs/Claude/mcp-server-name.log

Common Solutions

Node.js Version Issues

• Install Node.js 18+ via nvm: nvm install 18
• Use explicit binary path in configuration
• Avoid relying on system default Node.js

Path Configuration

• Check package.json for correct executable path
• Ensure MCP server is built: npm run build
• Use relative paths from MCP configuration location

Permission Issues

• Ensure execute permissions: chmod +x [node-binary]
• Check file permissions on MCP server files
• Verify directory access permissions

Environment Variables

• Use server-specific token/key names
• Ensure tokens have proper API permissions
• Test token validity outside of MCP context

Verification

Successful Setup Indicators

1. No errors in MCP server logs
2. Server tools appear in Claude interface
3. Test operations return expected data
4. No connection timeout errors

Debug Commands

# Check Node.js compatibility
node -e "console.log(process.version)"

# Test MCP server directly
./node-binary ./mcp-server-path --help

# Monitor logs in real-time
tail -f ~/Library/Logs/Claude/mcp-server-*.log

Best Practices

1. Use NVM: Manage multiple Node.js versions easily
2. Explicit Paths: Always use full paths in MCP configuration
3. Test Locally: Verify MCP server works before configuring with Claude
4. Check Logs: Monitor logs during initial setup
5. Version Control: Document working configurations

References

• Model Context Protocol Documentation
• Node.js Version Requirements
• Claude MCP Integration Guide

Notes

• Paths may need adjustment based on your system and installation method
• Some MCP servers may have additional requirements or configuration steps
• Always remove sensitive tokens before sharing configurations