Melhores Práticas para Servidores e Clientes MCP

Todas as práticas nesta página remontam a um modo de falha real coberto em outra parte desta seção: uma ferramenta que nunca apareceu porque não foi registrada, uma alteração de esquema que quebrou um cliente existente, um servidor compartilhado sem limitação de taxa que um chamador poderia esgotar.

Use isso como uma verificação pré-voo antes de mover um servidor do desenvolvimento local para qualquer coisa compartilhada ou remota.

Como Usar Esta Lista de Verificação

• Percorra-a de cima a baixo na primeira vez que implantar um novo servidor, projetando primeiro a ferramenta/recurso e, por último, os testes.
• Revise as seções C a E (transporte, autenticação, versionamento) sempre que alterar como ou onde um servidor é implantado.
• Nem todas as regras se aplicam a todos os servidores; uma ferramenta stdio puramente local não tem necessidade real de autenticação ou limitação de taxa.
• Trate um item não marcado como uma lacuna conhecida, não um bloqueador, mas um que você deve ser capaz de explicar se for perguntado.

A - Design de Ferramentas, Recursos e Prompts

• Dê a cada ferramenta um nome claro e orientado para a ação e uma docstring que descreva o que ela faz e quaisquer restrições em seus argumentos. Isso é o que Claude e os desenvolvedores humanos usam para decidir se e como chamá-la.
• Use dicas de tipo precisas ou esquemas para cada argumento, incluindo conjuntos de valores fixos, em vez de um str solto. Um tipo vago produz um esquema que não oferece orientação real ao cliente sobre entradas válidas.
• Use uma ferramenta para qualquer coisa com efeitos colaterais e um recurso para qualquer coisa que seja puramente dados somente leitura. Misturar os dois confunde como um cliente apresenta a capacidade e como ele raciocina sobre a segurança.
• Levante exceções reais para casos de falha em vez de retornar uma string de erro como se fosse um sucesso. Uma string retornada parece um resultado válido para o cliente; uma exceção é convertida em um erro estruturado adequado.
• Mantenha cada servidor focado em um conjunto coerente de capacidades relacionadas, em vez de uma grande superfície "catch-all". Um servidor com dezenas de ferramentas não relacionadas é mais difícil de raciocinar tanto para Claude quanto para os mantenedores.

B - Ciclo de Vida da Requisição e Registro

• Verifique se cada manipulador implementado está realmente registrado, não apenas escrito. Uma função de ferramenta que existe, mas nunca foi decorada, é invisível para qualquer cliente conectado, a fonte mais comum de "minha ferramenta não aparece".
• Confirme se a negociação de capacidade é bem-sucedida antes de assumir que qualquer ferramenta, recurso ou prompt é alcançável. Nada na fase de troca do ciclo de vida funciona até que a negociação seja concluída.
• Trate cada chamada de ferramenta como independente, a menos que você tenha construído deliberadamente um estado com escopo de sessão. O protocolo não garante ordem entre as chamadas; confiar na memória implícita entre as chamadas é uma fonte comum de bugs sutis.
• Mantenha o estado por sessão separado quando um servidor lida com várias sessões de cliente simultâneas. Misturar estado entre sessões é um bug de correção, não apenas de desempenho.

C - Escolha de Transporte

• Use stdio como padrão para desenvolvimento local e ferramentas de usuário único. Não tem configuração de rede, nenhuma porta para gerenciar e o loop de reinicialização mais rápido possível enquanto uma superfície de ferramenta ainda está mudando.
• Mude para HTTP/SSE quando mais de um cliente, máquina ou equipe precisar acessar o mesmo servidor. O stdio inicia um processo separado por cliente, o que não funciona para estado compartilhado ou acesso coordenado a um backend.
• Trate uma migração de stdio para HTTP/SSE como uma troca de transporte, não uma reescrita. Manipuladores de ferramentas, recursos e prompts são agnósticos ao transporte em ambos os SDKs oficiais; a migração é principalmente sobre adicionar autenticação e trocar a camada de conexão.

D - Autenticação e Controle de Acesso

