​
Introdução

Servidores MCP permitem conectar fontes de dados personalizadas e disponibilizá‑las para uso dentro do Cursor. Isso é especialmente útil quando tu precisas de contexto de lugares como navegadores, bancos de dados ou logs de erros e do sistema. Configurar um servidor MCP é simples e, com o Cursor, dá para fazer rapidinho. Neste guia, vamos ver como construir um servidor MCP para Postgres. Nosso objetivo é permitir que o Cursor execute consultas SQL diretamente em um banco de dados Postgres e exponha esquemas 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 fornece acesso a dados ou ações externas. Ele pode ser implementado de várias maneiras, mas aqui vamos usar o método mais simples: um servidor que roda localmente no teu computador via stdio (fluxos de entrada/saída padrão). Isso evita considerações de segurança complicadas e permite a gente focar na própria lógica do MCP. Um dos casos de uso mais comuns do MCP é o acesso a banco de dados. Ao construir dashboards, rodar análises ou criar migrações, muitas vezes é necessário consultar e inspecionar um banco de dados. Nosso servidor MCP para Postgres vai oferecer duas funcionalidades principais: executar consultas arbitrárias e listar esquemas de tabelas. Embora ambas as tarefas possam ser realizadas com SQL puro, o MCP oferece recursos que as tornam mais poderosas e, de modo geral, mais úteis. Tools fornecem uma forma de expor ações como executar consultas, enquanto resources 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 de dados. O SDK do MCP vai funcionar como um wrapper em volta dessas chamadas, permitindo integrar a funcionalidade do Postgres ao Cursor de forma transparente. [Placeholder: Ilustração de servidor MCP com tools e resources]

​
Como construir o MCP Server

O primeiro passo para construir o server é configurar um novo projeto. A gente vai começar criando uma nova pasta e inicializando um projeto Bun 
> mkdir postgres-mcp-server
> Bun init
A partir daqui, vamos selecionar o projeto Blank. Quando o boilerplate estiver configurado, precisamos instalar as dependências necessárias. zod é necessário para definir schemas de I/O no SDK do MCP 
bun add postgres @modelcontextprotocol/sdk zod
Agora, vamos até os repositórios de cada uma das bibliotecas e pegar o link para o conteúdo bruto de cada README. Vamos usar isso como contexto ao construir o server Agora, vamos definir como queremos que o server se comporte. Pra isso, vamos criar um spec.md e escrever os objetivos de alto nível 
# Spec

- Allow defining DATABASE_URL through MCP env configuration
- Query postgres data through tool
  - By default, make it readonly
  - Allow write ops by setting ENV `DANGEROUSLY_ALLOW_WRITE_OPS=true|1`
- Access tables as `resources`
- Use Zod for schema definitions
Como dá pra ver, essa é uma spec bem leve. Fica à vontade pra adicionar mais detalhes conforme necessário. Junto com os links dos READMEs, vamos construir o prompt final 
Read the following and follow @spec.md to understand what we want. All necessary dependencies are installed
- @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 Postgres), a gente pode usar o Cursor para criar o scaffold da implementação do server. O Cursor vai ajudar a juntar as peças, gerando o código que conecta o MCP SDK com o Postgres. Depois de algumas iterações de prompt, agora temos uma primeira versão do MCP server 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á para testá-la 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á para 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 as equipes muitas vezes 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ários membros da equipe podem consultar a mesma instância de banco de dados pelo Cursor
  • Configuração centralizada: Atualizações de schema e alterações de permissão 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 desempenho podem ser monitorados pela equipe
Para isso, você mudaria o método de transporte de stdio para HTTP. Embora a gente não vá cobrir toda a configuração, aqui vai um prompt inicial que você pode dar pro Cursor 
Based on the existing MCP server, create a new file that implements the HTTP protocol.

Move shared logic to mcp-core, and name each transport implementation by name (mcp-server-stdio, mcp-server-http)

@https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/refs/heads/main/README.md
Os resultados finais podem ser vistos aqui: pg-mcp-server