Performance Tuning

Enterprise Performance Tuning

Value Proposition Maximize throughput and minimize latency for high-demand AI workloads. mysql-mcp is designed for scale. It equips your agents with intelligent connection pooling. It includes token-optimized Code Mode and deep query diagnostics. This guarantees consistently reliable performance across diverse, concurrent multi-agent workloads. Read the full value proposition

---

Optimize Intelligent Connection Pooling

Fine-tune the underlying mysql2 connection pool configuration. This is a critical lever. It directly dictates the ceiling of concurrent tool execution. It impacts overall agent responsiveness.

Key Parameters

Parameter	Default	CLI	Environment Variable	Effect
connectionLimit	10	--pool-size	MYSQL_POOL_SIZE	Max simultaneous connections
acquireTimeout	10000	--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.
• HTTP Transport (--transport 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.

Enforce Distributed Rate Limiting

Configuring REDIS_URL harmonizes and synchronizes rate limits seamlessly. This applies across the HTTP Transport layer and Code Mode sandboxes. These limits are strictly governed by MCP_RATE_LIMIT_MAX and CODEMODE_RATE_LIMIT_MAX. Our architecture features a highly resilient, graceful fallback to in-memory rate limiting. It activates instantly should the Redis instance experience temporary unavailability.

This distributed rate limiting strategy acts as an essential safeguard for critical database resources. It guarantees equitable compute access. It ensures uncompromised platform stability in dense multi-agent environments.

Strategize Contextual Tool Filtering

Indiscriminately exposing the full tool library to an LLM is a problem. It expands the system prompt payload unnecessarily. This introduces steep token costs and artificially inflates response latency.

Understand the Impact of Filters

The robust --tool-filter CLI flag empowers you to selectively mount precise tools. You mount only what your specific workload demands.

Avoid mounting the entire toolset simultaneously, as it incurs significant performance penalties. Strategically leverage specialized presets like starter or dba-monitor. This streamlines your agent's context and drives optimal token efficiency.

# 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 Token and Execution Efficiency

Code Mode (mysql_execute_code) optimizes agent operations, reducing token overhead by batching complex data pipelines.

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: The script returns only the final answer, saving tokens.
• 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.

Diagnose 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)
mysql_explain_analyze	Analyze query execution plans (EXPLAIN ANALYZE)
mysql_slow_queries	Identify and analyze slow queries from the performance schema
mysql_index_usage	Analyze index usage statistics to find unused or inefficient indexes
mysql_table_stats	Retrieve detailed table statistics and access patterns
mysql_buffer_pool_stats	Monitor InnoDB buffer pool hit rates and memory usage

Follow the Workflow

1. Identify slow queries via mysql_slow_queries.
2. Analyze the plan with the mysql_explain_analyze tool for actual execution metrics.
3. Check for index usage with mysql_index_usage and mysql_table_stats.
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_variables
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. Use mysql_show_variables and mysql_show_status to query system variables and status.

Monitor Telemetry Real-Time

System latency and active sessions can be monitored in real-time. Do this via the Prometheus /metrics endpoint. Visualize them 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 sub-millisecond 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 estimation	Content-type-aware
Code Mode sandbox init	Optimized cold start	isolated-vm cold start
Logger	High-throughput	Zero work when below LOG_LEVEL

Clone the source repository and run pnpm run bench locally for full results on your hardware.

Note

Zod schemas are defined statically for near-instantaneous boot times.

---

Explore Related Topics

• Capacity Planning
• Tool Filtering
• Code Mode
• Configuration