Troubleshooting

This guide covers common issues and how to resolve them.

Server Startup Issues

"Config not found" Error

Solutions:

1. Check if config file exists:

   ls -la config/default.yaml

2. Specify config path explicitly:

   mcp-director serve --config /path/to/your/config.yaml

3. Set the environment variable:

   export MCP_DIRECTOR_CONFIG=/path/to/config.yaml

"Address already in use" Error

Solutions:

1. Find and stop the process using the port:

   lsof -i :3000
   kill <PID>

2. Use a different port:

   settings:
     http:
       port: 3001

"Authentication enabled but no password configured"

Solution: Either disable auth or set up a password:

# Option 1: Start with auth disabled, then enable via CLI
mcp-director serve
mcp-director auth enable --reset-password -p "your-secure-password"

# Option 2: Disable auth in config

Connection Problems

SSE Connection Drops Immediately

Solutions:

1. Check CORS configuration:

   settings:
     http:
       allowed_origins:
         - "http://localhost:3000"

2. Verify client is sending correct headers

3. Check server logs for authentication failures

"Connection refused" When Using connect

Solutions:

1. Ensure the server is running with --no-stdio:

   mcp-director serve --no-stdio

2. Verify the URL:

   mcp-director connect --url http://127.0.0.1:3000

3. Check server health:

   curl http://127.0.0.1:3000/health

Rate Limited (429 Error)

Solutions:

1. Increase the rate limit:

   settings:
     http:
       rate_limit:
         requests_per_minute: 600

2. Or configure per-profile limits:

   profiles:
     high-volume:
       rate_limit:
         requests_per_minute: 1000

Authentication Issues

"Invalid credentials" on Web UI Login

Solutions:

1. Reset password using CLI:

   mcp-director auth enable --reset-password -p "new-password"

2. Check auth status:

   mcp-director auth status

Profile Token Not Working

Solutions:

1. Verify token in URL:

   /sse?profile=myprofile&token=correct-token

2. Check profile auth is enabled:

   profiles:
     myprofile:
       auth:
         enabled: true
         token: "your-token-here"

3. Use Bearer token header:

   Authorization: Bearer your-token-here

Backend/Server Issues

Backend Shows as Unhealthy

Solutions:

1. Check server status:

   mcp-director server status my-server

2. Verify the command configuration

3. Check required environment variables

4. Look at server logs for error messages

Subprocess Backend Crashes on Startup

Solutions:

1. Test the command manually:

   node server.js

2. Check for missing dependencies

3. Verify working directory and paths

4. Add required environment variables

Client Integration Issues

Claude Desktop Not Connecting

Solutions:

1. Verify claude_desktop_config.json:

   {
     "mcpServers": {
       "director": {
         "command": "mcp-director",
         "args": ["serve"]
       }
     }
   }

2. Ensure mcp-director is in PATH:

   which mcp-director

3. Try absolute path in config

Tools Not Appearing in Client

Solutions:

1. Check if servers are healthy:

   curl http://localhost:3000/api/tools

2. Verify namespace strategy

3. Check profile tool restrictions

4. Verify project includes the servers you need

Getting Help

If you can't resolve your issue:

1. Check the logs with debug level:

   mcp-director serve --log-level debug

2. Search existing issues

3. Open a new issue with:

   • MCP Director version
   • Configuration (remove sensitive data)
   • Full error message
   • Steps to reproduce