MCP Design Patterns: Construindo Servidores que Agentes Realmente Conseguem Usar

O Model Context Protocol tem 97 milhões de downloads mensais do SDK. Também é culpado por agentes que alucinam, estouro de contexto e comportamento imprevisível.

O protocolo não é o problema. O design do seu servidor é.

Essa é a tese de Philipp Schmid, Technical Lead no Google DeepMind e criador do mcp-cli. Sua análise revela um erro fundamental que a maioria dos desenvolvedores comete: tratar MCP como wrapper de REST API.

A Mudança Mental Necessária

MCP não é uma API. É uma interface de usuário para agentes de IA.

Essa distinção parece sutil mas tem consequências profundas. Agentes têm restrições cognitivas diferentes de desenvolvedores humanos:

Aspecto	REST APIs (Desenvolvedores)	MCP Tools (Agentes)
Discovery	Barato - lê documentação uma vez	Caro - schema carregado a cada request
Composição	Combina endpoints pequenos livremente	Multi-step calls atrasam iteração
Flexibilidade	Mais opções = melhor DX	Complexidade causa alucinação

Quando você porta padrões de REST API diretamente para MCP, cria operações CRUD granulares que forçam agentes em cadeias de múltiplos passos. Cada ferramenta adicional consome contexto, aumenta chance de erro, e desacelera o loop de raciocínio.

Seis Práticas Essenciais

1. Resultados, Não Operações

O erro mais comum: expor operações de infraestrutura em vez de resultados que o agente precisa.

Ruim - três ferramentas separadas:

get_user_by_email(email)
list_orders(user_id)
get_order_status(order_id)

Bom - uma ferramenta focada em resultado:

track_latest_order(email) -> {status, eta, tracking_url}

O objetivo do agente é “rastrear um pedido”. Dê a ele uma ferramenta que faz exatamente isso. Não force o agente a orquestrar três chamadas para alcançar um objetivo simples.

2. Achate Seus Argumentos

Dicionários aninhados são convites para alucinação.

Ruim - estrutura flexível:

search_orders(filters: dict)

Bom - primitivos com restrições:

search_orders(
    email: str,
    status: Literal["pending", "shipped", "delivered"],
    limit: int = 10
)

Tipos restritos reduzem alucinação. O agente não pode inventar valores de status inválidos quando as opções são explícitas.

3. Instruções São Contexto

Cada docstring, descrição de parâmetro e mensagem de erro influencia o comportamento do agente. Isso não é documentação para humanos — é input de direcionamento para o modelo.

O que incluir:

Quando usar a ferramenta
Formatos de input esperados
Estrutura do output
Mensagens de erro úteis, não exceções técnicas

Um agente que recebe “status must be one of: pending, shipped, delivered” sabe como corrigir. Um que recebe “KeyError: status” não.

4. Curadoria Implacável

Meta: 5-15 ferramentas por servidor.

Cada ferramenta consome espaço na janela de contexto com sua descrição, schema de resposta e mensagens de erro potenciais. Schmid orienta: “Foque em discovery sobre exposição exaustiva de features.”

Ponto de referência: Claude Code usa aproximadamente 12 ferramentas. Manus usa menos de 20. Esses são sistemas de produção construídos por times que entendem economia de contexto.

5. Nomeie Ferramentas para Discovery

Padrão: {serviço}_{ação}_{recurso}

Exemplos:

slack_send_message
linear_list_issues
sentry_get_error_details

Prefixo de serviço previne colisões de nome e ajuda agentes a entender a proveniência da ferramenta.

6. Pagine Resultados Grandes

Inclua parâmetro limit (padrão 20-50)
Retorne metadados: has_more, next_offset, total_count
Nunca carregue resultados ilimitados na memória

Resultados sem paginação podem estourar o contexto do agente e causar comportamento errático.

Governança Através do Design

Aqui está onde as práticas de MCP conectam com governança de IA:

Tipos restritos = agentes não podem inventar valores inválidos. Isso não é apenas boa prática de código — é um mecanismo de controle que previne comportamento inesperado.

Ferramentas focadas em resultado = superfície de ataque reduzida. Menos operações expostas significa menos vetores para prompt injection ou uso indevido.

Conjuntos curados de ferramentas = limites de capacidade explícitos. Você sabe exatamente o que o agente pode e não pode fazer.

Paginação = consumo de recursos limitado. O agente não pode consumir recursos indefinidamente em uma única chamada.

Isso alinha com uma filosofia de governança de IA: o controle vem de restrições de design, não de monitoramento pós-fato.

O Contexto Enterprise

A maioria dos clientes enterprise que se aproximam de MCP pensam em termos de REST API. Eles têm APIs existentes e querem expô-las para agentes.

A conversa educacional é esta: “Você não está construindo uma API. Está projetando uma interface de usuário para uma entidade com restrições cognitivas diferentes dos seus desenvolvedores.”

Essa mudança de perspectiva é o primeiro passo para implementações MCP que funcionam.

Checklist de Avaliação

Use esses critérios para avaliar servidores MCP:

Quantidade de ferramentas:

Servidor tem 15 ou menos ferramentas?
Cada ferramenta serve um objetivo claro do agente?

Design de ferramenta:

Ferramentas são focadas em resultado, não em operação?
Argumentos são primitivos com tipos restritos?
Nomes seguem padrão serviço_ação_recurso?

Contexto e documentação:

Descrições explicam quando usar cada ferramenta?
Formatos de input/output são documentados?
Mensagens de erro são acionáveis?

Gestão de recursos:

Resultados grandes são paginados?
Limites padrão são razoáveis (20-50)?
Metadados de paginação estão incluídos?

Alternativas e Complementos

As práticas de Schmid não são as únicas abordagens. Considere também:

Tool RAG: Busca semântica em índices grandes de ferramentas, carregando apenas ferramentas relevantes por tarefa. Isso permite conjuntos maiores de ferramentas sem sobrecarregar o contexto.

Mascaramento Dinâmico de Ferramentas: A abordagem do Manus — manter muitas ferramentas mas controlar visibilidade via máquinas de estado. Ferramentas aparecem apenas em contextos apropriados.

Organização Hierárquica: Meta-ferramentas que expõem sub-capacidades sob demanda. “database_query” pode expandir para operações específicas quando necessário.

Essas abordagens são complementares, não excludentes. A curadoria agressiva é o ponto de partida; técnicas avançadas permitem escalar.

Considerações de Segurança

O artigo original foca em otimização de performance. Para enterprise, adicione:

Autenticação e Autorização: MCP não tem mecanismos de segurança inerentes. OAuth 2.1, princípio de menor privilégio e validação de input são responsabilidades do implementador.

Trilhas de Auditoria: Registre todas as chamadas de ferramenta para compliance e debugging.

Governança de Ferramentas: Versionamento, ciclo de vida e controle de mudanças para ferramentas em produção.

Superfície de Ataque: Cada ferramenta é um vetor potencial. Minimize exposição, valide inputs, e considere sandbox para operações sensíveis.

Conclusão

MCP tem 97 milhões de downloads mensais. A adoção só vai crescer. A diferença entre implementações que funcionam e que frustram está no design.

Pare de expor infraestrutura. Comece a projetar resultados.

Os melhores servidores MCP não parecem APIs. Parecem ferramentas construídas com propósito que entendem o que o agente está tentando alcançar.

Seis práticas. Checklist de avaliação. Mentalidade de interface de usuário, não de API.

Esse é o caminho para servidores MCP que agentes realmente conseguem usar.

No Victorino Group, implementamos MCP com governança para empresas que precisam de agentes confiáveis. Se você quer servidores que funcionam e que você controla, vamos conversar.