Docsv1.0

MCP Local Agent

Guia completo para conectar seus bancos de dados ao CO-PILOTTT usando o MCP Local Agent. Seus dados nunca saem da sua rede — o agente roda localmente e se comunica com a plataforma de forma segura.

Visão Geral

O MCP Local Agent é um container Docker que roda dentro da sua infraestrutura, conectando-se diretamente ao seu banco de dados. Ele expõe uma API REST segura que o CO-PILOTTT utiliza para consultar schemas, listar tabelas e executar queries SELECT em tempo real.

Dados na sua rede

O agente roda localmente. Nenhum dado bruto transita para fora do seu ambiente.

Somente leitura

Apenas comandos SELECT são permitidos. Nenhuma alteração é feita no seu banco.

Setup em 5 minutos

Um único docker run é suficiente para conectar qualquer banco suportado.

Pré-requisitos

Docker
Instalado e rodando na máquina que terá acesso ao banco de dados.
Acesso ao banco de dados
Rede acessível entre a máquina do agente e o servidor do banco.
Usuário com permissão de leitura
Um usuário de banco com permissões somente SELECT (veja seção abaixo).
Chave de API do CO-PILOTTT
Disponível no painel em Configurações > Conexões > Gerar Chave.

Instalação

Execute o comando abaixo substituindo as variáveis de ambiente com os dados do seu banco:

docker run -d \
  --name copilottt-agent \
  -p 8443:8443 \
  -e DB_TYPE=postgresql \
  -e DB_HOST=192.168.1.100 \
  -e DB_PORT=5432 \
  -e DB_NAME=meu_banco \
  -e DB_USER=copilot_reader \
  -e DB_PASSWORD=senha_segura \
  -e COPILOTTT_API_KEY=sua-chave-aqui \
  ghcr.io/dmetechnology/copilottt-agent:latest

bash

Variáveis de ambiente

Variável	Descrição	Exemplo
DB_TYPE	Tipo do banco de dados	postgresql, mysql, oracle...
DB_HOST	Endereço do servidor	192.168.1.100
DB_PORT	Porta do banco	5432
DB_NAME	Nome do banco / SID	meu_banco
DB_USER	Usuário de leitura	copilot_reader
DB_PASSWORD	Senha do usuário	senha_segura
COPILOTTT_API_KEY	Chave de API do CO-PILOTTT	cplt_xxxxxxxxxxxx

Configuração por Banco

Selecione o tipo do seu banco para ver o comando Docker específico:

docker run -d \
  --name copilottt-agent \
  -p 8443:8443 \
  -e DB_TYPE=postgresql \
  -e DB_HOST=192.168.1.100 \
  -e DB_PORT=5432 \
  -e DB_NAME=meu_banco \
  -e DB_USER=copilot_reader \
  -e DB_PASSWORD=senha_segura \
  -e COPILOTTT_API_KEY=sua-chave-aqui \
  ghcr.io/dmetechnology/copilottt-agent:latest

bash

Criando Usuário Read-Only

Recomendamos criar um usuário dedicado com permissões somente leitura para o agente. Selecione o banco para ver o SQL:

-- Criar usuário read-only no PostgreSQL
CREATE USER copilot_reader WITH PASSWORD 'senha_segura';
GRANT CONNECT ON DATABASE meu_banco TO copilot_reader;
GRANT USAGE ON SCHEMA public TO copilot_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO copilot_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO copilot_reader;

sql

Importante: Substitua senha_segura por uma senha forte e meu_banco pelo nome real do seu banco de dados.

Conectando no CO-PILOTTT

Após o agente estar rodando, siga os passos abaixo no painel do CO-PILOTTT:

Acesse Configurações > Conexões

No menu lateral do dashboard, clique em "Conexões" dentro de Configurações.

Clique em "Nova Conexão"

No canto superior direito, clique no botão para adicionar uma nova conexão.

Selecione "MCP Local Agent"

Escolha o tipo de conexão MCP Local Agent na lista de opções.

Informe o endereço do agente

Digite o endereço onde o agente está rodando, ex: http://192.168.1.100:8443

Teste e salve

Clique em "Testar Conexão" para verificar. Se tudo estiver OK, salve.

Testando a Conexão

Após conectar, você pode verificar se tudo está funcionando:

1. Health check do agente:

curl http://localhost:8443/health

bash

2. Listar tabelas:

curl -X POST http://localhost:8443/tools/list_tables \
  -H "Content-Type: application/json"

bash

3. Consultar schema:

curl -X POST http://localhost:8443/tools/get_schema \
  -H "Content-Type: application/json"

bash

4. Executar uma query de teste:

curl -X POST http://localhost:8443/tools/query_db \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT 1 AS test"}'

bash

Se todos os endpoints responderem com sucesso, a conexão está pronta para uso no CO-PILOTTT.

Troubleshooting

Connection refused na porta 8443

Causa: O container não está rodando ou a porta não está mapeada.

Solução: Verifique com docker ps se o container está ativo. Confira o mapeamento -p 8443:8443.

Authentication failed

Causa: Credenciais do banco incorretas.

Solução: Confira DB_USER e DB_PASSWORD. Teste o login diretamente no banco.

Could not connect to database

Causa: O agente não consegue acessar o host/porta do banco.

Solução: Verifique se o DB_HOST é acessível a partir do container. Use --network host se estiverem na mesma máquina.

Permission denied on table

Causa: O usuário não tem permissão SELECT na tabela.

Solução: Execute o GRANT SELECT conforme a seção "Criando Usuário Read-Only".

Timeout nas queries

Causa: Query muito pesada ou rede lenta entre agente e banco.

Solução: Verifique a latência de rede. Considere rodar o agente mais próximo do banco.

Segurança

A segurança é prioridade na arquitetura do MCP Local Agent:

Somente SELECT

O agente rejeita qualquer comando que não seja SELECT. INSERT, UPDATE, DELETE, DROP e outros são bloqueados no nível do agente.

Dados na sua rede

O agente roda dentro da sua infraestrutura. Os dados brutos nunca saem do seu ambiente.

Comunicação criptografada

A comunicação entre o agente e a plataforma CO-PILOTTT é feita via HTTPS com TLS 1.3.

Chave de API rotacionável

A COPILOTTT_API_KEY pode ser rotacionada a qualquer momento pelo painel sem downtime.

Sem armazenamento local

O agente não persiste dados em disco. Resultados de queries existem apenas em memória durante a execução.

Auditoria completa

Toda query executada é registrada com timestamp, usuário solicitante e query completa para auditoria.

Pronto para conectar?

Acesse o painel do CO-PILOTTT, gere sua chave de API e siga este guia para conectar seu banco em minutos.

Acessar Painel Falar com Especialista