Architecture

Architecture

For the complete architectural layout, logic flows, and module tree, please see the code-map.md file in the main repository.

The mysql-mcp project uses the Adaptive Instruction Architecture, where modular markdown files (src/constants/server-instructions/*.md) are compiled into a single build-time artifact, transmitting a slim pointer string to the client and exposing dynamic help via mysql://help resources.

Core Capabilities

• 241 Specialized Tools distributed across 28 Tool Groups to handle everything from CRUD to Spatial analysis.
• 16 Shortcuts (Tool Filtering) to easily configure context-friendly setups.
• 49 Observability Resources and 28 AI-Powered Prompts to empower proactive agent workflows.

Infrastructure & Transport

• Code Mode Execution: Powered by an isolated-vm sandbox, massively reducing token overhead with a strict 100KB payload cap and built-in rate limiting.
• Supported Transports: Seamlessly switch between stdio, http (Streamable HTTP /mcp), and sse (Legacy /sse).
• Authentication: Enterprise-ready security with Simple Bearer Token or full OAuth 2.1 (RFC 9728/8414) via Keycloak.

Recent Updates

• codemode has been multiplexed to all tools to drastically reduce token consumption.
• Implemented OAuth 2.1 validator middleware and enhanced MCP boundary validation.
• Guardrails introduced against hallucination across coordinator workflows.
• Allowed database-wide index audit in indexRecommendation.
• Expanded test coverage across admin, backup, preprocess schemas, and HTTP transport.
• Enforced strict error responses returning {success: false, error, code, category, suggestion, recoverable} instead of raw MCP exceptions.