Skip to content

Configuration

Jump to bottom
Chris edited this page Jul 18, 2026 · 142 revisions

Configure Enterprise Deployments

Tools Resources Prompts
OAuth Code Mode Rate Limiting

Value Proposition Simplify database integrations with flexible deployment options. Connect across different environments using various transport protocols and connection pooling to help support reliable and scalable operations.

🔒 Secure Your Enterprise Environment

Secure and streamline enterprise deployments with our flexible configuration architecture. Confidently manage secrets via environment variables or .env files, and leverage the --config flag to inject comprehensive, easily maintainable JSON/YAML deployment settings.

🤖 Integrate AI Agents Seamlessly

Configure Cursor IDE

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--mysql",
        "mysql://user:password@localhost:3306/database",
        "--tool-filter",
        "codemode"
      ]
    }
  }
}

Configure Claude Desktop

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@neverinfamous/mysql-mcp",
        "--transport",
        "stdio",
        "--mysql",
        "mysql://user:password@localhost:3306/database"
      ]
    }
  }
}

Configure Docker

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "MYSQL_HOST=host.docker.internal",
        "-e",
        "MYSQL_USER=user",
        "-e",
        "MYSQL_PASSWORD=password",
        "-e",
        "MYSQL_DATABASE=database",
        "writenotenow/mysql-mcp:latest",
        "--transport",
        "stdio"
      ]
    }
  }
}

Note

Use host.docker.internal to connect to MySQL running on your host machine from Docker. Docker images use the writenotenow namespace. The GitHub repo and NPM package use neverinfamous.

⚖️ Improve Throughput

Support enterprise scalability by deploying mysql-mcp as an HTTP server for remote deployments instead of using stdio:

# Local installation
npx -y @neverinfamous/mysql-mcp --transport http --server-host 0.0.0.0 --port 3000 --allowed-io-roots /data --mysql mysql://user:password@localhost:3306/database

# Docker with port mapping
docker run -p 3000:3000 \
  -e MYSQL_HOST=host.docker.internal \
  -e MYSQL_USER=user \
  -e MYSQL_PASSWORD=password \
  -e MYSQL_DATABASE=database \
  writenotenow/mysql-mcp:latest \
  --transport http \
  --server-host 0.0.0.0 \
  --port 3000 \
  --allowed-io-roots /data

When to use HTTP mode:

  • Deploying to cloud platforms (AWS, GCP, Azure)
  • Multiple AI clients connecting to one database
  • Enabling OAuth 2.0 / OIDC authentication
  • Running as a standalone network service
  • Serverless/stateless deployments (--stateless)
  • Exposing Prometheus metrics (/metrics) for telemetry

Tip

Most users should use stdio mode for local development. See HTTP Transport for HTTP deployment details. The CLI and ecosystem environments both default to port 3000 for frictionless out-of-the-box scaling.

🚩 Command-Line Configuration

