Performance Tuning

Performance Tuning

Maximize agent throughput with Code Mode token savings, connection pool tuning, and sysschema diagnostics.

---

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.

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.

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