Performance Tuning

Performance Tuning

Value Proposition Optimize throughput and reduce latency across all database interactions with sub-millisecond execution path overhead. Empower your AI agents with enterprise-grade connection pooling, intelligent query batching, and comprehensive query diagnostics to ensure platform stability 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	MYSQL_POOL_TIMEOUT	30000	How long to wait for a free connection
queueLimit	--pool-queue-limit	MYSQL_POOL_QUEUE_LIMIT	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. Under the MCP v2 stateless HTTP transport (NodeStreamableHTTPServerTransport), 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.

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. Note that the standard stdio transport is local and NOT subject to HTTP rate limits, but Code Mode within stdio still enforces rate limits locally. 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 --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.

Expertly Diagnosing Performance Bottlenecks

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

• mysql_performance_analysis: An exhaustive diagnostic prompt to expertly guide the analysis of intricate query execution and vital performance metrics.
• Other specialized prompts dynamically emerge to seamlessly analyze index utilization and table statistics.

Seamlessly Follow the Workflow

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

InnoDB Tuning

Setting	Recommendation	Tool / Query to Monitor
innodb_buffer_pool_size	70–80% of available RAM on dedicated servers	mysql_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_query (e.g. SHOW VARIABLES)
innodb_log_file_size	Ample capacity to sustain 1–2 hours of write operations	mysql_query (e.g. SHOW VARIABLES)
Buffer pool hit rate	Target a robust ≥99%	mysql_query (e.g. SHOW STATUS)

Note

Tune these critical server-level settings elegantly in your MySQL configuration file or via SET GLOBAL. Leverage the mysql_query tool to seamlessly 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 HTTP transport (--transport http) and the metrics export flag (--metrics-export prometheus) or the MCP_METRICS_EXPORT=prometheus environment variable.

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	Millions ops/sec
Sandbox dispose	Millions ops/sec
SandboxPool init	Hundreds of thousands ops/sec
Set.has tool check	Millions ops/sec
Map.get reverse lookup	Millions ops/sec
Map.get URI match	Millions ops/sec
validateCode safe short	Hundreds of thousands ops/sec
validateCode blocked	Hundreds of thousands ops/sec
checkRateLimit	Hundreds of thousands ops/sec
sanitizeResult small payload	Millions ops/sec
prompt schema parse	Millions ops/sec

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

Note

Standard 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