Performance Tuning

Performance Tuning

💎 Enterprise-Grade Value Proposition

• Maximize AI Context Windows: Transform complex database workflows via Code Mode, unlocking up to 90% token efficiency.
• Accelerate Agent Deployments: Build autonomous AI integrations instantly with zero-trust telemetry and strict boundaries.
• Unleash Autonomous Operations: Equip intelligent agents with granular, schema-enforced database capabilities.
• Scale Without Bottlenecks: Sustain high-throughput agent swarms with robust, enterprise-grade connection pooling.
• Secure Every Transaction: Fortify your infrastructure with native OAuth 2.1 authentication and sandboxed execution.

---

🌊 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 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.

• No filter: High latency, high token cost. Exceeds IDE limits.
• starter: Recommended default. Core CRUD, JSON, text, and Code Mode.
• dba-monitor: For operations/DBA agents. Performance, monitoring, sys schema, optimization.
• codemode: Streamlined profile. 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 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: 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 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 sys schema 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.

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 are defined statically for instant boot times.

---

Explore Related Topics

• Capacity-Planning
• Tool-Filtering
• Code-Mode
• Configuration