Protocolo MCP na prática: como conectar agentes de IA ao PostgreSQL

O Model Context Protocol (MCP), padrão aberto criado para padronizar a comunicação entre modelos de inteligência artificial e fontes externas de dados, oferece uma forma segura e modular de conectar agentes autônomos diretamente a bancos de dados relacionais como o PostgreSQL. Em vez de escrever códigos personalizados e frágeis de integração para cada ferramenta ou expor credenciais administrativas diretamente no prompt do assistente, o MCP estabelece uma arquitetura cliente-servidor padronizada que expõe tabelas, esquemas e consultas como ferramentas reutilizáveis.

Com essa abordagem, assistentes inteligentes podem inspecionar a estrutura de tabelas, executar consultas SQL parametrizadas, resumir métricas de vendas e responder a perguntas analíticas de gestores sem intermediários manuais. Para desenvolvedores e arquitetos de software em empresas brasileiras, a grande vantagem prática do protocolo reside no isolamento rigoroso de permissões: é possível restringir o acesso do agente estritamente a consultas de leitura (SELECT), mascarar dados pessoais sensíveis em conformidade com a LGPD e evitar injeções maliciosas de código. Aprender a configurar um servidor MCP para PostgreSQL na prática é o primeiro passo para desbloquear o potencial dos agentes de banco de dados.

Resumo rápido

• O Model Context Protocol (MCP) padroniza a conexão entre agentes de IA e bancos relacionais como o PostgreSQL.
• A arquitetura separa o cliente de IA (como Claude Desktop ou agentes customizados) do servidor que executa consultas no banco.
• Permite que o agente consulte esquemas, analise metadados e execute instruções SQL sob regras estritas de segurança.
• Configuração recomendada: criar um usuário de banco com privilégios exclusivos de leitura (READ ONLY) para o agente.
• O servidor MCP de PostgreSQL pode rodar localmente via Node.js (npx) ou encapsulado em contêineres Docker.
• Protege o ambiente de produção contra alterações indevidas de tabelas, exclusão de dados e ataques de SQL Injection.

O que é o Model Context Protocol e como ele interage com bancos

Antes do surgimento do MCP, a conexão de um modelo de linguagem a um banco de dados relacional dependia de scripts pontuais construídos com frameworks como LangChain ou LlamaIndex, ou do desenvolvimento manual de dezenas de declarações de function calling proprietárias para cada provedor de IA. Cada alteração de esquema no banco exigia revisar todo o código da aplicação e atualizar os prompts de sistema, aumentando o custo de manutenção e a fragilidade do sistema.

O MCP transforma essa dinâmica ao definir um protocolo universal baseado em JSON-RPC. O servidor MCP atua como uma camada intermediária especializada entre o banco de dados e o modelo de IA. Ele se conecta ao PostgreSQL através de drivers de conexão convencionais, lê a estrutura do catálogo de dados e expõe um conjunto claro de ferramentas (tools) e recursos (resources) padronizados que qualquer cliente compatível com MCP consegue descobrir e invocar automaticamente.

Quando o usuário faz uma pergunta como “quais foram os dez produtos mais vendidos na região Sudeste no último trimestre?”, o agente de IA solicita a lista de ferramentas disponíveis ao servidor MCP, seleciona a ferramenta de consulta SQL, gera a sintaxe adequada com base no esquema das tabelas e envia a instrução para execução. O servidor MCP valida os parâmetros, executa a consulta de forma controlada no PostgreSQL e retorna os registros estruturados para que o modelo elabore a síntese final em linguagem natural.

Arquitetura tradicional vs arquitetura baseada em servidores MCP

Compreender os ganhos de governança e escalabilidade do MCP exige comparar o modelo anterior de conexões customizadas com o modelo modular padronizado. A tabela comparativa a seguir destaca as diferenças fundamentais entre essas duas abordagens arquiteturais:

Para entender detalhadamente a especificação técnica e o funcionamento conceitual do protocolo, consulte nosso guia completo sobre Model Context Protocol (MCP).

Passo a passo: configurando o servidor MCP para PostgreSQL

