Busque em todas as páginas da documentação
Cada capacidade que você adiciona a um servidor MCP deve se tornar uma Ferramenta, um Recurso ou um Prompt, e escolher o certo mantém seu servidor previsível para cada cliente que se conecta a ele.
Esta página aborda as decisões que você enfrentará com mais frequência ao projetar um servidor e classifica a escolha certa para cada uma.
Cenário: Um servidor precisa permitir que um cliente leia o conteúdo de um arquivo específico no disco.
| Classificação | Escolha | Abordagem |
|---|---|---|
| Melhor | Recurso | @mcp.resource("file://{path}") endereça o arquivo por URI e retorna seu conteúdo na leitura. |
| 2ª | Ferramenta | Uma ferramenta read_file(path: str) funciona, mas oculta o fato de que esta é uma leitura pura e cacheável. |
| 3ª | Prompt | Não se encaixa; prompts produzem instruções, não conteúdo bruto de arquivo. |
Escolha errada: Construir isso como uma ferramenta chamada get_file_action que também registra uma entrada de auditoria como efeito colateral, pois isso mistura uma leitura com uma escrita dentro de algo que os clientes presumirão ser seguro chamar repetidamente.
Por que o melhor é o melhor: Um recurso torna a natureza somente leitura explícita e permite que qualquer cliente o cache ou liste sem adivinhar efeitos colaterais.
Cenário: Um servidor precisa permitir que o modelo crie uma nova linha, como uma tarefa ou um ticket.
| Classificação | Escolha | Abordagem |
|---|---|---|
| Melhor | Ferramenta | Uma ferramenta create_task(title: str, priority: str) executa a inserção e retorna o novo id. |
| 2ª | Recurso | Não apropriado; recursos não devem mutar estado. |
| 3ª | Prompt | Não se encaixa; um prompt não pode executar uma gravação em banco de dados. |
Escolha errada: Expor a criação como uma URI de recurso como tasks://create?title=X, pois as leituras de recursos devem ser idempotentes e livres de efeitos colaterais, e um cliente pode reler sem esperar uma nova linha a cada vez.
Por que o melhor é o melhor: Uma ferramenta sinaliza claramente "isso realiza uma ação", e o modelo entende que chamá-la novamente pode criar um segundo registro.
Cenário: Vários clientes precisam que o modelo resuma documentos exatamente da mesma maneira, todas as vezes.
| Classificação | Escolha | Abordagem |
|---|---|---|
| Melhor | Prompt | Um modelo de prompt summarize_document empacota as instruções exatas e as regras de formatação uma vez. |
| 2ª | Ferramenta | Uma ferramenta summarize(text: str) poderia funcionar se a lógica de sumarização em si for executada no lado do servidor, não via modelo. |
| 3ª | Recurso | Não se encaixa; recursos contêm dados, não instruções. |
Escolha errada: Confiar que cada cliente escreva sua própria instrução ad hoc "por favor, resuma isso", pois a deriva na redação entre clientes produz resumos inconsistentes, mesmo para o mesmo documento. Por que o melhor é o melhor: Um Prompt é exatamente o primitivo projetado para instruções compartilhadas e versionadas que vários clientes invocam de forma consistente.
Cenário: Um servidor tem configurações (flags de recursos, limites, padrões) que um cliente ou modelo pode precisar ver.
| Classificação | Escolha | Abordagem |
|---|---|---|
| Melhor | Recurso | Um recurso estático config://settings retorna a configuração atual como JSON. |
| 2ª | Ferramenta | Uma ferramenta get_config() funciona, mas implica uma ação para o que é realmente uma leitura estática. |
| 3ª | Prompt | Não se encaixa; a configuração são dados, não instruções. |
Escolha errada: Codificar valores de configuração em cada modelo de prompt em vez de expô-los como um recurso, o que significa que cada modelo precisa ser editado sempre que uma configuração muda. Por que o melhor é o melhor: Um recurso é o local natural para qualquer coisa que seja "estado atual para ler", especialmente quando raramente ou nunca tem efeitos colaterais.
Cenário: O modelo precisa enviar um e-mail, postar uma mensagem ou chamar uma API externa que altera algo fora do servidor.
| Classificação | Escolha | Abordagem |
|---|---|---|
| Melhor | Ferramenta | Uma ferramenta send_email(to: str, subject: str, body: str) executa a chamada e relata sucesso ou falha. |
| 2ª | Recurso | Não apropriado; esta é uma ação com efeitos colaterais no mundo real. |
| 3ª | Prompt | Não se encaixa; um prompt não pode realizar uma chamada externa por conta própria. |
Escolha errada: Construir isso como um recurso que "envia" a cada leitura, pois um cliente que relê um recurso (para cache ou exibição) acionaria inesperadamente um segundo envio. Por que o melhor é o melhor: Uma ferramenta torna a ação explícita, e o modelo trata cada chamada como algo com uma consequência real, em vez de uma leitura segura e repetível.
Cenário: Uma equipe quer que cada cliente execute a revisão de código da mesma maneira, com a mesma lista de verificação e tom.
| Classificação | Escolha | Abordagem |
|---|---|---|
| Melhor | Prompt | Um prompt code_review com argumentos para a diferença e áreas de foco produz instruções consistentes. |
| 2ª | Ferramenta | Uma ferramenta run_static_analysis(path: str) poderia complementar o prompt para as partes mecânicas da revisão. |
| 3ª | Recurso | Não se encaixa por si só, embora as diretrizes de revisão também possam ser expostas como um recurso para referência. |
Escolha errada: Colar a lista de verificação de revisão no prompt do sistema de cada cliente separadamente, pois as atualizações precisam ser feitas em vários lugares e saem de sincronia.
Por que o melhor é o melhor: Um Prompt centraliza a instrução no servidor, para que cada cliente que invoca code_review receba a versão atual automaticamente.
Cenário: Uma ferramenta de suporte precisa que o modelo recupere o registro de um cliente por id.
| Classificação | Escolha | Abordagem |
|---|---|---|
| Melhor | Recurso | customers://{customer_id} endereça cada registro por um URI estável e cacheável. |
| 2ª | Ferramenta | Uma ferramenta get_customer(customer_id: str) funciona se a pesquisa também precisar impor regras de acesso dinâmicas por chamada. |
| 3ª | Prompt | Não se encaixa; prompts não buscam dados. |
Escolha errada: Construir uma única ferramenta search_customers que sempre retorna todos os campos correspondentes, independentemente do que o modelo realmente precisa, pois isso vaza mais dados no contexto do que o necessário.
Por que o melhor é o melhor: Um recurso indexado por id fornece uma maneira previsível, mínima e endereçável de buscar exatamente um registro.
Cenário: Vários aplicativos cliente precisam que o modelo sempre responda a um determinado tipo de solicitação em um formato JSON fixo.
| Classificação | Escolha | Abordagem |
|---|---|---|
| Melhor | Prompt | Um modelo de prompt com instruções explícitas de formato de saída, invocado da mesma maneira por cada cliente. |
| 2ª | Ferramenta | A saída estruturada da ferramenta pode impor o formato se a formatação ocorrer no código em vez da saída do modelo. |
| 3ª | Recurso | Não se encaixa; recursos não moldam a saída do modelo. |
Escolha errada: Confiar que os desenvolvedores de cada cliente se lembrem e copiem as instruções de formatação exatas em seus próprios prompts, pois mesmo pequenas diferenças na redação produzem formas de saída inconsistentes. Por que o melhor é o melhor: Um Prompt compartilhado garante que cada cliente envie ao modelo as mesmas instruções de formatação, byte a byte.
Esta operação muda alguma coisa? Se sim, é uma Ferramenta. Se apenas lê dados existentes, considere um Recurso. Se está empacotando instruções reutilizáveis em vez de dados ou uma ação, é um Prompt.
Às vezes, como uma pesquisa de dados que pode ser um recurso parametrizado ou uma ferramenta somente leitura. Prefira o Recurso quando os dados tiverem uma forma genuinamente estática e forem endereçáveis; prefira a Ferramenta quando a pesquisa precisar de lógica por chamada, como verificações dinâmicas de autorização.
Tornar tudo uma ferramenta oculta quais operações são leituras seguras e quais têm efeitos colaterais, o que torna o servidor mais difícil de raciocinar e pode levar o modelo a tratar ações destrutivas tão casualmente quanto uma pesquisa.
Construir todas as capacidades como ferramentas, mesmo leituras puras, porque as ferramentas são o análogo mais óbvio para a chamada de função. Isso oculta pesquisas de dados seguras e cacheáveis dentro do mesmo primitivo das ações destrutivas.
Um Recurso. Codificar a configuração em cada modelo de prompt significa que cada alteração de valor requer a edição de vários modelos em vez de um manipulador de recursos.
Sim. Muitos servidores úteis expõem apenas Ferramentas e Recursos; os Prompts valem a pena adicionar especificamente quando a consistência da redação entre vários clientes se torna um problema real e observado.
Uma Ferramenta geralmente cria ou atualiza dados, e um Recurso então expõe esses mesmos dados para leitura posterior, indexados pelo id que a ferramenta retornou.
Os clientes podem presumir que os recursos são seguros para ler repetidamente ou para cache. Um recurso com um efeito colateral oculto pode acionar ações repetidas indesejadas, como o envio de notificações duplicadas.
Se a pesquisa for uma leitura direta de id para registro, use um Recurso. Se precisar de lógica personalizada por chamada, como filtragem pelas permissões do usuário atual, uma Ferramenta lhe dá mais espaço para executar essa lógica antes de retornar um resultado.
Sim. Os clientes chamam list_tools(), list_resources() (e list_resource_templates()) e list_prompts() para descobrir o que um servidor oferece, independentemente de quais primitivos ele usa.
Um modelo de prompt pode ser escrito para incluir a URI ou o conteúdo de um recurso como parte de suas instruções geradas, fornecendo ao modelo tanto uma formulação consistente quanto dados relevantes em uma única invocação.
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 a especificação atual do Model Context Protocol. 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.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026