//
Busque em todas as páginas da documentação
Projetar um servidor MCP bem significa que cada ferramenta, recurso e prompt é previsível para os clientes e modelos que o utilizam, não apenas funcional em seus próprios testes.
Este checklist reúne as práticas que valem a pena seguir em esquemas de ferramentas, URIs de recursos, modelos de prompt e como você implanta o próprio servidor.
create_task é lido como uma ação; task ou handle não fornece ao modelo nada para corresponder à intenção.Args: para cada ferramenta. A docstring é o texto principal que o modelo usa para julgar a relevância, e as notas por argumento esclarecem unidades e formatos que um hint de tipo sozinho não pode expressar.mode ou action esconde múltiplos comportamentos por trás de um único esquema e torna a seleção do modelo menos confiável.Literal, ou modelos Pydantic para validar entradas antes que seu handler seja executado. Isso captura argumentos incorretos como um erro de esquema em vez de uma falha em tempo de execução dentro do seu código.None ou uma string vazia. Uma falha silenciosa não dá ao modelo nenhum sinal de que algo deu errado.articles://{id} ou docs://{filename} torna os recursos previsíveis para descobrir e raciocinar sobre.Grupo A, design de ferramentas. A maioria dos primeiros servidores é construída em torno de ferramentas, e a maioria dos problemas de seleção de modelo remonta a nomes vagos, docstrings finas ou esquemas de ferramentas excessivamente amplos.
Sim. Muitos servidores úteis expõem apenas ferramentas e recursos. Prompts valem o esforço de design especificamente quando a consistência de redação entre múltiplos clientes é uma necessidade real e observada.
Porque os modos de falha são diferentes: problemas de ferramentas geralmente aparecem como o modelo chamando a coisa errada ou com argumentos ruins, enquanto problemas de recursos geralmente aparecem como vazamento de dados, travessia de diretório ou efeitos colaterais ocultos.
Construir toda capacidade como uma ferramenta, incluindo leituras puras, o que enterra buscas de dados seguras na mesma primitiva que ações destrutivas e torna o servidor mais difícil de raciocinar.
Sempre que o servidor passar de um protótipo local para ser compartilhado com uma equipe ou exposto remotamente; as preocupações de rede e autenticação nesse grupo só se aplicam quando um servidor sai de uma única máquina confiável.
Hints de tipo simples são suficientes para argumentos escalares simples. Recorra a um modelo Pydantic quando uma ferramenta precisar de restrições em nível de campo, estruturas aninhadas ou lógica de validação reutilizada em várias ferramentas.
Rígida o suficiente para que um caminho resolvido seja sempre verificado contra o diretório raiz pretendido antes que qualquer leitura ocorra, pois um nome de arquivo bruto ou parâmetro de caminho nunca deve ser confiado diretamente do chamador.
Sim. stdio é o padrão mais simples com a menor sobrecarga operacional. Mude para HTTP/SSE (ou um túnel) apenas quando tiver uma necessidade concreta de múltiplos clientes ou persistência independente.
Redes internas ainda têm múltiplos usuários e serviços que não devem ter acesso igual. Trate um servidor HTTP/SSE interno com a mesma disciplina de autenticação que qualquer outro serviço interno.
Muitas vezes sim, se mais de um aplicativo cliente dessa equipe invocar a mesma instrução. A centralização ainda evita a deriva mesmo dentro de uma única equipe, uma vez que mais de uma base de código depende da redação.
Se ela acumular muitos parâmetros opcionais para cobrir casos de uso não relacionados, ou ganhar um flag mode/action que ramifica para comportamentos diferentes, esse é um forte sinal para dividi-la em ferramentas mais estreitas.
Versões de Stack: Escrito contra a linha de modelos Claude atual a partir de ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e a especificação atual do Model Context Protocol. Nomes de modelos, versões de SDK e a especificação MCP se movem rapidamente - verifique os detalhes atuais em platform.claude.com/docs e modelcontextprotocol.io antes de depender deles.