Para colocar a integração em funcionamento, o desenvolvedor precisa de uma instância acessível do PostgreSQL (local ou em nuvem gerenciada como Supabase, Neon ou AWS RDS) e de um ambiente com Node.js instalado. Siga o roteiro técnico abaixo:

1. Criação do usuário seguro no PostgreSQL

Nunca utilize o usuário administrativo (postgres ou root) para conectar o servidor MCP. Crie um usuário dedicado com privilégios estritamente limitados à leitura das tabelas operacionais:

Execute no console do PostgreSQL (psql):

CREATE USER agente_ia WITH PASSWORD 'SenhaSegura123';

GRANT CONNECT ON DATABASE loja_producao TO agente_ia;

GRANT USAGE ON SCHEMA public TO agente_ia;

GRANT SELECT ON ALL TABLES IN SCHEMA public TO agente_ia;

ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO agente_ia;

Esse conjunto de privilégios assegura que, mesmo se o modelo sofrer uma injeção de prompt adversária ou tentar executar comandos de DROP, DELETE ou UPDATE, o mecanismo interno do PostgreSQL rejeitará a operação no nível de privilégio do banco.

2. Configuração do servidor oficial de MCP

A comunidade de código aberto do MCP mantém um servidor oficial de referência para PostgreSQL através do pacote @modelcontextprotocol/server-postgres. O servidor pode ser executado sem instalação manual persistente utilizando o comando npx do Node.js.

No arquivo de configuração do cliente (como o claude_desktop_config.json no Claude Desktop), adicione o bloco de inicialização do servidor:

{ "mcpServers": { "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://agente_ia:SenhaSegura123@localhost:5432/loja_producao"] } } }

Ao reiniciar o cliente, o assistente detectará automaticamente as ferramentas de inspeção de esquemas e execução de queries do banco de dados.

Para aprender como gerenciar regras e salvaguardas para agentes em ambientes produtivos, leia nosso artigo sobre permissões de agentes de IA e como limitar ações com segurança.

Boas práticas de segurança e conformidade com a LGPD

A conexão de agentes de IA a bancos que armazenam dados de cidadãos brasileiros impõe responsabilidades jurídicas claras no âmbito da Lei Geral de Proteção de Dados (Lei 13.709/2018). Dados cadastrais de pessoas físicas (como CPF, números de telefone, endereços residenciais e senhas criptografadas) nunca devem ser trafegados em texto puro nos prompts do modelo:

• Uso de visualizações (views) mascaradas: Em vez de dar acesso direto à tabela de usuários, crie uma VIEW de banco de dados que oculte colunas sensíveis, expondo apenas dados anonimizados como identificadores anônimos, cidade, estado e valores agregados de compras.
• Limitação do tamanho de saída (LIMIT obrigatório): Consultas disparadas por agentes devem conter limites máximos de registros retornados (como LIMIT 100) para evitar que o modelo tente carregar tabelas gigantescas na janela de contexto, o que geraria estouro de memória e altos custos de tokens.
• Auditoria e logs de execução: Configure o PostgreSQL para registrar todas as instruções SQL executadas pelo usuário agente_ia no log do servidor (parâmetro log_statement = 'all'), permitindo auditoria forense de quais perguntas os operadores estão fazendo aos dados.
• Comunicação criptografada (SSL/TLS): Em conexões com bancos em nuvem remota, certifique-se de que a string de conexão exija conexões protegidas por certificado (sslmode=require).

Se você utiliza ferramentas de produtividade para desktop e quer entender o fluxo de arquivos corporativos, conheça também nosso guia sobre Claude Cowork e tarefas com arquivos no desktop.

Exemplo: distribuidora de autopeças em Campinas

Para ilustrar a aplicação prática dessa arquitetura no setor empresarial nacional, considere uma distribuidora de autopeças sediada em Campinas, interior de São Paulo. A empresa gerencia um catálogo com mais de 35 mil itens cadastrados em um banco de dados PostgreSQL, atendendo oficinas mecânicas e varejistas em todo o estado.

Diariamente, a diretoria comercial e os analistas de estoque gastavam horas solicitando relatórios manuais à equipe de tecnologia da informação (TI) para saber quais lotes de pastilhas de freio e amortecedores estavam com giro lento ou quais clientes haviam reduzido o volume de compras no mês corrente.

