Guia de Desenvolvimento de Servidores MCP

Modificado em AAS em 2026-09-05: exemplos com escopo de versão e avaliação limitada.

Visão Geral

Crie servidores MCP (Model Context Protocol) que permitem que LLMs interajam com serviços externos por meio de ferramentas bem projetadas. A qualidade de um servidor MCP é medida pela forma como ele permite que LLMs realizem tarefas do mundo real.

Processo

🚀 Fluxo de Trabalho de Alto Nível

Criar um servidor MCP de alta qualidade envolve quatro fases principais:

Fase 1: Pesquisa Profunda e Planejamento

1.1 Entenda o Design Moderno de MCP

Cobertura de API vs. Ferramentas de Fluxo de Trabalho: Equilibre a cobertura abrangente de endpoints de API com ferramentas de fluxo de trabalho especializadas. Ferramentas de fluxo de trabalho podem ser mais convenientes para tarefas específicas, enquanto a cobertura abrangente dá aos agentes flexibilidade para compor operações. O desempenho varia por cliente — alguns clientes se beneficiam da execução de código que combina ferramentas básicas, enquanto outros funcionam melhor com fluxos de trabalho de nível superior. Comece com as operações mínimas necessárias para o fluxo de trabalho autorizado do usuário. Expanda a cobertura a partir de lacunas observadas.

Nomenclatura e Descoberta de Ferramentas: Nomes de ferramentas claros e descritivos ajudam os agentes a encontrar as ferramentas certas rapidamente. Use prefixos consistentes (por exemplo, github_create_issue, github_list_repos) e nomenclatura orientada para a ação.

Gerenciamento de Contexto: Agentes se beneficiam de descrições concisas de ferramentas e da capacidade de filtrar/paginar resultados. Projete ferramentas que retornem dados focados e relevantes. Alguns clientes suportam execução de código, o que pode ajudar os agentes a filtrar e processar dados de forma eficiente.

Mensagens de Erro Acionáveis: Mensagens de erro devem guiar os agentes em direção a soluções com sugestões específicas e próximos passos.

1.2 Estude a Documentação do Protocolo MCP

Navegue pela especificação MCP:

Comece com o mapa do site para encontrar páginas relevantes: https://modelcontextprotocol.io/sitemap.xml

Em seguida, obtenha páginas específicas com o sufixo .md para formato markdown (por exemplo, https://modelcontextprotocol.io/specification/2025-11-25/index).

Páginas importantes para revisar:

• Visão geral e arquitetura da especificação
• Mecanismos de transporte (HTTP streamable, stdio)
• Definições de ferramentas, recursos e prompts

1.3 Estude a Documentação do Framework

Escolha a pilha compatível com o projeto:

• Linguagem: TypeScript ou Python, de acordo com o runtime existente e o cliente testado
• Transporte: HTTP streamable para servidores remotos, usando JSON stateless (mais simples de escalar e manter, em oposição a sessões stateful e respostas em streaming). stdio para servidores locais.

Carregue a documentação do framework:

• Melhores Práticas MCP: 📋 Ver Melhores Práticas - Diretrizes principais

Para TypeScript (recomendado):

• SDK TypeScript: Use uma ferramenta de navegador ou HTTP somente leitura disponível para carregar https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
• ⚡ Guia TypeScript - Padrões e exemplos TypeScript

Para Python:

• SDK Python: Use uma ferramenta de navegador ou HTTP somente leitura disponível para carregar https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
• 🐍 Guia Python - Padrões e exemplos Python

1.4 Planeje Sua Implementação

Entenda a API: Revise a documentação da API do serviço para identificar endpoints chave, requisitos de autenticação e modelos de dados. Use ferramentas de pesquisa somente leitura disponíveis conforme necessário.

Seleção de Ferramentas: Liste as operações e permissões exatas necessárias para a tarefa. Mantenha as ferramentas de escrita separadas e exija autorização na fronteira do servidor.

Fase 2: Implementação

2.1 Configure a Estrutura do Projeto

Veja os guias específicos da linguagem para configuração do projeto:

• ⚡ Guia TypeScript - Estrutura do projeto, package.json, tsconfig.json
• 🐍 Guia Python - Organização de módulos, dependências

2.2 Implemente a Infraestrutura Principal

Crie utilitários compartilhados:

• Cliente de API com autenticação
• Auxiliares de tratamento de erros
• Formatação de resposta (JSON/Markdown)
• Suporte à paginação

2.3 Implemente Ferramentas

Para cada ferramenta:

Esquema de Entrada:

• Use Zod (TypeScript) ou Pydantic (Python)
• Inclua restrições e descrições claras
• Adicione exemplos nas descrições dos campos

Esquema de Saída:

• Defina outputSchema sempre que possível para dados estruturados
• Use structuredContent nas respostas das ferramentas (recurso do SDK TypeScript)
• Ajuda os clientes a entender e processar as saídas das ferramentas

Descrição da Ferramenta:

• Resumo conciso da funcionalidade

…