Option Environment Variable Default Description
--config, -c - - Configuration file path (.yaml or .json)
--dump-config - - Dump current configuration to stdout and exit
--transport, -t - stdio Transport type: stdio, http (starts /mcp, /sse, and /messages endpoints), sse (alias for http).
--port, -p MYSQLMCP_PORT, PORT 3000 HTTP port for http/sse transports (fallback alias: PORT)
--server-host MCP_HOST localhost Host to bind HTTP transport to (Alias: HOST)
--mysql, -m - - MySQL connection string
--mysql-host MYSQL_HOST - MySQL host
--mysql-port MYSQL_PORT 3306 MySQL port
--mysql-user MYSQL_USER - MySQL username
--mysql-password MYSQL_PASSWORD - MySQL password
--mysql-database MYSQL_DATABASE - MySQL database name
--pool-size MYSQL_POOL_SIZE 10 Connection pool size
--pool-timeout MYSQL_POOL_TIMEOUT 10000 Connection acquire timeout in ms
--pool-queue-limit MYSQL_POOL_QUEUE_LIMIT 0 Queue limit for waiting requests
--tool-filter, -f TOOL_FILTER - Tool filter string
--auth-token MCP_AUTH_TOKEN - Simple bearer token for HTTP authentication
--stateless - false Enable strictly stateless HTTP transport (disables sessions and SSE to support serverless scaling). (Warning: Entirely disables resource subscriptions and progress notifications).
--trust-proxy TRUST_PROXY false Trust X-Forwarded-For for client IP
--enable-hsts MCP_ENABLE_HSTS false Enable HTTP Strict Transport Security
--metrics-export MCP_METRICS_EXPORT disabled Enable Prometheus format metrics endpoint (requires a string provider, e.g., 'prometheus'). (Requires HTTP transport)
--log-level LOG_LEVEL info Log level: debug, info, warn, error
--allowed-io-roots ALLOWED_IO_ROOTS - Explicitly authorize filesystem boundaries (Required when using HTTP transport; emits warning for stdio)
--audit-log AUDIT_LOG - Path to the audit log file
--audit-backup AUDIT_BACKUP false Enable pre-mutation snapshots for DML changes
--audit-reads AUDIT_READS false Include read-scope tool calls in the audit log
--audit-redact AUDIT_REDACT false Redact sensitive arguments in the audit log
--audit-log-max-size AUDIT_LOG_MAX_SIZE - Max file size before rotation (bytes)
--audit-backup-data AUDIT_BACKUP_DATA false Include sample data in pre-mutation snapshots
--audit-backup-max-size AUDIT_BACKUP_MAX_SIZE - Max table size in bytes for data capture
--mysql-router-url MYSQL_ROUTER_URL https://localhost:8443 URL for MySQL Router REST API
--mysql-router-api-version MYSQL_ROUTER_API_VERSION /api/20190715 MySQL Router REST API path structure (e.g., /api/20190715), not a software version
--mysql-router-user MYSQL_ROUTER_USER - Username for MySQL Router REST API
--mysql-router-password MYSQL_ROUTER_PASSWORD - Password for MySQL Router REST API
--mysql-router-insecure MYSQL_ROUTER_INSECURE false Allow insecure connections to MySQL Router
--proxysql-host PROXYSQL_HOST localhost ProxySQL admin interface hostname
--proxysql-port PROXYSQL_PORT 6032 ProxySQL admin interface port
--proxysql-user PROXYSQL_USER admin ProxySQL admin username
--proxysql-password PROXYSQL_PASSWORD admin ProxySQL admin password
--mysqlsh-path MYSQLSH_PATH - Path to mysqlsh executable
--mysql-xport MYSQL_XPORT 33060 X Protocol port (for mysqlsh_import_json and docstore tools in mysql-ecosystem)
--oauth-enabled, -o OAUTH_ENABLED false Enable OAuth 2.0 / OIDC authentication (Enterprise Identity Providers like Okta, Auth0, etc.)
--oauth-issuer OAUTH_ISSUER - OAuth issuer URL
--oauth-audience OAUTH_AUDIENCE mysql-mcp-client OAuth audience
--oauth-jwks-uri OAUTH_JWKS_URI - JWKS URI (auto-discovered)
--oauth-clock-tolerance OAUTH_CLOCK_TOLERANCE 60 Clock tolerance in seconds
- CODEMODE_ISOLATION isolate Sandbox mode (only native isolate is supported)
- METADATA_CACHE_TTL_MS 30000 Cache TTL for schema metadata (ms)
- CODEMODE_MAX_RESULT_SIZE 102400 Max Code Mode result payload in bytes
- MCP_RATE_LIMIT_MAX 100 Max HTTP requests per minute per IP
- CODEMODE_RATE_LIMIT_MAX 60 Max Code Mode executions per minute per IP
- REDIS_URL - Redis URL for distributed rate limiting

🔐 Secure Enterprise Deployment via Environment Variables

For security, use environment variables instead of connection strings:

{
  "mcpServers": {
    "mysql-mcp": {
      "command": "npx",
      "args": ["-y", "@neverinfamous/mysql-mcp", "--transport", "stdio"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_PORT": "3306",
        "MYSQL_USER": "your_user",
        "MYSQL_PASSWORD": "your_password",
        "MYSQL_DATABASE": "your_database"
      }
    }
  }
}

Review Available Variables

Database

Parameter Default Description
MYSQL_HOST - MySQL server hostname
MYSQL_PORT 3306 MySQL server port
MYSQL_USER - MySQL username
MYSQL_PASSWORD - MySQL password
MYSQL_DATABASE - Default database
MYSQL_POOL_SIZE 10 Max connections in pool
MYSQL_POOL_TIMEOUT 10000 Connection timeout (ms)
MYSQL_POOL_QUEUE_LIMIT 0 Queue limit for waiting requests

