• Command MySQL InnoDB clusters autonomously.
• Manage Router connections securely.
• Monitor metadata cache status in real-time.
• Scale Read/Write workloads seamlessly.

• MySQL Router 8.0.17+ with REST API enabled
• Router REST API credentials (username/password)
• Network access to Router REST API endpoint (default: HTTPS on port 8443)
• For InnoDB Cluster mode: The cluster must be running for REST API authentication

Important:

When Router is bootstrapped against an InnoDB Cluster, it uses metadata_cache authentication by default. This authenticates REST API users against the cluster's metadata database.

1. Create REST API user in the cluster:

-- Connect to any cluster node
-- The user will be stored in mysql_innodb_cluster_metadata.router_rest_accounts

# Use mysqlrouter_passwd to generate the password hash
mysqlrouter_passwd set /tmp/rest_api.pwd rest_api
# Insert into cluster metadata (on PRIMARY node)
mysql -h localhost -P 3307 -u cluster_admin -p -e "INSERT INTO mysql_innodb_cluster_metadata.router_rest_accounts(cluster_id, user, authentication_method, authentication_string, description) SELECT cluster_id, 'rest_api', 'modular_crypt_format', '<hash_from_mysqlrouter_passwd>', 'REST API user' FROM mysql_innodb_cluster_metadata.clusters LIMIT 1;"

2. Router config uses metadata_cache backend:

[http_auth_backend:default_auth_backend]
backend=metadata_cache

For standalone Router deployments without InnoDB Cluster:

[http_server]
port=8443
ssl=1
ssl_cert=/path/to/router-cert.pem
ssl_key=/path/to/router-key.pem

[http_auth_realm:default_auth_realm]
backend=default_auth_backend
method=basic
name=default_realm

[http_auth_backend:default_auth_backend]
backend=file
filename=/path/to/mysqlrouter.pwd

[rest_router]
require_realm=default_auth_realm

[rest_routing]
require_realm=default_auth_realm

# Generate password hash (prompts for password)
mysqlrouter_passwd set /path/to/mysqlrouter.pwd router_admin

⚠️ Never commit Router credentials to version control. Use environment variables or secure secrets management.

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--mysql",
        "mysql://user:password@localhost:3306/database"
      ],
      "env": {
        "MYSQL_ROUTER_URL": "https://router.example.com:8443",
        "MYSQL_ROUTER_USER": "router_admin",
        "MYSQL_ROUTER_PASSWORD": "router_password",
        "MYSQL_ROUTER_INSECURE": "true"
      }
    }
  }
}

If you only want Router tools (e.g., for a dedicated monitoring agent):

{
  "args": [
    "--transport",
    "stdio",
    "--tool-filter",
    "router"
  ]
}

Cause: Router REST API is unreachable or TLS handshake failed.

Solutions:

1. Verify Router is running: docker ps | grep router
2. Check Router logs: docker logs mysql-router
3. Test API manually: curl -k -u rest_api:router_api https://localhost:8443/api/20190715/router/status
4. Ensure MYSQL_ROUTER_INSECURE=true is set for self-signed certificates

Cause: Authentication failed. For metadata_cache backend, this usually means the InnoDB Cluster is not running.

Solutions:

1. Start the InnoDB Cluster: docker compose -f innodb-cluster.yml up -d
2. Reboot cluster from outage if needed: dba.rebootClusterFromCompleteOutage()
3. Restart Router to reconnect: docker restart mysql-router
4. Verify credentials match the router_rest_accounts table

Cause: Cluster nodes are running but Group Replication is not active.

Solution: Reboot cluster from complete outage using MySQL Shell:

mysqlsh --uri cluster_admin:password@localhost:3307 --js \
  -e "dba.rebootClusterFromCompleteOutage('clusterName', {force: true})"

Cause: The connection pool name doesn't exist or connection pooling is not enabled.

• Enterprise Security: Implemented OAuth 2.1 validator middleware for secure REST API integrations.
• Improved Testing: Strengthened anti-hallucination guardrails across coordinator workflows (including strict list_dir requirements and task.md checklists).
• Token Optimization: Added summary, limit, and compact flags across tools for reduced token usage.

• Graceful error handling — All errors extend MySQLMcpError (9 categories). They return a deterministic schema: {success, error, code, category, suggestion, recoverable} via formatHandlerError(). Never raw MCP exceptions. Improved messages for common issues: connection refused, timeout, TLS certificate errors. Error payloads are strictly enforced by Zod 3.24+ / Standard Schema compliant z.preprocess() boundaries (Dual-Schema Pattern) to ensure predictable AI agent parsing and graceful interception via .safeParse(). The result is a Deterministic ErrorResponse Schema (powered by Standard Schema).
• mysql_router_pool_status — Fixed description to accurately reflect actual API response fields (idleServerConnections, stashedServerConnections).

• Tools - Complete tool list
• Tool-Filtering - Custom tool filtering
• Configuration - General configuration