Pular para o conteúdo principal

​
Introdução

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.

​
O que é um servidor 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.

​
Como criar o servidor MCP

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 
> 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 
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 
# 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. 
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 
npx @modelcontextprotocol/inspector bun run index.ts

​
Testando o servidor MCP

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. Interface do MCP Inspector 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.

​
Próximos passos

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 
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
⌘I