跳转到主要内容

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
需要查询数据库的 AI 代理通常通过手写的工具或边车进程与数据库对话。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 头:
此后这个连接上的每一个请求都需要那个会话 ID。省略它会以 JSON-RPC 错误失败,而不是静默地使用默认值:
发送 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 显示连接状态:
Claude Code 执行了它自己的 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。

故障排除

另请参阅