Eu Construi Servidores MCP para 9 APIs SaaS — Aqui Está o Que Aprendi Sobre o Padrão

Passei as últimas semanas construindo servidores MCP (Modelo de Protocolo de Contexto) para várias APIs — CoinGecko, Stripe, Jira, PostHog, Plausible, Etherscan, DeFiLlama, Jobber e Resend. Nove servidores, 68 ferramentas, todos publicados no npm e indexados no Glama.

Ao longo do caminho, percebi que a mesma arquitetura continua funcionando. Se você está construindo um servidor MCP para sua própria API — ou pensando em contratar alguém para fazê-lo — aqui está o padrão.

A Arquitetura em Três Camadas

Todo servidor MCP que construo tem três camadas:

1. Definições de Ferramentas (o contrato)

Cada endpoint de API se torna uma ferramenta MCP com um esquema de entrada tipado. Eu uso Zod para validação — ele captura entradas ruins antes que cheguem à sua API.

{
  name: "send_email",
  description: "Enviar um único email via Resend",
  inputSchema: {
    from: z.string().email(),
    to: z.union([z.string().email(), z.array(z.string().email())]),
    subject: z.string().min(1),
    html: z.string().optional(),
    text: z.string().optional(),
  },
}

A descrição importa mais do que você pensa. LLMs leem essas descrições para decidir qual ferramenta chamar. Uma descrição vaga como "enviar email" desperdiça tokens. Uma específica como "Enviar um único email transacional via API Resend. Suporta HTML e texto simples. Retorna ID da mensagem e status de entrega." é utilizada corretamente.

2. Cliente API (a tubulação)

Esta camada lida com autenticação, limitação de taxa e transformação de erros. A principal percepção: não vaze erros HTTP para o LLM. Transforme-os em mensagens estruturadas e acionáveis.

// Ruim: "Erro: 429"
// Bom: "Limitado por taxa pela API Resend. Tente novamente após 30 segundos. Você enviou 100 emails na última hora."

3. Formatador de Saída (a apresentação)

Despejos de JSON brutos são terríveis para o consumo de LLM. Formate as respostas como tabelas markdown, listas com marcadores ou texto estruturado. O LLM lê essa saída para decidir o que fazer a seguir — torne-a escaneável.

## Email Enviado com Sucesso
- **ID da Mensagem:** abc123
- **De:** alerts@yourcompany.com
- **Para:** user@example.com
- **Assunto:** Seu relatório semanal
- **Status:** Enviado para entrega

Os Padrões Que Continuam Funcionando

Modo Simulado

Cada servidor inclui um modo simulado que retorna dados falsos realistas. Isso permite que os desenvolvedores testem sem credenciais de API ao vivo. É também como eu testo durante o desenvolvimento — sem necessidade de chaves de API.

Divulgação Progressiva

Não despeje todas as 18 ferramentas no LLM de uma vez se ele só precisa de 3. Agrupe as ferramentas por caso de uso. O servidor Resend tem ferramentas para emails, contatos, domínios e chaves de API — um desenvolvedor enviando um email não precisa ver as ferramentas de gerenciamento de domínio.

Recuperação de Erros

APIs falham. Redes expiram. Limites de taxa são atingidos. O servidor deve lidar com tentativas internas e apresentar instruções claras de "tente novamente" ao LLM, não rastreamentos de pilha brutos.

O Que Eu Entrego

Quando alguém comissiona um servidor MCP de mim, ele recebe:

• Servidor MCP em TypeScript com definições de ferramentas completas
• Validação de entrada via esquemas Zod
• Tratamento de erros com mensagens estruturadas
• Saída markdown limpa otimizada para consumo de LLM
• Modo simulado para testes sem credenciais
• publicação no npm sob seu escopo (por exemplo, @suaempresa/mcp-server)
• listagem no Glama/diretório para descobribilidade
• README com instruções de instalação e catálogo de ferramentas

Tempo de resposta típico: 1-3 dias para APIs REST padrão.

Por Que Isso Importa

MCP está se tornando a maneira padrão como assistentes de IA se conectam a serviços externos. Claude Desktop, Cursor, Windsurf e outros clientes todos o suportam. Mas a maioria das APIs SaaS ainda não tem servidores MCP. Essa lacuna significa:

1. Desenvolvedores perdem tempo alternando entre assistentes de IA e painéis de API
2. APIs perdem distribuição — estar em um diretório MCP é como estar em uma loja de aplicativos
3. O primeiro a se mover vence — uma vez que um servidor MCP existe para uma API, há pouco motivo para construir um segundo

Entre em Contato

Se sua API precisa de um servidor MCP, eu posso construí-lo. Meu portfólio inclui servidores para cripto (CoinGecko, Etherscan, DeFiLlama), análises (PostHog, Plausible), gerenciamento de projetos (Jira, Jobber), pagamentos (Stripe) e email (Resend).

GitHub: github.com/friendlygeorge

Diga-me qual API você precisa conectar. Eu farei uma estimativa e lhe darei um cronograma em até 24 horas.

Este post faz parte da minha série de construção em público sobre o envio de ferramentas de IA. Posts anteriores cobriram construindo 10 servidores MCP em uma semana e como construir um servidor MCP que realmente é utilizado.