Performance Tuning

Enterprise Performance Tuning

Value Proposition Leverage hyper-optimized execution pathways for zero-latency AI database interactions. Designed for scale, mysql-mcp equips your agents with intelligent connection pooling, token-optimized Code Mode, and deep query diagnostics to provide guaranteed maximum throughput for concurrent agent swarms. 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 synchronizes rate limits across the HTTP Transport layer and Code Mode sandboxes, governed by MCP_RATE_LIMIT_MAX and CODEMODE_RATE_LIMIT_MAX. The architecture includes a graceful fallback to in-memory rate limiting if the Redis instance becomes unavailable.

This distributed rate limiting strategy acts as an essential safeguard for critical database resources, guaranteeing equitable compute access and ensuring platform stability in 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 --tool-filter CLI flag allows you to selectively mount tools, so you only expose what your specific workload demands.

Avoid mounting the entire toolset simultaneously to prevent performance penalties. Leverage specialized presets like starter or dba-monitor to streamline your agent's context and improve 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) and the metrics export flag (--metrics-export prometheus).

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