> ## 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.
</Warning>

## 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}
```

| 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';
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, 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.
</Warning>

<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.
</Note>

## See also

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