Como Construir Seu Primeiro Servidor MCP em 2026: Um Guia Prático para Desenvolvedores

O primeiro servidor MCP que escrevi fazia uma coisa. Ele lia meu banco de dados Postgres e retornava o esquema como JSON estruturado. Era isso. Sem junções sofisticadas, sem construtor de consultas, apenas uma lista de tabelas, colunas e tipos.

Levou-me uma tarde. Duas semanas depois, ele me salvou horas. Toda vez que pedi ao Claude Code para adicionar um novo recurso que tocasse o banco de dados, ele puxava o esquema através do servidor MCP em vez de alucinar nomes de colunas. A taxa de bugs em migrações geradas por IA caiu para praticamente zero. O padrão era tão obviamente útil que agora escrevo um pequeno servidor MCP para quase todos os projetos em que trabalho.

Se você leu meu guia do desenvolvedor MCP, você sabe o que é o protocolo. Este post é a parte que não cobri lá: na verdade, construir um. Não teórico, não acenando para a especificação. Os passos exatos que sigo quando me sento e decido que um projeto precisa de seu próprio servidor MCP, e os erros que continuo vendo outros desenvolvedores cometerem pelo caminho.

Por Que Você Deveria Construir Um Mesmo Que Não Esteja Na Anthropic

Há uma suposição estranha que continuo encontrando. As pessoas pensam que os servidores MCP são algo que grandes empresas de IA escrevem para suas integrações, e que o resto de nós apenas os instala. Isso está meio certo. Os servidores oficiais (GitHub, Linear, Notion, Postgres) são excelentes. Eles cobrem os casos óbvios. Mas não podem cobrir o seu caso.

Seu caso é o CLI interno estranho do seu repositório. Seu caso é o esquema JSON que você continua colando em prompts manualmente. Seu caso são as três APIs internas que ninguém fora da sua equipe jamais irá envolver. Seu caso é o script de construção que envia seu produto, a ferramenta de migração que você escreveu em 2023, o painel de análise que você consulta através de uma visão SQL caseira.

Cada uma dessas coisas é um candidato para um servidor MCP. Não porque o protocolo é glamouroso, mas porque, uma vez que está encapsulado, cada agente de IA que você usa pode acessá-lo. Claude Code, Cursor, Windsurf, Zed, o aplicativo de chat oficial da Anthropic, qualquer runtime de agente futuro. Um servidor, muitos consumidores. A alavancagem é difícil de exagerar.

A outra razão para construir é mais simples. Você entenderá o MCP em um nível que não está disponível apenas lendo a especificação. A primeira vez que você tiver que decidir o que sua ferramenta searchTickets retorna e o que não retorna, você aprende mais sobre design de agentes do que em um ano de teoria.

O Que Você Está Realmente Construindo

Um servidor MCP é um processo que fala JSON-RPC e expõe um pequeno conjunto de primitivas. O protocolo os chama de ferramentas, recursos e prompts. A maioria dos servidores envia apenas ferramentas. Alguns enviam recursos. Quase ninguém envia prompts. Comece com ferramentas.

Uma ferramenta é uma função com um nome, uma descrição, um esquema de entrada (JSON Schema) e uma implementação. Quando o modelo decide chamar sua ferramenta, o runtime serializa os argumentos, os envia para seu servidor, seu servidor executa a função e o resultado volta como texto ou conteúdo estruturado. Esse é o ciclo todo.

Um recurso é algo que o modelo pode ler, mas não escrever. Pense nisso como um arquivo que o agente pode buscar por URI. Um padrão comum é expor a documentação do seu projeto, seu esquema de banco de dados ou um instantâneo do estado do sistema como recursos. O modelo os puxa quando relevante.

Um prompt é uma instrução modelada que o usuário pode invocar pelo nome. Eles são úteis para codificar fluxos de trabalho comuns. Na prática, quase todos os servidores que vi os ignoram e permitem que o usuário invoque comandos de barra ou habilidades em vez disso.

O protocolo não se importa com qual linguagem você escreve o servidor. Existem SDKs maduros para TypeScript, Python, Go, Rust, Kotlin, C# e Java. Eu escrevo quase todos os meus em TypeScript porque a cadeia de ferramentas combina com o resto da minha pilha e porque o @modelcontextprotocol/sdk oficial é o mais ativamente mantido. Escolha qualquer linguagem que te leve a um servidor funcional mais rápido. O modelo não sabe nem se importa.

Escolha Seu Transporte: stdio Versus HTTP

Existem dois transportes que importam em 2026, e a escolha entre eles molda tudo o mais.

O transporte stdio é o que você quer para servidores apenas locais. O runtime do agente inicia seu servidor como um processo filho e canaliza JSON-RPC através de stdin e stdout. Não há porta, não há autenticação, não há rede. O servidor vive e morre com a sessão do agente. A maioria das ferramentas de desenvolvimento local (ajudantes do Postgres, wrappers do git, ferramentas de sistema de arquivos, runners de construção) são enviadas como servidores stdio porque o modelo de segurança é muito simples: se o agente pode executar um processo na sua máquina, ele já tem o mesmo nível de confiança que esse processo.

O transporte HTTP transmitível é o que você quer para servidores hospedados. Ele funciona sobre HTTP com Eventos Enviados pelo Servidor para a metade de streaming. Você o coloca em um servidor real (Fluid Compute, Lambda, uma VM, o que for), dá a ele uma URL, e qualquer agente que suporte MCP remoto pode se conectar. Use isso quando o servidor precisar ser compartilhado entre máquinas, quando precisar de autenticação centralizada, ou quando encapsular uma API que não deve ter suas credenciais em cada laptop de desenvolvedor.

Há uma terceira opção, o transporte SSE-only depreciado, que você deve ignorar. A especificação de 2025 consolidou-se no HTTP transmitível. Novos servidores não devem implementar apenas SSE.

Para seu primeiro servidor MCP, recomendo fortemente stdio. O ciclo de feedback é rápido, a história de autenticação não existe, e a história de implantação é "basta colocar o binário no seu laptop". Você pode passar para HTTP mais tarde, quando tiver algo que valha a pena hospedar.

O Servidor MCP Mínimo Viável

Aqui está o menor servidor TypeScript útil que eu realmente enviaria. Ele expõe uma ferramenta que retorna o status git atual do repositório em que foi lançado.

import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';

const server = new Server(
  { name: 'git-status-mcp', version: '0.1.0' },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'git_status',
      description:
        'Retorna o status git porcelain do diretório de trabalho atual. Use isso para