Comparação: Ferramentas, Recursos e Prompts do MCP
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.
Como Usar Esta Comparação
- Leia cada cenário e verifique qual primitivo corresponde à forma do que você está construindo, não apenas ao que parece conveniente codificar primeiro.
- Quando uma capacidade puder se encaixar plausivelmente em dois primitivos, prefira aquele cujas semânticas (ação vs dados vs instrução) correspondam ao modelo mental do leitor sobre o que está acontecendo.
- Revise essas decisões à medida que um servidor cresce; uma capacidade que começou como uma ferramenta às vezes revela um recurso ou prompt mais limpo por baixo dela.
- Trate as entradas de "Escolha errada" como erros reais que valem a pena evitar, não apenas casos extremos teóricos.
Decisão 1: Buscando o conteúdo de um arquivo
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.
Decisão 2: Criando um novo registro em um banco de dados
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.
Decisão 3: Padronizando como o modelo resume um documento
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.
Decisão 4: Expondo a configuração atual do servidor
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.
Decisão 5: Enviando uma notificação ou realizando uma chamada externa
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.
Decisão 6: Orientando um fluxo de trabalho de revisão de código de várias etapas
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.
Decisão 7: Permitindo que o modelo pesquise um registro de cliente específico
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.
Decisão 8: Aplicando um formato de saída específico em todos os clientes
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.
Aplicando Esta Comparação na Prática
- Comece perguntando se a capacidade muda alguma coisa: se sim, é uma Ferramenta; se for puramente uma leitura, considere um Recurso primeiro.
- Use um Prompt apenas quando a consistência da redação entre vários clientes for o problema real que você está resolvendo, não apenas porque você deseja economizar algumas linhas de texto.
- A maioria dos servidores de produção usa os três primitivos juntos: Ferramentas para ações, Recursos para os dados que essas ações tocam e Prompts para as instruções que os unem de forma consistente.
FAQs
Qual é a pergunta mais importante a se fazer ao escolher um primitivo?
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.
Uma capacidade pode legitimamente ser construída como uma Ferramenta ou um Recurso?
À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.
Por que não tornar tudo uma Ferramenta para simplificar?
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.
Quando vale a pena o esforço extra de design para um Prompt?
- Quando mais de um cliente precisa da mesma redação de instrução exata.
- Quando você deseja versionar e atualizar instruções em um local em vez de muitos.
- Quando a consistência da saída é importante em toda uma equipe ou produto.
Qual é o erro mais comum que as equipes cometem ao projetar seu primeiro servidor MCP?
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.
Valores de configuração devem ser um Recurso ou codificados em Prompts?
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.
É correto ter zero Prompts em um servidor?
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.
Como Ferramentas e Recursos normalmente trabalham juntos?
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.
Qual é o risco de usar um Recurso para algo com efeitos colaterais?
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.
Como devo decidir entre uma Ferramenta de pesquisa e um Recurso de pesquisa?
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.
Todos os três primitivos precisam ser descobertos pelo cliente?
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 Prompt pode referenciar um Recurso dentro de suas mensagens geradas?
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.
Relacionado
- Entendendo MCP: Ferramentas, Recursos e Prompts - a base conceitual por trás de cada primitivo.
- Definindo Ferramentas Chamáveis em um Servidor MCP - design de esquema e manipulador para ferramentas.
- Expondo Dados Legíveis como Recursos MCP - design de URI para recursos.
- Construindo Modelos de Prompt Reutilizáveis com Prompts MCP - projetando prompts compartilhados e parametrizados.
- Melhores Práticas de Conceitos Principais do MCP - uma lista de verificação para aplicar essas decisões de forma consistente.
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.