MySQL MCP Architecture

MySQL MCP is a lightweight HTTP-based MCP server that provides read-only database access to MariaDB/MySQL instances. It exposes 9 tools for schema inspection, query execution, and server diagnostics through both a simple REST API and the MCP JSON-RPC protocol.

The server acts as a safe database gateway for AI agents, enforcing read-only query restrictions (SELECT, SHOW, DESCRIBE, EXPLAIN only) and identifier sanitization to prevent SQL injection. It integrates with the rod-server MCP Proxy, allowing Claude Code and other MCP clients to query MariaDB databases without direct database credentials.

Key design decision: This server uses HTTP transport (not stdio) so it can run as a long-lived Docker container behind the MCP Proxy, which aggregates multiple MCP backends under a single authenticated endpoint.

MCP Tools

Transport

HTTP

Runtime

Node.js 20

Port

3201

Security

Read-only

Source Files

2. Runtime Architecture

Diagram A: Runtime Request Flow

Request Flow

Claude Code sends an MCP tool call (e.g., db_query) via stdio to the MCP Proxy.
The MCP Proxy (mcp.home) routes the call to the mysql-mcp container over HTTP on port 3201, using the POST /call endpoint.
MySQL MCP validates the request (read-only check, identifier sanitization), acquires a connection from the pool, and executes the query against MariaDB.
Results are returned as MCP-formatted JSON content (array of {type: "text", text: ...}).

Direct HTTP access (dashed line) is also supported for scripts and debugging via curl http://mysql-mcp:3201/call from within the Docker network.

5. Public Interfaces

HTTP Endpoints

Method	Path	Description
`GET`	`/health`	Health check with DB connectivity status
`GET`	`/tools`	List all available MCP tools with schemas
`GET`	`/docs`	API documentation with examples
`POST`	`/call`	Call a tool: `{"tool": "name", "params": {}}`
`POST`	`/tools/list`	MCP JSON-RPC tool listing
`POST`	`/tools/call`	MCP JSON-RPC tool call

MCP Tools (9 total)

Tool	Description	Required Params	Optional Params
`db_list_databases`	List all databases on the MariaDB server	--	--
`db_list_tables`	List all tables in a specific database	`database`	--
`db_describe_table`	Describe column structure, types, and keys of a table; includes CREATE TABLE statement	`database`, `table`	--
`db_query`	Execute a read-only SQL query (SELECT, SHOW, DESCRIBE, EXPLAIN only)	`database`, `query`	`limit` (default 100, max 1000)
`db_table_stats`	Row counts and size statistics for all tables in a database	`database`	--
`db_foreign_keys`	List foreign key relationships for a table or entire database	`database`	`table`
`db_indexes`	List indexes on a table	`database`, `table`	--
`db_server_status`	Server status: version, uptime, connections, total queries	--	--
`db_process_list`	Show currently running queries and processes	--	--

Example Usage

# List databases
curl -s http://mysql-mcp:3201/call \
  -H "Content-Type: application/json" \
  -d '{"tool":"db_list_databases","params":{}}'

# Query a table
curl -s http://mysql-mcp:3201/call \
  -H "Content-Type: application/json" \
  -d '{"tool":"db_query","params":{"database":"nextcloud","query":"SELECT COUNT(*) FROM oc_users"}}'

# Via MCP Proxy (authenticated)
curl -sk https://mcp.home/mcp/database/call \
  -H "X-API-Key: $MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"db_server_status","params":{}}'

6. Repository Structure

docker/mysql-mcp/
  Dockerfile          # Node.js 20 Alpine, production build
  package.json        # Dependencies: express, mysql2
  src/
    index.js          # Entire server (595 lines): tools, handlers, HTTP endpoints

Component Classification

Component	Classification	Role
`src/index.js`	Primary	Single-file server containing: tool definitions (9 tools), SQL handler logic with read-only validation and identifier sanitization, connection pool management, Express HTTP server with 6 endpoints, and graceful shutdown handling.
`Dockerfile`	Secondary	Alpine-based Node.js 20 image. Production-only `npm install`, runs as non-root `node` user, healthcheck on `/health`.
`package.json`	Auxiliary	Declares two runtime dependencies and the `npm start` script.

7. Deployment & Operations

Container Details

Property	Value
Container name	`mysql-mcp`
Base image	`node:20-alpine`
Exposed port	`3201`
Network	`hosting_web` + `hosting_backend`
User	`node` (non-root)
Healthcheck	`GET /health` every 30s, 3s timeout, 3 retries
Restart policy	`unless-stopped`

Environment Variables

Variable	Default	Purpose
`PORT`	`3201`	HTTP listen port
`MYSQL_HOST`	`mariadb`	MariaDB hostname (Docker service name)
`MYSQL_PORT`	`3306`	MariaDB port
`MYSQL_USER`	`rodchemist`	Database user
`MYSQL_PASSWORD`	(from .env)	Database password

Health Monitoring

# Check container health
docker inspect mysql-mcp --format='{{.State.Health.Status}}'

# Check health endpoint
curl -s http://mysql-mcp:3201/health | jq .

# View logs
docker logs -f mysql-mcp

Connection Pool Configuration

Setting	Value
Connection limit	5
Queue limit	10
Connect timeout	10,000 ms
Keep-alive	Enabled (10s initial delay)
Wait for connections	Yes

8. Dependencies

Runtime Dependencies

Package	Version	Purpose
`express`	`^4.18.0`	HTTP server framework for REST and MCP JSON-RPC endpoints
`mysql2`	`^3.14.0`	MariaDB/MySQL client with Promise API and connection pooling

Infrastructure Dependencies

Service	Relationship	Required
MariaDB (`mariadb:3306`)	Database backend -- all tools query this server	Required
MCP Proxy (`mcp-proxy`)	Upstream aggregator -- routes MCP calls to this backend	Optional
Docker network (`hosting_backend`)	Must share network with MariaDB container	Required

Minimal dependency footprint: Only 2 npm packages. No build tools, no TypeScript, no bundler. The entire server is a single 595-line JavaScript file.

9. Constraints & Risks

Item	Severity	Details
Read-only enforcement	Mitigated	Query validation checks for SELECT/SHOW/DESCRIBE/EXPLAIN prefixes. However, this is a string-prefix check, not a SQL parser. Edge cases with CTEs (`WITH`) are allowed, which could theoretically be abused. The database user should also have read-only grants as a defense-in-depth measure.
Hardcoded credentials	Warning	Default credentials (`rodchemist` / password) are hardcoded as fallbacks in the source. These are overridden by environment variables in production, but the defaults should be removed.
No authentication	Warning	The HTTP server has no authentication. It relies on Docker network isolation and the MCP Proxy's API key authentication for access control. Direct HTTP access is possible from any container on the same Docker network.
Single-file architecture	Acceptable	All logic is in one 595-line file. This is appropriate for the server's limited scope (9 tools, 6 endpoints) but would need refactoring if significantly more tools are added.
Connection pool size	Acceptable	Pool limit of 5 connections is sufficient for the expected low-concurrency MCP usage pattern. Queue limit of 10 provides backpressure.

Generated by /repo-architecture v2.0.0 on 2026-03-22. This document is auto-generated — regenerate after significant changes.