Pular para o conteúdo principal
Página traduzida

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 mcp ou stackql srv de 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 srv para 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_methods e describe_method percorrem a hierarquia do provider e retornam as entradas e os campos de saída de cada operação, de modo que os parâmetros WHERE obrigatórios são conhecidos antes de a consulta ser escrita.
  • Validar e ler: validate_select_query analisa e planeja um SELECT sem executá-lo; run_select_query o executa.
  • Alterar: run_mutation_query executa INSERT, UPDATE, REPLACE e DELETE; run_lifecycle_operation executa operações de ciclo de vida EXEC. Ambas são controladas pelo modo do servidor, descrito abaixo.
  • Manutenção: server_info, list_registry, pull_provider e reload_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:

ModoSELECT / metadadosINSERT / UPDATE / REPLACEDELETE / EXEC
read_onlypermiterecusarecusa
safe (padrão)permiterequer aprovaçãorequer aprovação
delete_safepermitepermiterequer aprovação
full_accesspermitepermitepermite

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