Esta página foi traduzida do inglês com assistência de IA. Se houver diferenças entre as duas, a versão em inglês é a referência.
Agentes de IA
O StackQL oferece aos agentes de IA a mesma interface SQL que as pessoas usam para consultar, provisionar e operar serviços na nuvem e SaaS. Um agente descobre o que um provider expõe, valida uma consulta antes de executá-la, lê o estado em tempo real com SELECT e o altera com INSERT, UPDATE e DELETE, sem arquivo de estado e sem um SDK por nuvem.
Como os agentes se conectam
- MCP sobre stdio para clientes de editor e de desktop, como o Claude Desktop, o Cursor e o Continue. O próprio cliente inicia
stackql mcp --mcp.server.type=stdio. Consulte Servidor MCP. - MCP sobre HTTP para agentes independentes e automações que se conectam a um processo
stackql mcpoustackql srvde longa duração, com autenticação por token bearer e TLS opcional. - MCP incorporado para aplicações compiladas: o servidor é executado no mesmo processo, em Go, Rust, Swift, Kotlin, .NET e Gleam. Consulte MCP incorporado.
- Protocolo de comunicação do PostgreSQL por meio do
stackql srvpara frameworks de agentes, notebooks e ferramentas de BI que já falam Postgres.
Início rápido com o Claude Desktop
Instale pelo Anthropic Connector Directory (recomendado) ou pelo MCP Bundle disponível para download, ou registre o servidor manualmente em claude_desktop_config.json:
{
"mcpServers": {
"stackql": {
"command": "stackql",
"args": ["mcp", "--mcp.server.type=stdio", "--tls.allowInsecure"],
"env": {
"AWS_ACCESS_KEY_ID": "your-aws-access-key-id",
"AWS_SECRET_ACCESS_KEY": "your-aws-secret-access-key"
}
}
}
}
Inclua apenas as credenciais dos providers que você pretende usar. As instruções completas, incluindo os downloads do bundle e o uso de um arquivo de credenciais, estão em Usar o StackQL com o Claude Desktop.
O que um agente pode fazer
O servidor MCP expõe um conjunto de ferramentas pequeno e tipado. Cada ferramenta retorna uma visualização renderizada para o modelo e um payload estruturado para clientes programáticos.
- Descobrir:
list_providers,list_services,list_resources,list_methodsedescribe_methodpercorrem a hierarquia do provider e retornam as entradas e os campos de saída de cada operação, de modo que os parâmetrosWHEREobrigatórios são conhecidos antes de a consulta ser escrita. - Validar e ler:
validate_select_queryanalisa e planeja umSELECTsem executá-lo;run_select_queryo executa. - Alterar:
run_mutation_queryexecutaINSERT,UPDATE,REPLACEeDELETE;run_lifecycle_operationexecuta operações de ciclo de vidaEXEC. Ambas são controladas pelo modo do servidor, descrito abaixo. - Manutenção:
server_info,list_registry,pull_providerereload_credentials.
A referência completa, com entradas, comportamento de controle e um prompt de exemplo por ferramenta, está em Ferramentas MCP.
Barreiras de proteção
O modo do servidor define o contrato de segurança de toda a sessão:
| Modo | SELECT / metadados | INSERT / UPDATE / REPLACE | DELETE / EXEC |
|---|---|---|---|
read_only | permite | recusa | recusa |
safe (padrão) | permite | requer aprovação | requer aprovação |
delete_safe | permite | permite | requer aprovação |
full_access | permite | permite | permite |
"Requer aprovação" usa a elicitação do MCP: os clientes compatíveis com ela (Claude Desktop, Cursor, Continue) mostram ao usuário o nome da ferramenta, a classe da consulta e o SQL e aguardam uma decisão antes de qualquer execução; os clientes que não a anunciam são recusados. Cada chamada de ferramenta é gravada em um log de auditoria, os listeners HTTP exigem um token bearer e as credenciais vêm do ambiente ou de um arquivo dotenv, sem que nenhum valor de segredo seja retornado ao cliente. Os detalhes estão em Modos do servidor, Autenticação de clientes HTTP e Log de auditoria.
Próximos passos
- Servidor MCP - modos de implantação, configuração, modos do servidor, log de auditoria e opções.
- Ferramentas MCP - a referência completa das ferramentas, com entradas, controle e prompts de exemplo.
- MCP incorporado - execute o servidor dentro da sua própria aplicação em Go, Rust, Swift, Kotlin, .NET ou Gleam.
- Query Library - SQL pronto para executar, por provider, para perguntas comuns de operações na nuvem.
- Referência de IA - conceitos, guias práticos, comparações e solução de problemas escritos para agentes e para as pessoas que os criam.