VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
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:
Criando Dados de Exemplo
Este guia usa um banco de dados dedicado e uma pequena tabelaposts para que o agente tenha algo real para consultar.
Instalando a Extensã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:
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 dovsql_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:
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:initialize tem sucesso e retorna um cabeçalho Mcp-Session-Id:
notifications/initialized, e então liste as ferramentas disponíveis usando o ID de sessão da resposta do initialize:
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:
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:
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:
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:
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 ovsql_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:
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:
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 novsql_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 deixarvsql_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 tantovsql_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. Alternevsql_mcp.vsql_mcp_enabled para OFF e depois para ON depois de mudá-las.
Solução de Problemas
Veja também
- Gerenciamento de Usuários no MySQL —
CREATE USER,GRANTe o design de contas com privilégio mínimo - Fortalecimento de Segurança no MySQL — fortalecimento mais amplo do servidor, além das proteções de uma única extensão
- Conectando o MySQL a APIs de IA — a direção oposta: chamando uma API de IA de dentro do MySQL com
vsql_ai