MCP MySQL Sentinel

Controlled database access for AI agents.

Connect agents to MySQL without turning database access into an unrestricted capability.

A practical, self-hosted MCP reference implementation combining token authentication, role-based SQL permissions, statement checks, bounded query results, and an audit trail.

A Veritiana open-source AI integration reference · Explore Veritiana · Website

Python 3.11+ · FastMCP / MCP 1.30.0 · Streamable HTTP · MySQL · PyMySQL · Apache-2.0

The problem

AI agents are useful when they can work with real information. But connecting an agent directly to a database raises difficult questions:

• Who is requesting this operation?

• Which SQL statements should that identity be allowed to execute?

• How do we prevent an agent with a read-only task from receiving broad database privileges?

• How can operators inspect successful, rejected, and failed requests?

MCP MySQL demonstrates one explicit answer: put a policy-aware MCP interface between the agent and MySQL. Instead of treating an agent as an all-powerful database user, the service authenticates each request, applies a configured role policy, checks the requested SQL, executes it through a dedicated database account, and writes an audit record.

The goal is not to make an LLM a database administrator. The goal is to make access visible, constrained, and understandable.

Related MCP server: tokenlite-mysql-mcp

See it in action

These are behavior examples, not an online demo. Never run write-operation demonstrations against valuable production data.

What makes this project useful

Architecture: five controlled stages

1. Agent / MCP client — invokes an exposed tool, such as query(sql).

2. MCP transport — FastMCP exposes a Streamable HTTP endpoint.

3. Identity and policy — the server authenticates the bearer token and resolves the user's role from YAML configuration.

4. SQL guard — deterministic checks decide whether the submitted statement is admissible under that role.

5. Database execution — PyMySQL sends permitted SQL to MySQL, subject to the database user's actual grants. Results are returned as structured data; outcomes are audited.

Defense in depth, not a sandbox. The guard uses lexical SQL checks, not a complete SQL parser. It must never replace least-privilege MySQL accounts, network restrictions, encrypted transport, review of SQL privileges, and security testing. Its read/write role names describe application-level policy, not independently enforced MySQL identities.

Available MCP tools

Who should explore it?

AI agent developers looking for a concrete database integration pattern; backend engineers adding MCP to existing MySQL-backed applications; software architects studying authorization and execution boundaries; and DevOps / security engineers experimenting with traceable self-hosted agent tools.

This is especially useful as a reference architecture to inspect, modify, and test. It is not advertised as a turnkey enterprise security gateway.

Quick start

Prerequisites: Python 3.11+, access to a MySQL server, and a dedicated database account with the least privileges needed for your demonstration.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'

Prepare local settings and access control:

mkdir -p "$HOME/.config/mcp-mysql"
cp .env.example "$HOME/.config/mcp-mysql/.env"
cp config/roles.example.yaml "$HOME/.config/mcp-mysql/roles.yaml"
chmod 600 "$HOME/.config/mcp-mysql/.env" "$HOME/.config/mcp-mysql/roles.yaml"

Edit .env and set your real MySQL connection settings and writable paths:

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=mcp
MYSQL_PASSWORD=change-me
MYSQL_DATABASE=app
MYSQL_TIMEOUT_MS=10000
MCP_HOST=127.0.0.1
MCP_PORT=8000
MCP_PUBLIC_URL=http://127.0.0.1:8000
MCP_ROLES_FILE=/home/YOUR_USER/.config/mcp-mysql/roles.yaml
MCP_AUDIT_FILE=/home/YOUR_USER/.config/mcp-mysql/audit.jsonl

Replace YOUR_USER, credentials, and paths before starting. The original example .env contains deployment-style /etc and /var/log paths; those need appropriate permissions if retained.

Generate a token and store its hash in your role configuration:

mcp-mysql-token

The command prints a bearer token and its SHA-256 digest. Store the digest under the desired user's token_sha256 in roles.yaml; deliver the raw bearer token privately to its intended user. The sample file contains placeholders and is not runnable unchanged.

Run the server:

mcp-mysql

The service starts a Streamable HTTP MCP endpoint on the configured host and port. Connect with a compatible MCP client configured with the server URL and bearer authorization. Client-specific JSON varies by client; do not assume one universal client configuration.

Example policy

The repository includes config/roles.example.yaml:

roles:
  readonly:
    allow: [SELECT, WITH, SHOW, DESCRIBE, EXPLAIN]
    max_rows: 200
  developer:
    allow: [SELECT, WITH, SHOW, DESCRIBE, EXPLAIN, INSERT, UPDATE, DELETE]
    max_rows: 200
  migrator:
    allow: [SELECT, SHOW, DESCRIBE, CREATE, ALTER]
    max_rows: 50

These are sample application roles; the actual MySQL login configured through MYSQL_USER is shared by server-side execution. MySQL privileges must be configured separately and can be more restrictive than these example policies.

Security boundary and limitations

This project deliberately makes its trade-offs visible:

• SQL inspection is lexical. Prefix verbs and word/phrase checks can miss database-specific semantics; do not treat them as authoritative SQL parsing or full read-only proof.

• Database privileges remain decisive. Use a separate limited-privilege MySQL account, avoid administrative grants, and isolate demonstration environments.

• Treat credentials as secrets. Never commit .env, roles.yaml with real token hashes, raw tokens, or audit records containing sensitive SQL.

• Audit can contain SQL text. Control log access, rotation, retention and redaction according to your environment.

• Transport needs deployment security. Bind locally for development; do not expose the example service publicly without a properly secured TLS/reverse-proxy and network policy.

• The reference is not a security certification. Review and test it before any production deployment. Database data returned through tools must be treated as untrusted content rather than instructions to the agent.

Project layout

mcp-mysql/
├── README.md
├── docs/
│   └── images/
│       └── architecture.png
├── config/
│   └── roles.example.yaml
├── src/mcp_mysql/
│   ├── server.py         # MCP transport and tools
│   ├── auth.py           # Bearer-token verification
│   ├── config.py         # Environment and role loading
│   ├── sql_guard.py      # Lexical policy checks
│   ├── db.py             # MySQL execution and bounds
│   ├── audit.py          # JSONL audit writer
│   └── make_token.py     # Token generator
├── tests/
│   └── test_sql_guard.py
├── .env.example
└── pyproject.toml

Validate the implementation

python -m pytest

This repository includes SQL-guard unit tests; passing them does not constitute penetration testing or end-to-end production assurance.

Part of Veritiana

Veritiana builds practical, inspectable implementations of AI systems architecture. Across agent workflows, simulation, memory systems, and integrations, the emphasis is on explicit boundaries, real code, and repeatable experimentation.

MCP MySQL contributes a focused AI Integration Pattern: controlled MCP access to relational data.

Explore related work:

• Claude Agent Development Kit — structured Claude Code agent workflows.

• Claude Chief of Staff — read-only agent with source validation and auditable output.

• Agent Glasses Memory Core — event processing and structured agent memory.

• CouncilMind CE — local-first multi-agent orchestration.

• AURA — autonomous multi-agent simulation.

• BabyGPT Engine — browser-native Transformer experimentation.

• Tenrec — persistent agent runtime.

Veritiana: GitHub · Website

Project status

Initial reference implementation. It is suited to learning, local experimentation, and evaluation in controlled environments. Before public production deployment, extend validation, threat modeling, SQL parsing/policy enforcement, logging safeguards, and operational hardening.

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full terms. You may use, modify, and distribute this project under the conditions of that license.