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 200+ 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 200+ 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