Extensão vsql_mcp para MySQL

O vsql_mcp serve o banco de dados a agentes de IA pelo Model Context Protocol, a partir de um listener dentro do processo do servidor. Um agente pode listar schemas, descrever tabelas e executar consultas somente leitura. As gravações ficam desativadas até que você as ative, e o caminho das consultas passa por uma conta do banco de dados que você indica, então o agente recebe exatamente o acesso que você concedeu a essa conta.


Mantenedor	VillageSQL
Código-fonte e documentação completa	villagesql/vsql-mcp
Licença	GPL-2.0
Escrito em	Rust
Capability	Preview

Esta extensão usa capabilities Preview, quatro delas, então o servidor precisa ser iniciado com --vsql_allow_preview_extensions=ON. Caso contrário, o INSTALL EXTENSION é recusado.

Instalar

O vsql_mcp não vem incluído com o servidor, então compile-o primeiro a partir do repositório e copie o vsql_mcp.veb resultante para o diretório indicado pela variável de sistema veb_dir. Em seguida, instale-o:

INSTALL EXTENSION vsql_mcp;

Confirme que ele está lá:

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

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

As instruções de compilação estão no repositório.

O que ela adiciona

Ela adiciona uma função SQL, info(), que informa o que o listener está fazendo. Todo o resto é configuração e tráfego MCP.

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 é true a partir do momento em que vsql_mcp.vsql_mcp_enabled é definido como ON até o próximo despertar do worker em segundo plano, que ocorre a cada 25 ms. Uma chamada nessa janela também pode informar "enabled":false, já que o listener ainda não se vinculou.

Configuração	Padrão	O que controla
`vsql_mcp.vsql_mcp_enabled`	`OFF`	Se o listener está em execução
`vsql_mcp.schema`	vazio	O banco de dados que ele serve
`vsql_mcp.db_url`	vazio	A conta com a qual as ferramentas de consulta, gravação e explain se conectam
`vsql_mcp.allowed_tables`	vazio	Quais tabelas essas ferramentas podem tocar
`vsql_mcp.allow_write`	`OFF`	Se a ferramenta de gravação existe
`vsql_mcp.max_rows`	`1000`	O limite de linhas de um único resultado
`vsql_mcp.query_timeout`	`30`	Por quanto tempo uma consulta pode rodar, em segundos
`vsql_mcp.port`	`3100`	A porta HTTP
`vsql_mcp.ssl_port`	`3143`	A porta HTTPS
`vsql_mcp.ssl_cert`, `vsql_mcp.ssl_key`	vazio	O certificado e a chave para HTTPS
`vsql_mcp.require_auth`	`OFF`	Se uma requisição precisa carregar um bearer token
`vsql_mcp.bearer_token`	vazio	Esse token
`vsql_mcp.session_ttl`	`1800`	Por quanto tempo uma sessão de agente ociosa é mantida, em segundos

Exemplo

Aponte o listener para um banco de dados e inicie-o:

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;

Os agentes então se conectam a http://127.0.0.1:3100 por MCP Streamable HTTP. O repositório traz a configuração de cliente para cada agente.

A conta em db_url define o teto do que um agente pode fazer, e toda conta do banco de dados pode ler db_url, senha incluída, com SHOW VARIABLES, então conceda a ela o mínimo necessário e deixe allow_write desativado até que você realmente queira ativá-lo. Ative require_auth com um bearer token antes que a porta fique acessível de qualquer lugar além do localhost; o SHOW VARIABLES também mostra esse token a todas as contas.

Uma configuração gravada com SET PERSIST sobrevive a uma reinicialização, mas UNINSTALL EXTENSION a apaga. Após desinstalar e reinstalar, toda configuração volta ao seu padrão, e nenhuma reinicialização traz o valor antigo de volta.

Veja também

Servindo o MySQL a agentes de IA por MCP — conectar um agente e o que ele pode ver
Gerenciando extensões — como as configurações de extensão são lidas e gravadas
Capabilities Preview — o que o flag de preview ativa e o que ele promete
Extensões disponíveis — o catálogo completo
villagesql/vsql-mcp — código-fonte, configuração de cliente e as limitações conhecidas

Instalar e Executar Extensões

Catálogo de Extensões

Criar uma Extensão

Instalar

O que ela adiciona

Exemplo

Veja também

​Instalar

​O que ela adiciona

​Exemplo

​Veja também

Instalar

O que ela adiciona

Exemplo

Veja também