Troubleshooting Guide

May 16, 2026 ยท View on GitHub

This guide helps you resolve common issues with the MySQL Query MCP Server.

MCP Protocol Method Names

Important: The MCP protocol uses specific JSON-RPC method names:

  • tools/list - Used by clients to request a list of available tools
  • tools/call - Used by clients to call a specific tool

The SDK maps these to:

  • ListToolsRequestSchema - For handling tools/list requests
  • CallToolRequestSchema - For handling tools/call requests

If you're building a client that communicates with this server directly, make sure to use the correct method names in your JSON-RPC requests:

// List tools
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list",
  "params": {}
}

// Call a tool
{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "sql": "SELECT 1",
      "environment": "development"
    }
  }
}

Environment Limitations

Important: This tool is designed to work with four specific predefined environments:

  • local
  • development
  • staging
  • production

You cannot use custom environment names like "dev" or "prod". If you need to connect to a database outside of these environments, you must map it to one of these four names.

Example of incorrect naming:

DEV_DB_HOST=dev.example.com  # Wrong: "DEV" is not recognized
PROD_DB_HOST=prod.example.com  # Wrong: "PROD" is not recognized

Example of correct naming:

DEVELOPMENT_DB_HOST=dev.example.com  # Correct: "DEVELOPMENT" is recognized
PRODUCTION_DB_HOST=prod.example.com  # Correct: "PRODUCTION" is recognized

Connection Issues

Problem: Cannot connect to database

Symptoms:

  • "No connection pool available for environment" error
  • "Connection refused" errors

Possible causes and solutions:

  1. Database credentials are incorrect

    • Double-check your credentials in .env or your MCP configuration
    • Verify you can connect to the database using another client like MySQL Workbench

  2. Database server is not running

    • Check if your MySQL server is running
    • For local databases: sudo service mysql status (Linux) or check Activity Monitor (Mac)

  3. Network/firewall restrictions

    • Check if your database allows remote connections
    • Verify firewall settings allow connections on the configured MySQL port ([ENV]_DB_PORT, default 3306)

  4. Missing environment variables

    • Ensure all required variables for your environment are set
    • Run with DEBUG=true to see loaded configuration

  5. Incorrect custom port

    • If your MySQL server is not on 3306, set [ENV]_DB_PORT explicitly
    • Ensure the value is a valid integer such as 3307

  6. Incorrect environment name

    • Verify you're using one of the supported environment names: local, development, staging, production
    • Environment variables must be prefixed with LOCAL_, DEVELOPMENT_, STAGING_, or PRODUCTION_
    • You cannot use custom environment names with this tool (such as DEV_ or PROD_)

Problem: SSL connection errors

Symptoms:

  • "SSL connection error" messages
  • "Cannot establish secure connection" errors

Solutions:

  • If your database doesn't support SSL, set MCP_MYSQL_SSL=false
  • For databases that require SSL but have self-signed certificates, you may need to set MCP_MYSQL_REJECT_UNAUTHORIZED=false
  • For production databases that require SSL, ensure your MySQL client supports it

Query Issues

Problem: Query execution fails

Symptoms:

  • "Query execution failed" errors
  • No results returned

Possible causes and solutions:

  1. Invalid SQL syntax

    • Check your SQL syntax carefully
    • Test the query directly in MySQL client

  2. Unsupported query type

    • Only SELECT, SHOW, and DESCRIBE queries are supported
    • This tool strictly enforces read-only operations
    • You cannot use INSERT, UPDATE, DELETE, CREATE, DROP, or any other data/schema modification queries

  3. Query timeout

    • Your query may be taking too long to execute
    • Optimize your query or increase the timeout parameter

MCP Server Issues

Problem: Server won't start

Symptoms:

  • Process exits immediately after starting
  • Port binding errors

Possible causes and solutions:

  1. Node.js version incompatibility

    • Ensure you're using Node.js 14 or higher
    • Update Node.js if necessary

  2. Permission issues

    • Ensure you have the necessary permissions to run the server
    • Try running with elevated permissions if needed

  3. Binary not found

    • Verify the installation path: which mysql-query-mcp
    • Reinstall the package if necessary

Problem: "Method not found" errors

Symptoms:

  • Client receives "Method not found" error responses
  • No data is returned from the server

Possible causes and solutions:

  1. Incorrect method name format

    • Ensure client is using tools/list and tools/call method names
    • Do NOT use listTools, callTool, or other variations

  2. SDK version mismatch

    • Ensure you're using a compatible version of the MCP SDK

Integration Issues

Problem: AI assistant doesn't recognize the MySQL tools

Symptoms:

  • AI assistant mentions it can't access database functionality
  • AI assistant doesn't list MySQL tools when asked

Possible causes and solutions:

  1. MCP Server not correctly configured

    • Verify your MCP configuration file has the correct setup
    • Make sure to use the full environment names (DEVELOPMENT, not DEV)

  2. Extension not properly configured

    • Ensure your AI tool has the extension properly configured
    • Restart the AI tool after configuration changes

Debugging Tools

Enable Debug Mode

Run the server with debug logging enabled by setting in your configuration:

"env": {
  "DEBUG": "true"
}

Or when running directly:

DEBUG=true mysql-query-mcp

This will output detailed logs to help diagnose issues.

Check Connectivity

Test database connectivity directly:

mysql -h YOUR_HOST -u YOUR_USER -p

Check MySQL Query Tool Status

Verify the server is functioning correctly:

mysql-query-mcp --version

Getting Help

If you can't resolve your issue with this guide:

  1. Open an issue on GitHub
  2. Include:
    • Error messages
    • Steps to reproduce the issue
    • Your environment details (OS, Node.js version)
    • Debug logs (with sensitive information removed)