Performance Tuning

Performance Tuning

Value Proposition Optimize throughput and reduce latency across all database interactions with near-zero overhead. Empower your AI agents with enterprise-grade connection pooling, intelligent query batching, and comprehensive query diagnostics to ensure robust stability and performance scale across multi-agent ecosystems. Read the full value proposition.

---

Optimizing Connection Pooling

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

Key Parameters

Configuration	CLI Flag	Environment Variable	Default	Description
connectionLimit	--pool-size	MYSQL_POOL_SIZE	10	Max simultaneous connections
acquireTimeout	--pool-timeout	(CLI / Config only)	30000	How long to wait for a free connection
queueLimit	--pool-queue-limit	(CLI / Config only)	0 (∞)	Max requests waiting in queue

Note

For execution limits, please note the distinction between MYSQLSH_TIMEOUT (shell operations) and MCP_REQUEST_TIMEOUT (global request timeout).

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 invocation operates cleanly over streamable HTTP requests while leveraging the shared MySQL pool. 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.

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. Note that the standard stdio transport is local and NOT subject to HTTP rate limits, but Code Mode within stdio still enforces CODEMODE_RATE_LIMIT_MAX (globally via Redis if configured, or locally in-memory). 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, ensuring balanced compute access and ensuring platform stability in multi-agent environments.

Tip

Monitor Redis Performance: To visualize cache hit rates, query latencies, and blocked clients for the rate-limiting subsystem, see the Redis Telemetry Datadog dashboard documented in Observability. For a comprehensive guide to the Redis rate limiting architecture, fallback behavior, and test isolation, see Redis Integration.

Contextual Tool Filtering

Exposing the full tool library simultaneously can unnecessarily increase token overhead.

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 --allowed-io-roots "C:/temp,/tmp" --tool-filter "starter"

See Tool Filtering for the complete list of groups and shortcuts.

Improve Token and Execution Efficiency

Code Mode (mysql_execute_code) accelerates agent operations, reducing token overhead by intelligently 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.
• Maximize Token and Execution Efficiency: Batching complex data pipelines reduces token usage, minimizes network latency of multi-step reasoning loops, and returns only the final answer from the sandboxed environment.

Rule of Thumb: Use Code Mode if a question requires more than two sequential queries.

AI-Driven Root Cause Analysis: Diagnosing Performance Bottlenecks

Diagnose slow queries and optimize execution plans using our comprehensive diagnostic prompts rather than relying on standalone tools. These prompts guide the entire analysis process.

• mysql_performance_analysis: A diagnostic prompt to guide the analysis of query execution and performance metrics.
• Other specialized prompts dynamically emerge to analyze index utilization and table statistics.

Follow the Workflow

Leverage these diagnostic prompts to systematically pinpoint slow queries, analyze query execution plans, check index statistics, and verify optimization improvements.

InnoDB Tuning

Setting	Recommendation	Tool / Query to Monitor
innodb_buffer_pool_size	70–80% of available RAM on dedicated servers	mysql_read_query (e.g. SHOW ENGINE INNODB STATUS)
innodb_flush_log_at_trx_commit	1 for uncompromising durability, 2 for peak throughput (risk: 1s data loss on crash)	mysql_read_query (e.g. SHOW VARIABLES)
innodb_log_file_size	Ample capacity to sustain 1–2 hours of write operations	mysql_read_query (e.g. SHOW VARIABLES)
Buffer pool hit rate	Target a robust ≥99%	mysql_read_query (e.g. SHOW STATUS)

Note

Tune these critical server-level settings in your MySQL configuration file or via SET GLOBAL. Leverage the mysql_read_query tool to query system variables and monitor status.

Monitor Telemetry Real-Time

Telemetry can be monitored in real-time via the Prometheus /metrics endpoint. Visualize them in the Grafana dashboard.

Important

The /metrics endpoint requires the metrics export flag (--metrics-export prometheus) or the MCP_METRICS_EXPORT=prometheus environment variable. It can be exported natively under the HTTP transport (--transport http) or as a standalone background server when using the stdio transport.

For full setup instructions, see Observability & Telemetry.

Verify Performance Characteristics

Our internal benchmarks consistently demonstrate exceptional sub-millisecond overhead on critical execution paths. (Note: The following metrics reflect point-in-time reference benchmarks and may vary based on hardware, environment, and specific version implementations.)

Metric	Performance Range (Reference)
parseToolFilter	Tens of thousands ops/sec
CodeModeSandbox.create cold start	Sub-millisecond overhead
Sandbox dispose	Sub-millisecond overhead
SandboxPool init	Hundreds of thousands ops/sec
Set.has tool check	Sub-millisecond overhead
Map.get reverse lookup	Sub-millisecond overhead
Map.get URI match	Sub-millisecond overhead
validateCode safe short	Hundreds of thousands ops/sec
validateCode blocked	Hundreds of thousands ops/sec
checkRateLimit	Hundreds of thousands ops/sec
sanitizeResult small payload	Sub-millisecond overhead
prompt schema parse	Sub-millisecond overhead

Clone the source repository and run pnpm run bench locally to generate precise, up-to-date results on your bespoke hardware configuration.

Note

Zod validation schemas are defined statically for fast boot times.

---

Explore Related Topics

• Capacity Planning - System capacity and scaling
• Tool Filtering - Custom tool filtering
• Code Mode - Code Mode API documentation
• Configuration - General configuration