VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
vsql_mcp 扩展去掉了这一层:它在 VillageSQL 进程内部运行一个 Model Context Protocol 服务器,所以任何 MCP 客户端都可以直接发现架构并运行查询。
vsql_mcp 做什么
vsql_mcp 是一个 Rust 扩展,从服务器进程内的后台工作线程通过 Streamable HTTP 传输(规范修订版 2025-06-18)提供 MCP 服务。它暴露六个工具:list_schemas、list_tables、describe_table、query、explain 和 write。write 工具只有在您启用它之后才会出现,它默认是禁用的。
vsql_mcp 是预览扩展。它使用 VEF 预览能力 thread_worker、sys_var、status_var 和 sql_query,所以服务器必须在允许预览扩展的状态下启动:
创建示例数据
本指南使用一个专用数据库和一个小的posts 表,让代理有真实的东西可查。
安装扩展
创建最小权限账户
vsql_mcp 运行的大多数工具调用,包括 query、write、explain 和表 DDL 资源,都通过一个回环连接、使用您配置的账户访问服务器。只有 list_schemas、list_tables 和 describe_table 在进程内运行,不需要该账户。请创建一个专用账户,范围限定在本指南使用的这一个数据库,并且只有 SELECT:
vsql_mcp 自身的防护措施(下文介绍)是在这些授权之上执行的,而不是取而代之。
配置并启用服务器
所有vsql_mcp 设置都是 SET GLOBAL vsql_mcp.<name> 变量。把 db_url 指向上面创建的账户,把服务器限定到一个架构,要求 bearer 令牌,然后打开它:
http_port 显示为 3100,即默认值。服务器在 http://127.0.0.1:3100/mcp 上监听,并且只绑定到 127.0.0.1。它从不直接接受远程连接;如果您需要远程访问,把它放在反向代理之后是您自己的责任。
验证服务器能说 MCP
在连接真实客户端之前,先用 MCP 握手直接验证 HTTP 端点。没有 bearer 令牌的请求会被拒绝:initialize 成功并返回一个 Mcp-Session-Id 头:
notifications/initialized,然后使用 initialize 响应中的会话 ID 列出可用的工具:
write 不在其中,因为 allow_write 仍然是 OFF,所以此刻连接的代理不会围绕一个它无法使用的工具来做计划。
通过 MCP 调用工具
list_tables 显示被暴露架构中的那一个表:
query 运行一条 SELECT 并返回实际的行:
posts 表中真实的示例数据,通过 MCP 协议而不是直接的 SQL 连接返回。
query 只接受单条只读语句。其他任何东西都会在到达数据库之前被拒绝:
连接真实客户端
上面的步骤证明服务器对原始 HTTP 客户端的响应是正确的。要证明代理确实能使用它,请把服务器注册到 Claude Code,并让它管理会话:local config 把该服务器的范围限定在这一个项目。改为传入 --scope user 可以让它在每个项目中都可用。claude mcp list 显示连接状态:
initialize 握手,协商了一个会话,并确认服务器能通过 MCP 应答,这就是本指南用 SET GLOBAL 语句配置并在上面手动测试过的同一台服务器。从这里开始,向代理询问关于 mcp_guide 数据库的问题会经由 list_tables、describe_table 和 query,与用 curl 演示的完全一样。
vsql_mcp 没有 stdio 传输。服务器运行在数据库进程内部,所以不存在供客户端派生的子进程。只会说 stdio 的客户端,或者经由供应商云代理、无法访问 127.0.0.1 的远程客户端,需要在端点前面放一个 stdio 到 HTTP 的桥接或一条隧道。
write 工具
allow_write 默认是 OFF,在它关闭时调用 write 会立即失败,不会触及数据库:
allow_write 打开会让该工具出现在 tools/list 中,但账户自身的授权仍然适用。在 mcp_user 仍然只持有 SELECT 的情况下,同一个调用现在改为在数据库层失败:
UPDATE 后,同一个调用就能通过,并且确实改变了那一行:
allow_write 和账户的授权是两道独立的关卡,一次真实的写入需要两者都打开。写入没有像 max_rows 限制读取那样的行数上限:一条不带条件的 DELETE 会清空整个表,与其他任何设置无关。拥有生产数据库写入权限的代理,与任何其他拥有广泛写入权限的自主进程承担同样的风险:它可能执行一个对它合理、对您不合理的计划,而且比人工审查步骤能拦下的速度更快。请给 db_url 一个授权恰好与您愿意接受的影响范围相匹配的账户,并把 allow_write 视为按数据库逐一做出的决定,而不是因为某次演示需要就一直开着的默认值。
本指南在继续之前把 allow_write 关回去并撤销 UPDATE,对于一个代理拥有常驻访问权限的数据库,这也是更安全的常态。
缩小代理能触及的范围
有两项设置能把代理的触及范围缩得比账户授权本身更小,当一个账户不只服务于vsql_mcp 时很有用。
max_rows 限制单次 query 调用返回的行数,并把结果标记为 truncated:
allowed_tables 限制一条语句可以触及哪些表,通过用 EXPLAIN FORMAT=JSON 为该语句生成执行计划来检查。添加第二个表来观察它的执行效果:
secrets,而 allowed_tables 只设置为 posts 时,posts 仍然可用,secrets 则被拒绝:
list_tables 也不再列出被排除的表,所以只依靠 list_tables 工作的代理永远不会知道 secrets 的存在:
db_url 账户可以调用的任何函数。请把 allowed_tables 和 max_rows 视为叠加在账户授权之上的防护措施,而不是限定授权本身的替代品。
常见问题
代理需要直接访问数据库凭据吗?
不需要。代理使用vsql_mcp.bearer_token 中设置的 bearer 令牌向 vsql_mcp 认证。vsql_mcp.db_url 指明的数据库账户只由扩展在内部用于运行工具查询;代理永远看不到该账户的密码。
我可以暴露多个架构吗?
可以,但把vsql_mcp.schema 留空会暴露比您预期更多的东西。此时 list_schemas 会返回服务器上的每一个架构,包括 mysql、sys 和 performance_schema,而且它不会按 db_url 账户能访问的范围过滤:该列表在进程内针对 information_schema.SCHEMATA 运行,而不是通过该账户的连接。把 vsql_mcp.schema 限定到一个架构才是限制发现范围的方法。账户的授权仍然决定 query 和 write 实际能读什么,所以被列出的架构不一定是可读的架构。
vsql_mcp 支持 TLS 吗?
支持。把vsql_mcp.ssl_cert 和 vsql_mcp.ssl_key 都设置为 PEM 文件路径后,会在 vsql_mcp.ssl_port(默认 3143)上提供 HTTPS。两者任一留空都会关闭 TLS,与端口设置无关。
为什么更改端口不会立即生效?
端口和 TLS 设置在服务器下一次被启用时生效。更改它们之后,请把vsql_mcp.vsql_mcp_enabled 切换为 OFF 再切换为 ON。
故障排除
另请参阅
- MySQL 用户管理 —
CREATE USER、GRANT以及最小权限账户设计 - MySQL 安全加固 — 超出单个扩展防护措施之外的更广泛的服务器加固
- 将 MySQL 连接到 AI API — 另一个方向:使用
vsql_ai从 MySQL 内部调用 AI API