vsql_mcp extension for MySQL

vsql_mcp serves the database to AI agents over the Model Context Protocol, from a listener inside the server process. An agent can list schemas, describe tables, and run read-only queries. Writes stay off until you turn them on, and the query path runs through a database account you nominate, so the agent gets exactly the access you granted that account.


Maintainer	VillageSQL
Source and full documentation	villagesql/vsql-mcp
License	GPL-2.0
Written in	Rust
Capability	Preview

This extension uses preview capabilities, four of them, so the server must be started with --vsql_allow_preview_extensions=ON. INSTALL EXTENSION is refused otherwise.

Install

vsql_mcp is not bundled with the server, so build it from the repository first and copy the resulting vsql_mcp.veb into the directory named by the veb_dir system variable. Then install it:

INSTALL EXTENSION vsql_mcp;

Confirm it is there:

SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_mcp';

+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_mcp       |
+----------------+

The build instructions are in the repository.

What it adds

It adds one SQL function, info(), which reports what the listener is doing. Everything else is configuration and MCP traffic.

SELECT CONVERT(info() USING utf8mb4) AS info;

{"enabled":false,"http_port":0,"https_port":0,"port":3100,"protocol_version":"2025-06-18","schema":"","sessions_active":0,"ssl_port":3143}

Setting	Default	What it controls
`vsql_mcp.vsql_mcp_enabled`	`OFF`	Whether the listener runs
`vsql_mcp.schema`	empty	The database it serves
`vsql_mcp.db_url`	empty	The account the query, write, and explain tools connect as
`vsql_mcp.allowed_tables`	empty	Which tables those tools may touch
`vsql_mcp.allow_write`	`OFF`	Whether the write tool exists at all
`vsql_mcp.max_rows`	`1000`	The row cap on a single result
`vsql_mcp.query_timeout`	`30`	How long one query may run, in seconds
`vsql_mcp.port`	`3100`	The HTTP port
`vsql_mcp.ssl_port`	`3143`	The HTTPS port
`vsql_mcp.ssl_cert`, `vsql_mcp.ssl_key`	empty	The certificate and key for HTTPS
`vsql_mcp.require_auth`	`OFF`	Whether a request must carry a bearer token
`vsql_mcp.bearer_token`	empty	That token
`vsql_mcp.session_ttl`	`1800`	How long an idle agent session is kept, in seconds

Example

Point the listener at a database and start it:

SET GLOBAL vsql_mcp.schema = 'shop';
SET GLOBAL vsql_mcp.db_url = 'mysql://agent:secret@127.0.0.1:3306';
SET GLOBAL vsql_mcp.allowed_tables = 'orders,customers';
SET GLOBAL vsql_mcp.vsql_mcp_enabled = ON;

Agents then connect to http://127.0.0.1:3100 over MCP Streamable HTTP. The repository carries the client configuration for each agent.

The account in db_url sets the ceiling on what an agent can do, so grant it the least it needs and leave allow_write off until you mean it. Turn on require_auth with a bearer token before the port is reachable from anywhere but localhost.

A setting written with SET PERSIST survives a restart, but UNINSTALL EXTENSION deletes it. After an uninstall and reinstall every setting is back at its default, and no restart brings the old value back.

Getting Started

Server Development

Using Extensions

Creating Extensions

Install

What it adds

Example

See also

​Install

​What it adds

​Example

​See also

Install

What it adds

Example

See also