Performance Tuning

Performance Tuning

Value Proposition Optimize throughput and reduce latency for your AI workloads. mysql-mcp empowers you to optimize agent performance. We provide highly optimized Code Mode token efficiency, intelligent connection pooling, and deep query diagnostics. Read the full value proposition.

---

Optimize Connection Pooling

Maximize your throughput. The mysql2 connection pool configuration is a critical lever that 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.
• 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 both the HTTP Transport layer (governed by MCP_RATE_LIMIT_MAX) and Code Mode (governed by CODEMODE_RATE_LIMIT_MAX). Crucially, the system features a graceful fallback to in-memory rate limiting if the Redis instance becomes unavailable.

This distributed rate limiting is an essential safeguard for database resources, ensuring equitable access and uncompromised stability in high-concurrency, multi-agent enterprise environments.

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

Code Mode (mysql_execute_code) optimizes agent operations, delivering token savings over individual tool calls while accelerating 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 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 via the Prometheus /metrics endpoint and visualized 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 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 estimation	Content-type-aware
Code Mode sandbox init	Optimized cold start	isolated-vm cold start
Logger	High-throughput	Zero work when below minLevel

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