Servidores MCP permitem conectar fontes de dados personalizadas e torná-las disponíveis para uso dentro do Cursor. Isso é especialmente útil quando tu precisas de contexto de lugares como navegadores, bancos de dados ou logs de erro e do sistema. Configurar um servidor MCP é simples e, com o Cursor, dá para fazer rapidinho.Neste guia, vamos mostrar como construir um servidor MCP para Postgres. Nosso objetivo é permitir que o Cursor execute queries SQL diretamente em um banco de dados Postgres e exponha schemas de tabelas de forma estruturada.
Este tutorial foi feito para ensinar os fundamentos de como construir servidores MCP.
Um servidor MCP é um processo que se comunica com o Cursor e dá acesso a dados ou ações externas. Dá pra implementar de várias formas, mas aqui a gente vai usar o jeito mais simples: um servidor que roda localmente no teu computador via stdio (fluxos de entrada/saída padrão). Isso evita preocupações de segurança complicadas e deixa a gente focar na lógica do MCP em si.Um dos casos de uso mais comuns do MCP é acesso a banco de dados. Ao montar dashboards, rodar análises ou criar migrações, muitas vezes é preciso consultar e inspecionar um banco. Nosso servidor MCP para Postgres vai oferecer duas capacidades centrais: executar consultas arbitrárias e listar schemas de tabelas.Embora ambas as tarefas possam ser feitas com SQL puro, o MCP oferece recursos que deixam tudo mais poderoso e útil no geral. Ferramentas dão um jeito de expor ações como executar consultas, enquanto recursos permitem compartilhar contexto padronizado, como informações de schema. Mais adiante neste guia a gente também vai ver prompts, que habilitam fluxos de trabalho mais avançados.Por baixo dos panos, vamos usar o pacote npm postgres para executar instruções SQL no banco. O SDK do MCP vai servir como um wrapper em volta dessas chamadas, permitindo integrar a funcionalidade do Postgres ao Cursor de forma transparente.
O primeiro passo para criar o servidor é configurar um novo projeto. A gente vai começar criando uma nova pasta e inicializando um projeto com o Bun
Copy
Ask AI
> mkdir postgres-mcp-server> Bun init
Daqui, a gente vai selecionar o projeto Blank. Depois que o nosso boilerplate estiver configurado, precisamos instalar as dependências necessárias. zod é necessário para definir schemas de entrada/saída no SDK do MCP
Copy
Ask AI
bun add postgres @modelcontextprotocol/sdk zod
A partir daqui, a gente vai nos repositórios de cada biblioteca e pega o link para o conteúdo raw dos respectivos arquivos README. Vamos usar isso como contexto ao construir o servidor
Agora, vamos definir como a gente quer que o servidor se comporte. Pra isso, vamos criar um spec.md e escrever os objetivos de alto nível
Copy
Ask AI
# Especificação- Permitir definir DATABASE_URL via configuração de ambiente do MCP- Consultar dados do Postgres por meio da ferramenta - Por padrão, deixar como somente leitura - Permitir operações de escrita definindo a variável de ambiente `DANGEROUSLY_ALLOW_WRITE_OPS=true|1`- Acessar tabelas como `resources`- Usar Zod para definições de schema
Como dá pra ver, essa é uma especificação bem leve. Fica à vontade pra adicionar mais detalhes conforme necessário. Junto com os links do README, a gente vai construir o prompt final.
Copy
Ask AI
Lê o seguinte e segue @spec.md pra entender o que a gente quer. Todas as dependências necessárias já estão instaladas- @https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/refs/heads/main/README.md- @https://raw.githubusercontent.com/porsager/postgres/refs/heads/master/README.md
Com esses três componentes em mãos (a especificação, a documentação do MCP SDK e a documentação da biblioteca do Postgres), dá pra usar o Cursor pra criar o esqueleto da implementação do servidor. O Cursor vai ajudar a juntar as peças, gerando o código que conecta o MCP SDK ao Postgres.Depois de algumas idas e vindas nos prompts, agora a gente tem uma primeira versão do servidor MCP rodando. Pra testar, dá pra usar o MCP Inspector
Copy
Ask AI
npx @modelcontextprotocol/inspector bun run index.ts
Quando a implementação inicial estiver pronta, dá pra testar usando o MCP Inspector. O Inspector oferece uma forma de ver o que o servidor expõe e verificar se as ferramentas e os recursos se comportam como esperado. A gente deve confirmar que as consultas podem ser executadas e que as informações do esquema são retornadas corretamente.Quando tudo estiver ok, dá pra conectar o servidor ao próprio Cursor e testá-lo em um ambiente real. Nesse ponto, o Cursor vai conseguir usar o servidor MCP do Postgres como se fosse um recurso nativo, permitindo consultar e inspecionar o banco de dados diretamente.
Executar o servidor MCP localmente via stdio é um ótimo ponto de partida, mas times geralmente precisam de acesso compartilhado ao mesmo banco de dados por meio do servidor MCP. Nesses cenários, implantar o servidor MCP como um serviço HTTP centralizado se torna necessário.Um servidor MCP implantado oferece várias vantagens em relação a instâncias individuais via stdio:
Acesso compartilhado ao banco de dados: Várias pessoas do time podem consultar a mesma instância de banco de dados pelo Cursor
Configuração centralizada: Atualizações de schema e alterações de permissões são gerenciadas em um único lugar
Segurança aprimorada: Autenticação adequada, rate limiting e controles de acesso podem ser implementados
Observabilidade: Padrões de uso e métricas de performance podem ser monitorados em todo o time
Para isso, você trocaria o método de transporte de stdio para HTTP.Embora a gente não cubra toda a configuração, aqui vai um bom prompt inicial que você pode passar para o Cursor
Copy
Ask AI
Com base no servidor MCP existente, cria um novo arquivo que implemente o protocolo HTTP.Move a lógica compartilhada para o mcp-core e nomeia cada implementação de transporte pelo nome (mcp-server-stdio, mcp-server-http)@https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/refs/heads/main/README.md
Os resultados finais podem ser conferidos aqui: pg-mcp-server