Tool Filtering

Parameter Default Description
TOOL_FILTER - Filter tools by group or exact name

Server

Parameter Default Description
MCP_HOST localhost Host to bind HTTP transport to (Alias: HOST)
MYSQLMCP_PORT 3000 HTTP port for http/sse transports (fallback alias: PORT)
MCP_AUTH_TOKEN - Simple bearer token for HTTP authentication
MCP_RATE_LIMIT_MAX 100 Max HTTP requests per minute per IP address. Requires REDIS_URL for distributed tracking. Falls back to in-memory.
CODEMODE_RATE_LIMIT_MAX 60 Code Mode executions per minute per IP address. Requires REDIS_URL for distributed tracking. Falls back to in-memory.
REDIS_URL - Redis URL for distributed rate limiting
TRUST_PROXY false Trust X-Forwarded-For for client IP
MCP_ENABLE_HSTS false Enable HTTP Strict Transport Security
MCP_METRICS_EXPORT disabled Enable Prometheus format metrics endpoint /metrics (requires a string provider, e.g., 'prometheus'). (Requires HTTP transport)
MYSQL_ROUTER_URL https://localhost:8443 URL for MySQL Router REST API
MYSQL_ROUTER_API_VERSION /api/20190715 MySQL Router REST API path structure (e.g., /api/20190715), not a software version
MYSQL_ROUTER_USER - Username for MySQL Router REST API
MYSQL_ROUTER_PASSWORD - Password for MySQL Router REST API
MYSQL_ROUTER_INSECURE false Allow insecure connections to MySQL Router
PROXYSQL_HOST localhost ProxySQL admin interface hostname
PROXYSQL_PORT 6032 ProxySQL admin interface port
PROXYSQL_USER admin ProxySQL admin username
PROXYSQL_PASSWORD admin ProxySQL admin password
MYSQLSH_PATH - Path to mysqlsh executable
MYSQL_XPORT 33060 X Protocol port (for mysqlsh_import_json and docstore tools in mysql-ecosystem)
ALLOWED_IO_ROOTS - Explicitly authorize filesystem boundaries (Required when using HTTP transport)
CODEMODE_MAX_RESULT_SIZE 102400 Max Code Mode result payload in bytes (default 100KB, up to 100MB limit)
CODEMODE_TIMEOUT_MS 30000 Code mode execution timeout in ms
MCP_MAX_BODY_SIZE 1048576 Maximum request body size in bytes
MCP_REQUEST_TIMEOUT 120000 Global request timeout in ms
MCP_HEADERS_TIMEOUT 66000 Global headers timeout in ms
MCP_KEEPALIVE_TIMEOUT 65000 Keep-alive timeout in ms
MCP_IDLE_TIMEOUT 300000 Idle session timeout in ms
MCP_ABSOLUTE_TIMEOUT 3600000 Absolute session timeout in ms
MCP_REAPER_INTERVAL 60000 Session reaper interval in ms

Audit Trail

Parameter Default Description
AUDIT_LOG - Path to the audit log file
AUDIT_BACKUP false Enable pre-mutation snapshots for DML changes
AUDIT_READS false Include read-scope tool calls in the audit log
AUDIT_REDACT false Redact sensitive arguments in the audit log
AUDIT_LOG_MAX_SIZE - Max file size before rotation (bytes)
AUDIT_BACKUP_DATA false Include sample data in pre-mutation snapshots
AUDIT_BACKUP_MAX_SIZE - Max table size in bytes for data capture

OAuth

Parameter Default Description
OAUTH_ENABLED false Enable OAuth 2.0 / OIDC authentication (Enterprise Identity Providers like Okta, Auth0, etc.)
OAUTH_ISSUER - OAuth issuer URL
OAUTH_AUDIENCE mysql-mcp-client OAuth audience
OAUTH_JWKS_URI - JWKS URI (auto-discovered)
OAUTH_CLOCK_TOLERANCE 60 Clock tolerance in seconds

Optimize Core Performance Parameters

Fine-tune your deployment for peak performance by configuring these enterprise-grade core parameters.

Parameter Default Description
METADATA_CACHE_TTL_MS 30000 Cache TTL for schema metadata (ms)
LOG_LEVEL info Log verbosity: debug, info, warn, error
--stateless false Enable stateless HTTP mode (no sessions, no SSE). Note: CLI-only flag, cannot be set via env.
CODEMODE_ISOLATION isolate Sandbox mode (only native isolate is supported)

