Troubleshooting

Solutions for common RouterMCP issues.

Connection Issues

404 Not Found

Cause: Incorrect URL path

Solution: Ensure URL includes:

• /v1/ prefix (not /1/)
• /request suffix for JSON-RPC endpoint

✓ https://gateway.routermcp.com/v1/mcp/my-project/request
✗ https://gateway.routermcp.com/1/mcp/my-project/request
✗ https://gateway.routermcp.com/v1/mcp/my-project

401 Unauthorized

Cause: Missing or invalid API key

Solution:

1. Check project authMode is set to api_key
2. Include Authorization: Bearer {key} header
3. Verify the key hasn't been revoked

Connection Timeout

Cause: Network or server issues

Solution:

1. Check the endpoint URL is correct
2. Verify network connectivity
3. Check if upstream servers are responding
4. Try increasing timeout settings

Tool Issues

Tools Not Appearing

Causes:

• Servers not configured
• Tools disabled
• Filter rules blocking

Solution:

1. Verify servers are added and enabled
2. Check allowedTools / denyTools filters
3. Sync tools from upstream: POST /api/servers/{id}/sync

Tool Not Found (-32002)

Cause: Tool name doesn't include server prefix

Solution: Use full namespaced name:

✓ github.create_issue
✗ create_issue

Tool Disabled (-32003)

Cause: Tool exists but is disabled

Solution: Enable the tool in dashboard or via API

CLI Issues

Command Not Found

Cause: RouterMCP not installed globally

Solution:

npm install -g routermcp
# or use npx
npx routermcp --help

Config File Not Found

Cause: No routermcp.jsonc in current directory

Solution:

routermcp config  # Create config
# or specify path
routermcp -c /path/to/routermcp.jsonc

Upstream Server Fails to Connect

Causes:

• Invalid command or URL
• Missing environment variables
• Network issues

Solution:

1. Test the upstream server independently
2. Check environment variables are set
3. Use verbose mode: routermcp -v

Code Mode Issues

Timeout

Cause: Execution exceeds timeout limit

Solution: Increase timeout or optimize code:

{
  "codeMode": {
    "timeout": 60000
  }
}

Fetch Not Available

Cause: allowFetch is disabled

Solution:

{
  "codeMode": {
    "allowFetch": true
  }
}

Debugging

Enable Verbose Logging

routermcp -v

Test with cURL

curl -i -X POST 'https://gateway.routermcp.com/v1/mcp/my-project/request' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_key' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Check Audit Logs

Review audit logs in the dashboard for error details.