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.
• 19 Observability Resources and 19 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

• Implemented OAuth 2.1 validator middleware for enhanced security.
• Allowed mask data alias validation at the MCP boundary (Security).
• Made server config action required and fixed audit default limit (Admin).
• Added strict validation and aliases for user and host summaries (Sysschema).
• Enforced strict error responses returning {success: false, error, code, category, suggestion, recoverable} instead of raw MCP exceptions.
• Implemented graceful nonexistent table handling ({exists: false, table}).