Tip

Lower METADATA_CACHE_TTL_MS for development. Increase it for production databases with stable schemas.

Maximize Efficiency with Token-Optimized Payloads

Many tools support optional parameters to reduce response size and token usage:

Flag Effect Tool Groups
summary Return a concise summary instead of full detailed results Applicable to tools returning large datasets
limit Cap the number of returned rows/items (up to a configured maximum) such as stats, spatial, and monitoring tools
compact Omit verbose fields from results Applicable to tools that return large metadata objects

Tip

Tools supporting limit return limited and totalAvailable flags. This informs you about truncated results.

🔌 Connect Databases

🖥️ Local MySQL (Installed on Your Machine)

{
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "root",
    "MYSQL_PASSWORD": "password",
    "MYSQL_DATABASE": "mydb"
  }
}

🐳 Docker MySQL (Container)

Option 1: Port Mapping (Recommended)

If MySQL container uses -p 3306:3306:

{
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306"
  }
}

Option 2: Container IP

# Find container IP
docker inspect mysql-container | grep IPAddress
{
  "env": {
    "MYSQL_HOST": "172.17.0.2",
    "MYSQL_PORT": "3306"
  }
}

☁️ Remote MySQL (Cloud/RDS)

{
  "env": {
    "MYSQL_HOST": "your-db.us-east-1.rds.amazonaws.com",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "admin",
    "MYSQL_PASSWORD": "password",
    "MYSQL_DATABASE": "production"
  }
}

Common cloud hostnames:

Provider Example Hostname
AWS RDS your-instance.xxxx.us-east-1.rds.amazonaws.com
Google Cloud SQL 127.0.0.1 (when using Cloud SQL Proxy locally)
Azure MySQL your-server.mysql.database.azure.com
PlanetScale aws.connect.psdb.cloud (SSL required)
DigitalOcean your-cluster-do-user-xxx.db.ondigitalocean.com

Tip

Remote connections may require SSL. Check your provider's documentation.

📊 Configure Observability & Telemetry

Enable native Prometheus format metrics export via the /metrics endpoint. This is available exclusively on the HTTP transport. Use the --metrics-export CLI flag or the MCP_METRICS_EXPORT=prometheus environment variable.

{
  "env": {
    "MCP_METRICS_EXPORT": "prometheus"
  }
}

Deploy via test-server/infrastructure. Prometheus and Grafana are pre-configured. They scrape this endpoint and display metrics instantly.

🏊 Configure Connection Pooling

MySQL benefits from connection pooling. Configure via environment variables:

{
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "app_user",
    "MYSQL_PASSWORD": "secure_password",
    "MYSQL_DATABASE": "production",
    "MYSQL_POOL_SIZE": "20", // 20 is an increase from default 10
    "MYSQL_POOL_TIMEOUT": "10000"
  }
}

🧩 Integrate Ecosystem Tools

For InnoDB Cluster deployments with MySQL Router, ProxySQL, and MySQL Shell:

{
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3307",
    "MYSQL_USER": "cluster_admin",
    "MYSQL_PASSWORD": "cluster_password",
    "MYSQL_DATABASE": "mysql",
    "MYSQL_XPORT": "33060",
    "MYSQL_ROUTER_URL": "https://localhost:8443",
    "MYSQL_ROUTER_USER": "rest_api",
    "MYSQL_ROUTER_PASSWORD": "router_password",
    "MYSQL_ROUTER_INSECURE": "true",
    "PROXYSQL_HOST": "localhost",
    "PROXYSQL_PORT": "6032",
    "PROXYSQL_USER": "radmin",
    "PROXYSQL_PASSWORD": "radmin",
    "MYSQLSH_PATH": "/usr/local/bin/mysqlsh"
  }
}

Important

Router REST API authentication requires a running InnoDB Cluster. See MySQL Router for troubleshooting steps.

🌐 Explore Related Topics

MySQL MCP Documentation

Value Proposition Enforce strict execution boundaries and maximize LLM context efficiency for secure, autonomous database interactions. Read the full value proposition

🏠 Home

Launch Your Setup

Connect Ecosystem Tools

Security & Compliance

Scale Your Operations

Explore External Links

Clone this wiki locally