> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Extensão vsql_mcp para MySQL

> A extensão vsql_mcp serve o MySQL a agentes de IA pelo Model Context Protocol, com navegação de schema, consultas somente leitura, uma lista de tabelas permitidas e limites de linhas.

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](https://github.com/villagesql/vsql-mcp) |
| **Licença** | GPL-2.0 |
| **Escrito em** | Rust |
| **Capability** | Preview |

> [!WARNING]
>
> 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:

```sql theme={null}
INSTALL EXTENSION vsql_mcp;
```

Confirme que ele está lá:

```sql theme={null}
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](https://github.com/villagesql/vsql-mcp).

## 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.

```sql theme={null}
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:

```sql theme={null}
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.

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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](https://villagesql.com/docs/en/guides/mysql-ai-agents-mcp.md) — conectar um agente e o que ele pode ver
* [Gerenciando extensões](https://villagesql.com/docs/pt-BR/extensions/managing.md) — como as configurações de extensão são lidas e gravadas
* [Capabilities Preview](https://villagesql.com/docs/pt-BR/extensions/build/preview-capabilities.md) — o que o flag de preview ativa e o que ele promete
* [Extensões disponíveis](https://villagesql.com/docs/pt-BR/extensions/catalog) — o catálogo completo
* [villagesql/vsql-mcp](https://github.com/villagesql/vsql-mcp) — código-fonte, configuração de cliente e as limitações conhecidas


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.