Pular para o conteúdo principal

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

All examples on this page work on VillageSQL. Install Now →
Um agente de IA que precisa consultar um banco de dados normalmente fala com ele por uma ferramenta escrita à mão ou por um processo auxiliar. A extensão vsql_mcp remove essa camada: ela executa um servidor Model Context Protocol dentro do próprio processo do VillageSQL, de modo que qualquer cliente MCP pode descobrir o esquema e executar consultas diretamente.

O que o vsql_mcp Faz

vsql_mcp é uma extensão em Rust que serve MCP pelo transporte Streamable HTTP (revisão da especificação 2025-06-18) a partir de um worker em segundo plano dentro do processo do servidor. Ela expõe seis ferramentas: list_schemas, list_tables, describe_table, query, explain e write. A ferramenta write só aparece depois que você a ativa, e ela vem desativada por padrão. vsql_mcp é uma extensão Preview. Ela usa as capabilities Preview do VEF thread_worker, sys_var, status_var e sql_query, então o servidor precisa ser iniciado com as extensões Preview permitidas:
Verifique o flag antes de instalar:

Criando Dados de Exemplo

Este guia usa um banco de dados dedicado e uma pequena tabela posts para que o agente tenha algo real para consultar.

Instalando a Extensão

Instalá-la registra as suas variáveis de configuração e de status. Nada escuta em uma porta até que você a ative na próxima seção.

Criando uma Conta com Privilégio Mínimo

vsql_mcp executa a maioria das chamadas de ferramenta, incluindo query, write, explain e o recurso de DDL de tabela, por uma conexão de loopback com o servidor usando uma conta que você configura. Somente list_schemas, list_tables e describe_table rodam dentro do processo sem essa conta. Crie uma conta dedicada, restrita ao único banco de dados que este guia usa, com SELECT apenas:
As concessões da conta são o limite de acesso real. As proteções próprias do vsql_mcp, cobertas abaixo, são aplicadas por cima dessas concessões, e não no lugar delas.

Configurando e Ativando o Servidor

Todas as configurações do vsql_mcp são variáveis SET GLOBAL vsql_mcp.<name>. Aponte db_url para a conta criada acima, restrinja o servidor a um esquema, exija um token bearer e ative-o:
Confirme que ele está escutando:
http_port mostra 3100, o padrão. O servidor escuta em http://127.0.0.1:3100/mcp e se vincula somente a 127.0.0.1. Ele nunca aceita conexões remotas diretamente; colocá-lo atrás de um proxy reverso é responsabilidade sua, se você precisa disso.

Verificando que o Servidor Fala MCP

Antes de conectar um cliente real, verifique o endpoint HTTP diretamente com o handshake do MCP. Uma requisição sem token bearer é rejeitada:
Com o token, initialize tem sucesso e retorna um cabeçalho Mcp-Session-Id:
Toda requisição seguinte nesta conexão precisa desse ID de sessão. Omiti-lo falha com um erro JSON-RPC, e não com um padrão silencioso:
Envie notifications/initialized, e então liste as ferramentas disponíveis usando o ID de sessão da resposta do initialize:
Cinco ferramentas são listadas, e não seis. write está ausente porque allow_write ainda está OFF, então um agente que se conecta agora nunca planeja em torno de uma ferramenta que não pode usar.

Chamando Ferramentas pelo MCP

list_tables mostra a única tabela no esquema exposto:
query executa um SELECT e retorna as linhas de verdade:
Esses são os dados de exemplo reais da tabela posts, retornados pelo protocolo MCP em vez de por uma conexão SQL direta. query aceita somente uma única instrução somente leitura. Qualquer outra coisa é recusada antes de chegar ao banco de dados:

Conectando um Cliente Real

Os passos acima provam que o servidor responde corretamente a um cliente HTTP bruto. Para provar que um agente consegue de fato usá-lo, registre o servidor no Claude Code e deixe-o gerenciar a sessão:
local config restringe o servidor a este único projeto. Passe --scope user em vez disso para torná-lo disponível em todos os projetos. claude mcp list mostra o status da conexão:
O Claude Code executou o seu próprio handshake initialize, negociou uma sessão e confirmou que o servidor responde pelo MCP, o mesmo servidor que este guia configurou com instruções SET GLOBAL e testou à mão acima. A partir daqui, fazer ao agente uma pergunta sobre o banco de dados mcp_guide passa por list_tables, describe_table e query, exatamente como demonstrado com o curl. vsql_mcp não tem transporte stdio. O servidor roda dentro do processo do banco de dados, então não há processo filho para um cliente iniciar. Um cliente que só fala stdio, ou um cliente remoto que passa por um proxy na nuvem de um fornecedor e não consegue alcançar 127.0.0.1, precisa de uma ponte stdio-para-HTTP ou de um túnel na frente do endpoint.

