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.

Diagnosing Performance Bottlenecks

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

• mysql_performance_analysis: A comprehensive diagnostic prompt to guide analysis of query execution and performance metrics.
• Other specialized prompts are dynamically available to analyze index usage and table statistics.

Follow the Workflow

Leverage the diagnostic prompts to systematically identify 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 durability, 2 for throughput (risk: 1s data loss on crash)	mysql_read_query (e.g. SHOW VARIABLES)
innodb_log_file_size	Large enough to hold 1–2 hours of writes	mysql_read_query (e.g. SHOW VARIABLES)
Buffer pool hit rate	Target ≥99%	mysql_read_query (e.g. SHOW STATUS)

Note

Tune these server-level settings in your MySQL configuration file or via SET GLOBAL. Use the mysql_read_query tool to query system variables and 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 benchmarks confirm sub-millisecond overhead on critical paths:

Metric	Performance
parseToolFilter	~32,000-62,000 ops/sec
CodeModeSandbox.create cold start	~2.78M ops/sec
Sandbox dispose	~2.37M ops/sec
SandboxPool init	~109k ops/sec
Set.has tool check	~4.4M ops/sec
Map.get reverse lookup	~4.5M ops/sec
Map.get URI match	~5.1M ops/sec
validateCode safe short	~173k ops/sec
validateCode blocked	~298k ops/sec
checkRateLimit	~205k ops/sec
sanitizeResult small payload	~1.49M ops/sec
prompt schema parse	~1.3M ops/sec

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

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