> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# vsql_mcp extension for MySQL

> The vsql_mcp extension serves MySQL to AI agents over the Model Context Protocol, with schema browsing, read-only queries, a table allowlist, and row caps.

`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](https://github.com/villagesql/vsql-mcp) |
| **License** | GPL-2.0 |
| **Written in** | Rust |
| **Capability** | Preview |

> [!WARNING]
>
> 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:

```sql theme={null}
INSTALL EXTENSION vsql_mcp;
```

Confirm it is there:

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_mcp';
```

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

The build instructions are in the
[repository](https://github.com/villagesql/vsql-mcp).

## What it adds

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

```sql theme={null}
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,"starting":false}
```

`starting` is `true` from the moment `vsql_mcp.vsql_mcp_enabled` is set `ON`
until the background worker's next wakeup, which comes every 25 ms. A call in
that window can report `"enabled":false` too, since the listener has not bound
yet.

| 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:

```sql theme={null}
SET GLOBAL vsql_mcp.schema = 'shop';
SET GLOBAL vsql_mcp.db_url = 'mysql://agent:secret@127.0.0.1:3306/shop';
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.

> [!WARNING]
>
> The account in `db_url` sets the ceiling on what an agent can do, and every
> database account can read `db_url`, password included, with `SHOW VARIABLES`,
> 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; `SHOW VARIABLES` shows that token to every account too.

> [!NOTE]
>
> 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.

## See also

* [Serving MySQL to AI agents over MCP](https://villagesql.com/docs/guides/mysql-ai-agents-mcp.md) — connecting an agent and what it can see
* [Managing extensions](https://villagesql.com/docs/mysql-8.4/0.0.6/managing.md) — how extension settings are read and written
* [Preview capabilities](https://villagesql.com/docs/mysql-8.4/0.0.6/preview-capabilities.md) — what the preview flag turns on and what it promises
* [Available extensions](https://villagesql.com/docs/mysql-8.4/0.0.6/extensions.md) — the full catalog
* [villagesql/vsql-mcp](https://github.com/villagesql/vsql-mcp) — source, client setup, and the known limitations


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.