Performance Tuning

Performance Tuning

Value Proposition Achieve peak agent throughput and minimal latency. mysql-mcp empowers you to optimize performance at scale through Code Mode token efficiency, intelligent connection pooling, and deep sysschema diagnostics, ensuring your workflows run at maximum velocity. Read the full value proposition.

---

Connection Pooling

The mysql2 connection pool configuration directly impacts concurrent tool execution.

Key Parameters

Parameter	Default	CLI	Environment Variable	Effect
connectionLimit	10	--pool-size	MYSQL_POOL_SIZE	Max simultaneous connections
acquireTimeout	configurable connection timeout	--pool-timeout	MYSQL_POOL_TIMEOUT	How long to wait for a free connection
queueLimit	0 (∞)	--pool-queue-limit	MYSQL_POOL_QUEUE_LIMIT	Max requests waiting in queue

Guidance

• stdio (single agent): Default 10 works well. AI agents usually issue queries sequentially.
• Streamable HTTP (multiple agents): Increase to 20–50. Each tool call needs a connection. Monitor for acquireTimeout errors.
• Short-lived queries: If your workload is mostly reads, a pool of 10–15 handles high throughput because connections are returned quickly.
• Long-running analytics: Increase the pool for complex aggregations holding connections. Consider using Code Mode. It batches work into a single connection.

Distributed Rate Limiting

Configuring REDIS_URL synchronizes rate limits across both the HTTP Transport layer (governed by MCP_RATE_LIMIT_MAX) and Code Mode (governed by CODEMODE_RATE_LIMIT_MAX). Crucially, the system features a graceful fallback to in-memory rate limiting if the Redis instance becomes unavailable.

This distributed rate limiting is an essential safeguard for database resources, ensuring equitable access and uncompromised stability in high-concurrency, multi-agent enterprise environments.

Strategize Tool Filtering

Exposing all tools to an LLM increases the system prompt payload. This costs more tokens and slows response time.

Understand the Impact of Filters

The --tool-filter CLI flag selectively mounts only needed tools.

Avoid mounting all tools, as it incurs high latency and token costs. Use presets like starter or dba-monitor to streamline the agent's context.

# Mount only the tools your agent needs
npx -y @neverinfamous/mysql-mcp --tool-filter starter

See Tool Filtering for the complete list of groups and shortcuts.

Maximize Efficiency

Code Mode (mysql_execute_code) provides significant token savings over individual tool calls.

Decide When to Use Individual Tools

• Single-step retrieval: "Get the schema for the users table."
• Simple lookups: "Search for 'payment failed' in the logs."
• Low latency per step: Tool calls are fast. Multi-step reasoning requires multiple LLM roundtrips.

Decide When to Use Code Mode

• Multi-step data pipelines: Query tables and process results in JavaScript.
• Token efficiency: Up to 90% token savings. The script returns only the final answer.
• Performance: Eliminates network latency of multi-step reasoning loops. The script runs in a V8 isolate.
• High Efficiency: Batching complex data pipelines reduces token usage and overhead.

Rule of Thumb: Use Code Mode if a question requires more than two sequential queries.

Analyze Query Performance

We include dedicated tools for diagnosing slow queries and optimizing execution plans.

Review Key Tools

Tool	Purpose
mysql_explain	Analyze query execution plans (EXPLAIN / EXPLAIN ANALYZE)
mysql_slow_queries	Identify and analyze slow queries from the performance schema
mysql_optimizer_trace	Trace optimizer decisions for a specific query
mysql_index_recommendation	Suggest missing indexes based on query patterns. Supports database-wide audits
mysql_buffer_pool_stats	Monitor InnoDB buffer pool hit rates and memory usage
mysql_sys_*	Expose MySQL sysschema diagnostics (redundant indexes, unused indexes, statement analysis)

Follow the Workflow

1. Identify slow queries via mysql_slow_queries or mysql_sys_statement_summary.
2. Analyze the plan with the mysql_explain tool for actual execution metrics.
3. Check for missing indexes with mysql_index_recommendation.
4. Verify improvements by re-running mysql_explain after adding indexes.

Review InnoDB Tuning Quick Reference

Setting	Recommendation	Tool to Monitor
innodb_buffer_pool_size	70–80% of available RAM on dedicated servers	mysql_buffer_pool_stats
innodb_flush_log_at_trx_commit	1 for durability, 2 for throughput (risk: 1s data loss on crash)	mysql_show_variables
innodb_log_file_size	Large enough to hold 1–2 hours of writes	mysql_show_status
Buffer pool hit rate	Target ≥99%	mysql_buffer_pool_stats

Note: Tune these server-level settings in your MySQL configuration file or via SET GLOBAL.

Monitor Telemetry Real-Time

Connection pool metrics, system latency, and active sessions can be monitored in real-time via the Prometheus /metrics endpoint and visualized in the Grafana dashboard.

Important

The /metrics endpoint requires the HTTP transport (--transport http).

For full setup instructions, see Observability & Telemetry.

Verify Performance Characteristics

Our benchmarks confirm microsecond-level overhead on critical paths:

Area	Key Metric	Notes
Tool dispatch	High-throughput O(1) hash resolution	O(1) hash-based tool resolution
Schema validation	Sub-millisecond validation	Depends on schema complexity
Token estimation	Sub-millisecond validation	Content-type-aware
Code Mode sandbox init	Optimized cold start	isolated-vm cold start
Logger	High-throughput	Zero work when below minLevel

Run pnpm run bench locally for full results on your hardware.

Note: Zod schemas are defined statically for instant boot times.

---

Explore Related Topics

• Capacity Planning
• Tool Filtering
• Code Mode
• Configuration