• Nunca exponha um servidor HTTP/SSE sem autenticação, mesmo para o que parece ser uma implantação interna ou temporária. Qualquer coisa alcançável por rede por partes que você não confia totalmente precisa de um limite na frente dela.
• Aplique autenticação na camada de conexão, antes que o transporte MCP seja alcançado, não dentro de manipuladores de ferramentas individuais. Quando um manipulador é executado, a negociação já expôs o manifesto de capacidade do servidor.
• Use hmac.compare_digest ou uma verificação de tempo constante equivalente para qualquer comparação de segredo. Uma comparação == ingênua pode vazar informações de tempo que ajudam um invasor a adivinhar um token válido.
• Escolha autenticação baseada em token para um conjunto pequeno e conhecido de clientes confiáveis e OAuth para um público mais amplo ou de terceiros. Combine a complexidade do esquema com quem está realmente se conectando, em vez de usar a opção mais pesada em todos os lugares.
• Termine TLS na frente de qualquer implantação HTTP/SSE. Enviar tokens ou códigos OAuth sobre HTTP puro os expõe a qualquer pessoa que observe o caminho da rede, derrotando o esquema de autenticação completamente.

E - Limitação de Taxa e Carga de Produção

• Chaveie as limitações de taxa pela identidade do cliente resolvida, não por um único contador global. Um contador compartilhado permite que um chamador de alto volume esgote o limite para todos os outros clientes.
• Escolha uma estratégia de limitação de taxa que corresponda ao seu formato de tráfego: janela fixa para tráfego estável e simples; janela deslizante ou balde de tokens para tráfego legítimo e com picos. Uma janela fixa muito rígida causa rejeições falsas bem na fronteira de reinicialização.
• Adicione limitação de taxa apenas quando um servidor for genuinamente compartilhado. Ele adiciona complexidade real que uma ferramenta stdio de usuário único não precisa carregar.
• Retorne um erro claro e distinguível quando um cliente for limitado pela taxa, em vez de uma falha genérica ambígua. O chamador, ou Claude, precisa reconhecê-lo como um limite de taxa e recuar, não tentar novamente cegamente.

F - Versionamento de Esquema

• Adicione novos argumentos de ferramenta como opcionais com padrões sensatos, nunca renomeie ou remova os existentes sem um plano. Clientes existentes que chamam com o formato antigo falharão na validação do esquema imediatamente.
• Envie alterações genuinamente incompatíveis como um novo nome de ferramenta em vez de mutar o existente. Forçar uma mudança incompatível no mesmo nome significa que todos os clientes conectados precisam atualizar simultaneamente.
• Dê a qualquer ferramenta ou campo depreciado um aviso de depreciação visível em sua descrição, com uma janela de remoção definida. Uma remoção silenciosa quebra os clientes sem nenhum aviso.
• Trate os argumentos da ferramenta como um contrato público, com o mesmo cuidado que você aplicaria a uma API pública, não a uma assinatura de função interna. Clientes que você não controla dependem do formato exato que você publicou.

G - Testes Antes da Implantação

• Escreva testes unitários que chamam diretamente as funções de manipulador de ferramentas e recursos, cobrindo o caminho feliz e pelo menos uma falha de validação por manipulador. Feedback rápido para a lógica de negócios sem a sobrecarga da camada de protocolo.
• Escreva pelo menos um teste de integração que inicie o servidor real e o execute através de uma sessão de cliente. Esta é a única camada que captura uma ferramenta que está implementada corretamente, mas nunca registrada.
• Teste se a entrada inválida aparece como um erro estruturado através do cliente real, não apenas dentro da função testada unitariamente. Confirma que a falha realmente chega ao cliente de forma limpa, em vez de travar o processo do servidor.
• Adicione um teste de integração que exercite a autenticação quando o servidor for implantado via HTTP/SSE. Token válido é bem-sucedido, token ausente ou inválido é rejeitado; ambos precisam de cobertura antes de uma implantação remota.
• Reexecute os testes de integração após qualquer alteração de esquema para capturar uma regressão contra clientes que usam o formato de argumento mais antigo. Os testes servem como uma rede de segurança para a disciplina de versionamento na seção F.

FAQs

Relacionado

• Como Servidores MCP Lidam com Requisições - o ciclo de vida por trás das seções A e B
• Comparação de Implantação MCP stdio vs HTTP/SSE - a decisão de transporte por trás da seção C
• Autenticando Servidores MCP Remotos - detalhes completos por trás da seção D
• Referência de Versionamento e Limitação de Taxa de Esquemas de Ferramentas MCP - detalhes completos por trás das seções E e F
• Testando Servidores MCP Antes da Implantação - detalhes completos por trás da seção G

Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e os SDKs atuais do Model Context Protocol Python/TypeScript. Nomes de modelos, versões de SDK e a especificação MCP mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs e modelcontextprotocol.io antes de confiar neles.