Com a implantação de um servidor MCP PostgreSQL operando sob usuário de leitura restrita:

1. Inspeção autônoma: O diretor de compras pergunta ao agente de IA: “Quais são as cinco linhas de filtros de óleo para caminhões pesados com maior volume de estoque parado há mais de noventa dias no depósito de Campinas?”.
2. Geração precisa de SQL: O agente utiliza o servidor MCP para consultar a tabela de metadados, identifica as tabelas estoque_itens, categorias e movimentacoes, e compõe uma instrução SQL com INNER JOIN e filtro de data sem erros de sintaxe.
3. Resposta analítica consolidada: O servidor executa a consulta em 80 milissegundos e devolve uma tabela limpa. O agente resume os valores parados em reais, calcula a média diária histórica de saída e sugere uma política de desconto promocional para os clientes do polo logístico de Paulínia e Hortolândia.

Essa rotina reduziu o tempo de espera por análises operacionais de três dias para menos de trinta segundos, sem sobrecarregar a equipe de desenvolvedores da empresa.

Erros comuns

• Conectar com usuário de privilégio administrativo: Permitir que o agente utilize credenciais de superusuário abre brechas inaceitáveis para acidentes catastróficos de modificação ou apagamento de tabelas.
• Ignorar índices em tabelas de grandes dimensões: Enviar o agente para fazer filtros em tabelas com milhões de linhas sem índices adequados pode causar varreduras completas (sequential scans) e travar o banco.
• Expor senhas em arquivos de configuração compartilhados: Deixar a string de conexão exposta em texto puro em repositórios Git públicos ou sem controle de permissão de arquivo local.
• Não definir limites de timeout para consultas: Deixar de configurar a diretiva statement_timeout no PostgreSQL pode fazer com que consultas complexas fiquem presas consumindo processamento ininterrupto.
• Presumir que o agente sabe regras implícitas de negócio: Se uma regra de cancelamento de pedido requer filtrar uma coluna de status específica, isso deve estar documentado nos comentários das colunas do PostgreSQL para que o modelo leia no catálogo.
• Esquecer de mascarar dados pessoais: Violar a privacidade de clientes ao permitir que o agente exiba telefones e CPFs sem necessidade operacional.

Perguntas frequentes

O servidor MCP funciona com bancos de dados hospedados na nuvem como Supabase ou AWS RDS?

Sim. Desde que a string de conexão padrão do PostgreSQL esteja configurada com o host correto, porta, credenciais e parâmetros SSL exigidos pela plataforma de nuvem, o servidor MCP se comunica normalmente.

O agente pode modificar dados no banco através do MCP?

Tecnicamente, o protocolo suporta qualquer instrução que o usuário conectado tenha direito de executar. No entanto, a boa prática de segurança manda vincular o servidor MCP a um usuário do PostgreSQL sem permissões de INSERT, UPDATE ou DELETE.

É necessário expor a porta 5432 do banco para a internet pública?

Não. Quando o servidor MCP roda na mesma máquina ou dentro da mesma rede virtual privada (VPC) do banco, a comunicação ocorre de maneira interna e protegida sem exposição pública.

O servidor MCP consome muitos recursos de memória no computador?

Não. O processo do servidor MCP atua apenas como um intermediário leve de comunicação de protocolo, consumindo tipicamente menos de 100 megabytes de memória RAM durante sua execução.

Como o agente sabe quais colunas e tabelas consultar?

O servidor oficial MCP para PostgreSQL possui ferramentas automáticas que leem o esquema de informações do banco (information_schema), repassando as definições de nomes de tabelas, tipos de dados e comentários diretamente ao modelo de linguagem.

Para conhecer todas as integrações de ferramentas e plataformas inteligentes da empresa, consulte nosso índice detalhado de integrações da Anthropic e Claude.

Fontes e leitura recomendada

• Documentação oficial do Model Context Protocol: arquitetura e conceitos fundamentais
• Repositório oficial de servidores MCP de referência da comunidade de código aberto
• Documentação oficial do PostgreSQL: permissões, usuários e gerenciamento seguro de acessos
• Anthropic: desenvolvimento de agentes inteligentes integrados com ferramentas e servidores MCP