A Ferramenta write

allow_write está OFF por padrão, e chamar write enquanto ela está desativada falha imediatamente, sem tocar no banco de dados:
Ativar allow_write faz a ferramenta aparecer em tools/list, mas as concessões da própria conta continuam valendo. Com mcp_user ainda tendo somente SELECT, a mesma chamada agora falha na camada do banco de dados:
Conceder UPDATE no banco de dados deixa a mesma chamada passar, e ela muda a linha de verdade:
allow_write e as concessões da conta são dois portões separados, e uma gravação real exige os dois abertos. Não há teto de linhas para uma gravação da forma como max_rows limita uma leitura: um DELETE sem cláusula WHERE esvazia a tabela independentemente de qualquer outra configuração. Um agente com acesso de gravação a um banco de dados de produção carrega o mesmo risco de qualquer outro processo autônomo com acesso amplo de gravação: ele pode agir com base em um plano que fez sentido para ele e não para você, mais rápido do que uma etapa de revisão humana consegue perceber. Dê a db_url uma conta cujas concessões correspondam exatamente ao raio de impacto que você está disposto a aceitar, e trate allow_write como uma decisão tomada por banco de dados, e não como um padrão deixado ativado porque uma demonstração precisou dele. Este guia desativa allow_write de novo e revoga UPDATE antes de continuar, que também é o estado de repouso mais seguro para um banco de dados ao qual um agente tem acesso permanente.

Restringindo o que um Agente Pode Alcançar

Duas configurações restringem o alcance de um agente para além das concessões da conta sozinhas, úteis quando uma conta serve a mais do que o vsql_mcp. max_rows limita quantas linhas uma única chamada de query retorna e marca o resultado como truncated:
allowed_tables restringe quais tabelas uma instrução pode tocar, verificado ao planejar a instrução com EXPLAIN FORMAT=JSON. Adicione uma segunda tabela para vê-la em ação:
Com secrets presente no mesmo esquema e allowed_tables definido somente como posts, posts continua funcionando e secrets é recusada:
list_tables também deixa de nomear a tabela excluída, então um agente que trabalha somente a partir de list_tables nunca fica sabendo que secrets existe:
A lista de permissões é planejada a partir das tabelas da instrução, e não lida das concessões da conta, então ela não enxerga através de uma função armazenada e não impede uma ferramenta de leitura de chamar qualquer função que a conta de db_url possa chamar. Trate allowed_tables e max_rows como proteções em camadas por cima das concessões da conta, e não como substituto para restringir as próprias concessões.

Perguntas Frequentes

Um agente precisa de acesso direto às credenciais do banco de dados?

Não. O agente se autentica no vsql_mcp com o token bearer definido em vsql_mcp.bearer_token. A conta de banco de dados nomeada por vsql_mcp.db_url é usada somente internamente pela extensão para executar as consultas das ferramentas; o agente nunca vê a senha dessa conta.

Posso expor mais de um esquema?

Sim, mas deixar vsql_mcp.schema vazio expõe mais do que você pode esperar. list_schemas então retorna todos os esquemas do servidor, mysql, sys e performance_schema incluídos, e não filtra pelo que a conta de db_url consegue alcançar: a listagem roda dentro do processo contra information_schema.SCHEMATA, e não pela conexão da conta. Restringir vsql_mcp.schema a um esquema é o que limita a descoberta. As concessões da conta ainda governam o que query e write conseguem de fato ler, então um esquema listado não é necessariamente um esquema legível.

O vsql_mcp suporta TLS?

Sim. Definir tanto vsql_mcp.ssl_cert quanto vsql_mcp.ssl_key com caminhos de arquivos PEM serve HTTPS em vsql_mcp.ssl_port (padrão 3143). Deixar qualquer um dos dois vazio desativa o TLS, independentemente da configuração da porta.

Por que mudar a porta não tem efeito imediato?

As configurações de porta e de TLS têm efeito na próxima vez que o servidor é ativado. Alterne vsql_mcp.vsql_mcp_enabled para OFF e depois para ON depois de mudá-las.

Solução de Problemas

Veja também