Performance Tuning

Unleash Enterprise Performance

1. 🚀 Value Proposition

• Ultra-Low Latency: Achieve microsecond-level overhead on critical database paths.
• Ensure your database orchestrations run at maximum velocity.
• Keep agents fast and costs minimal with ultra-low token overhead.

2. 🌊 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	30000 ms	--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 concurrent tool call needs its own connection. Monitor for acquireTimeout errors in logs.
• 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 if agents run complex aggregations that hold connections for seconds. Consider using Code Mode to batch work into a single connection.

3. Tool Filtering Strategies

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

The Impact of Filters

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

• No filter (all 241 tools): High latency, high token cost. Exceeds IDE limits.
• starter (43 tools): Recommended default. Core CRUD, JSON, text, and Code Mode.
• dba-monitor (43 tools): For operations/DBA agents. Performance, monitoring, sys schema, optimization.
• codemode (1 tool): Ultimate minimalism. One tool with full database API access.

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

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

4. Maximize Efficiency

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

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, but multi-step reasoning requires multiple LLM roundtrips.

When to Use Code Mode (mysql_execute_code)

• Multi-step data pipelines: Query tables and process results in JavaScript.
• Token efficiency: 70–90% token savings. The script returns only the final answer.
• Performance: Eliminates network latency of multi-step reasoning loops. The script runs in a native V8 isolate.
• Unbeatable ROI: Instantaneous execution of complex data pipelines slashes costs.

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

5. Analyze Query Performance

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

Key Tools

Tool	Purpose
mysql_explain	Analyze query execution plans (EXPLAIN / EXPLAIN ANALYZE)
mysql_slow_query_analysis	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, now supporting full database-wide audits
mysql_buffer_pool_stats	Monitor InnoDB buffer pool hit rates and memory usage
mysql_sysschema_*	Expose MySQL sys schema diagnostics (redundant indexes, unused indexes, statement analysis)

Workflow

1. Identify slow queries via mysql_slow_query_analysis or mysql_sysschema_statements_with_runtimes_in_95th_percentile.
2. Analyze the plan with mysql_explain using analyze: true for actual execution metrics.
3. Check for missing indexes with mysql_index_recommendation.
4. Verify improvements by re-running mysql_explain after adding indexes.

6. Master 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.

7. Verify Performance Characteristics

Our benchmarks confirm microsecond-level overhead on critical paths:

Area	Key Metric	Notes
Tool dispatch	~5M+ ops/sec (Map.get lookup)	O(1) hash-based tool resolution
Schema validation	~200K–500K ops/sec	Depends on schema complexity
Token estimation	~1M+ ops/sec	Content-type-aware
Code Mode sandbox init	~2000 ops/sec	isolated-vm cold start
Logger	~5M+ ops/sec	Zero work when below minLevel

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

Note: Zod schemas compile lazily to maintain validation boundaries without impacting boot times.

---

See also: Capacity-Planning · Tool-Filtering · Code-Mode · Configuration