Com a popularização do Model Context Protocol (MCP), tornou-se relativamente simples conectar agentes de IA a sistemas existentes. Para empresas que já possuem APIs REST bem estruturadas, a primeira ideia costuma ser bastante natural: criar um servidor MCP e expor cada endpoint como uma tool.
A abordagem parece eficiente. Afinal, a API já possui contratos, autenticação, validações e operações bem definidas. Transformar essas operações em ferramentas permitiria que agentes utilizassem as mesmas capacidades disponíveis para aplicações web e mobile, sem precisar desenvolver uma nova camada de negócio.
O problema é que uma interface adequada para uma aplicação tradicional não é necessariamente uma boa interface para um agente de IA. APIs utilizadas por interfaces gráficas frequentemente refletem a maneira como uma aplicação apresenta e manipula recursos. Existem endpoints para listar registros, consultar detalhes, atualizar campos e executar ações específicas. O usuário navega entre telas, seleciona elementos e confirma operações, enquanto a aplicação mantém o contexto necessário para realizar cada chamada.
Um agente trabalha de maneira diferente. Ele recebe uma intenção, interpreta o resultado esperado e precisa descobrir quais ferramentas utilizar para alcançá-lo. Quando expomos diretamente a estrutura de uma API, transferimos para o agente a responsabilidade de reconstruir um fluxo que a própria aplicação já conhece.
Essa diferença merece atenção porque o MCP não deveria ser tratado apenas como uma nova forma de transportar chamadas HTTP. Ele também cria uma oportunidade para projetar interfaces orientadas às capacidades que queremos disponibilizar aos agentes.
Uma intenção simples pode exigir várias chamadas desnecessárias
Imagine um SaaS de gestão financeira que permite cadastrar contas a pagar e registrar pagamentos.
Sua API REST possui endpoints como:
GET /bills
GET /bills/{billId}
PATCH /bills/{billId}
POST /bills/{billId}/paymentsEsses endpoints podem ser perfeitamente adequados à aplicação web. O usuário visualiza uma lista de contas, seleciona uma delas, consulta os detalhes e registra o pagamento.
Agora considere que o mesmo usuário converse com um agente e solicite:
“Marque a conta de luz de outubro como paga.”
Se o servidor MCP simplesmente reproduzir a API, o agente precisará descobrir como combinar as ferramentas disponíveis. Ele pode chamar list_bills, procurar a conta correspondente, executar get_bill para confirmar os detalhes e finalmente utilizar create_bill_payment ou update_bill.
A depender da implementação, essa sequência pode exigir múltiplas interações com o modelo, respostas intermediárias e decisões sobre identificadores e estados do sistema.
Além do custo de latência e tokens, existe outro problema: o agente passa a assumir responsabilidades que deveriam pertencer à aplicação.
Determinar qual registro corresponde à conta de luz de outubro, verificar se ela já está paga, validar o período e aplicar as regras para registrar um pagamento são responsabilidades do domínio financeiro. Não deveriam depender exclusivamente da capacidade do modelo de interpretar uma lista de registros e escolher o identificador correto.
Uma alternativa é oferecer uma ferramenta diretamente associada à intenção:
record_bill_paymentEla poderia receber:
{
"bill_reference": "conta de luz",
"billing_month": "2026-10"
}Internamente, a ferramenta utiliza os serviços existentes para localizar a conta, verificar sua situação e registrar o pagamento conforme as regras do produto. Se a data do pagamento for necessária, mas não puder ser determinada com segurança, a ferramenta solicita essa informação antes de concluir a operação.
O agente continua responsável por compreender o pedido e selecionar a capacidade adequada. A aplicação permanece responsável pela lógica que determina como aquela intenção deve ser executada.
Essa separação reduz a quantidade de decisões operacionais transferidas ao modelo e preserva as regras de negócio onde elas já deveriam estar: no sistema.
Uma tool deve representar uma capacidade, não necessariamente um recurso
A diferença entre os dois modelos pode ser resumida assim:
| Interface orientada a recursos | Interface orientada à intenção |
|---|---|
list_bills | find_bill |
get_bill | get_bill_context |
update_bill | record_bill_payment |
update_bill_status | cancel_bill |
Os nomes são apenas exemplos. A distinção importante está no contrato oferecido.
Uma operação como update_bill costuma exigir que o consumidor conheça o identificador interno do registro e os campos que precisam ser modificados. Já record_bill_payment representa uma ação de negócio, com regras e consequências próprias.
A segunda ferramenta pode receber informações próximas da linguagem utilizada pelo usuário, como fornecedor, competência ou referência da conta. Cabe ao sistema resolver essas informações para um identificador interno, respeitando o contexto e as permissões da operação.
Isso também evita outro problema comum: fazer o agente manipular diretamente estados que deveriam ser consequência de operações de domínio.
Registrar um pagamento não precisa ser equivalente a atualizar um campo status para PAID. A operação pode exigir validação de valor, registro de data, prevenção de duplicidade, histórico e atualização de outros componentes. Permitir que o agente modifique o estado diretamente pode contornar parte dessas regras.
Essa abordagem se aproxima do conceito de operações orientadas ao domínio, em vez de simples manipulação de dados.
Não significa, entretanto, que todas as ferramentas devam executar processos completos. Ferramentas de busca, consulta e exploração continuam necessárias. Um agente que precisa analisar despesas de diferentes meses pode se beneficiar de operações granulares e filtros flexíveis.
A granularidade adequada depende da intenção. O importante é evitar que o agente tenha de reconstruir repetidamente processos de negócio que poderiam ser oferecidos como capacidades bem definidas.
O que uma boa tool deveria resolver internamente
Voltando ao exemplo da conta de luz, uma implementação mais robusta de record_bill_payment teria responsabilidades bastante claras.
Primeiro, precisaria localizar a conta a partir das informações recebidas, considerando apenas os registros aos quais o usuário possui acesso. Se existir uma única conta correspondente, o fluxo pode continuar. Se houver duas contas semelhantes, a ferramenta não deve escolher arbitrariamente uma delas: deve retornar as alternativas necessárias para esclarecer a ambiguidade.
Depois, o sistema verifica o estado atual. A conta já foi registrada como paga? Existe um pagamento parcial? A operação solicitada é permitida? É necessário confirmar o valor ou a data?
Somente depois dessas verificações a alteração deve ser persistida, utilizando os mecanismos transacionais e de idempotência apropriados.
Uma resposta bem estruturada poderia ser:
{
"status": "completed",
"bill": {
"description": "Energia elétrica",
"billing_month": "2026-10",
"amount": 248.90
},
"payment_recorded": true
}Se houver ambiguidade, o resultado deve expressar essa condição em vez de produzir uma alteração:
{
"status": "needs_clarification",
"reason": "multiple_matching_bills",
"candidates": [
{
"id": "bill_101",
"description": "Energia elétrica - Residência"
},
{
"id": "bill_205",
"description": "Energia elétrica - Escritório"
}
]
}Com esse contrato, o agente recebe informações suficientes para fazer a próxima pergunta ao usuário, sem precisar interpretar uma resposta HTTP genérica ou consultar novamente todos os registros.
O mesmo princípio vale para erros. Retornar apenas um 422 Unprocessable Entity pode ser adequado para determinados clientes HTTP, mas fornece pouco contexto para um agente decidir como proceder. Uma tool pode traduzir o erro de domínio para uma resposta estruturada que explique a condição e as alternativas permitidas.
A especificação do MCP contempla esse cenário por meio dos resultados de execução de ferramentas, incluindo erros de execução identificados por isError e conteúdo que pode orientar a correção da chamada.
Existe ainda uma distinção importante: marcar uma conta como paga em um sistema de controle financeiro não é o mesmo que executar uma transferência bancária. Operações com efeitos financeiros externos exigem autorizações, confirmações e controles proporcionais ao risco. Reduzir o número de chamadas não deve significar eliminar essas garantias.
Menos tools pode ajudar, mas quantidade não é o principal critério
Outro erro frequente é acreditar que a qualidade de um servidor MCP depende da quantidade de ferramentas que ele disponibiliza.
Expor cinquenta endpoints como cinquenta tools pode gerar sobreposição de responsabilidades, descrições difíceis de distinguir e fluxos que exigem várias chamadas para concluir tarefas simples. Dependendo do cliente e da estratégia de descoberta, também pode aumentar o consumo de contexto necessário para apresentar essas ferramentas ao modelo.
Por outro lado, tentar concentrar todas as operações em cinco ferramentas genéricas pode produzir o problema inverso. Uma tool com quinze parâmetros opcionais e múltiplos comportamentos possíveis se torna difícil de compreender, validar e utilizar corretamente.
Não existe um número universal de tools adequado para qualquer aplicação.
A recomendação mais útil é começar pelos fluxos que os usuários realmente precisam executar. Em um SaaS financeiro, por exemplo, podemos identificar capacidades como consultar contas em aberto, registrar pagamentos, consultar despesas por período e cancelar lançamentos. Cada uma representa uma intenção suficientemente clara para justificar uma ferramenta própria.
Em seguida, avaliamos quais operações precisam ser separadas. Consultar contas e registrar um pagamento, por exemplo, possuem riscos e requisitos de autorização distintos. Manter ferramentas de leitura separadas das operações que modificam dados costuma facilitar a governança e a seleção correta pelo agente.
A documentação da AWS sobre estratégias de MCP recomenda justamente equilibrar granularidade e escopo, priorizando operações orientadas a workflows sem transformar as ferramentas em interfaces excessivamente genéricas.
Também é importante considerar que alguns clientes conseguem descobrir e carregar ferramentas dinamicamente. Nesses cenários, uma quantidade grande de tools não implica necessariamente que todos os schemas serão enviados ao modelo em todas as interações.
O objetivo não é minimizar a contagem a qualquer custo, mas oferecer interfaces claras, distintas e eficientes.
A qualidade da interface precisa ser medida pela execução
Há um aspecto que considero especialmente importante: uma tool não deveria ser considerada bem projetada apenas porque seu schema parece simples.
Ela precisa funcionar bem quando um agente tenta resolver problemas reais.
Para avaliar um servidor MCP, podemos montar um conjunto de solicitações representativas do produto, incluindo situações comuns, entradas incompletas e cenários ambíguos:
- “Mostre minhas contas vencidas.”
- “Marque a conta de luz de outubro como paga.”
- “Quanto gastei com energia elétrica nos últimos três meses?”
- “Cancele o lançamento duplicado de internet.”
- “Registre este pagamento, mas não altere nenhuma outra conta.”
A avaliação deve observar se o agente seleciona a ferramenta correta, fornece parâmetros adequados, resolve ambiguidades sem inventar informações e conclui a intenção respeitando as regras do sistema.
Também vale medir quantidade de chamadas, latência, tokens consumidos, necessidade de intervenção humana e frequência de erros. Uma ferramenta que economiza duas chamadas, mas introduz decisões incorretas, não representa uma melhoria.
Esse processo permite identificar quando uma tool está granular demais, quando combina responsabilidades incompatíveis ou quando suas descrições não deixam claro em quais situações deve ser utilizada.
A Anthropic discute essa abordagem em Writing effective tools for agents, recomendando que ferramentas sejam projetadas e avaliadas a partir de tarefas reais, em vez de simplesmente reproduzirem as funcionalidades disponíveis nas APIs existentes.
O ponto central é que a ergonomia de uma interface para agentes precisa ser validada pela qualidade das tarefas concluídas, não apenas pela organização do código que implementa o servidor MCP.
E quando uma CLI é suficiente?
Existe ainda uma decisão arquitetural que merece atenção: nem toda integração com agentes precisa utilizar MCP.
Em ambientes de desenvolvimento e operações, muitos agentes já possuem acesso a ferramentas de terminal. Se o produto oferece uma CLI bem construída, com comandos previsíveis, documentação acessível, saída estruturada e códigos de retorno consistentes, ela pode ser uma interface bastante eficiente.
Considere um comando como:
finance bills pay \
--reference "conta de luz" \
--month 2026-10 \
--jsonSe esse comando possui comportamento bem documentado, autenticação adequada e as mesmas validações de domínio, ele pode atender à intenção do agente sem exigir uma camada MCP adicional.
Uma CLI também pode ser utilizada por pessoas, scripts e pipelines de automação, o que favorece o reaproveitamento da interface.
Isso não torna MCP desnecessário. O protocolo oferece um mecanismo padronizado de descoberta e invocação de ferramentas, contratos estruturados e integração com aplicações que não operam exclusivamente por terminal.
Além disso, oferecer acesso a um shell exige controles próprios de execução e permissões. Uma CLI utilizada por agentes não deveria herdar indiscriminadamente todo o poder de um ambiente operacional.
A escolha depende do contexto: quais agentes utilizarão a integração, como descobrem capacidades, onde executam e quais mecanismos de autenticação e governança estão disponíveis.
O ponto comum é que tanto uma CLI quanto um servidor MCP deveriam oferecer operações com significado claro para quem as utiliza, sem transferir desnecessariamente a lógica do negócio para o agente.
O MCP deve preservar a arquitetura, não duplicá-la
Uma boa estratégia para produtos que já possuem APIs REST é manter a camada de negócio existente e construir interfaces específicas para os diferentes consumidores.
A aplicação web pode continuar utilizando endpoints orientados à sua experiência de navegação. O servidor MCP pode expor capacidades orientadas à intenção. Uma CLI pode disponibilizar comandos adequados a operações de terminal.
Essas interfaces não precisam duplicar a implementação do domínio.
Por trás delas, os mesmos serviços de aplicação podem continuar responsáveis por validações, permissões, transações, idempotência e regras de negócio.
Essa separação evita um erro importante: implementar no servidor MCP uma segunda versão das regras que já existem no backend. Além de aumentar o custo de manutenção, isso cria o risco de diferentes canais executarem a mesma operação de maneiras incompatíveis.
Também reforça uma responsabilidade fundamental: o agente pode sugerir a intenção e fornecer parâmetros, mas não deve ser a autoridade final sobre permissões, identidades e restrições de negócio.
Essas garantias precisam permanecer no sistema, independentemente de a operação ter sido iniciada por uma interface web, uma CLI ou um agente.
A interface para agentes começa no problema que queremos resolver
MCP facilita a conexão entre agentes e sistemas, mas não elimina a necessidade de projetar boas interfaces.
Simplesmente transformar endpoints REST em tools é uma maneira rápida de disponibilizar funcionalidades existentes. Em protótipos ou APIs que já representam operações de domínio bem definidas, isso pode ser perfeitamente suficiente.
O problema surge quando confundimos facilidade de exposição com qualidade do contrato oferecido.
Interfaces tradicionais frequentemente organizam recursos para que aplicações construam experiências sobre eles. Agentes precisam de capacidades que permitam executar intenções com o mínimo necessário de ambiguidade, contexto e coordenação.
Isso não significa esconder toda a complexidade ou impedir operações granulares. Significa definir conscientemente quais responsabilidades pertencem ao agente e quais deveriam continuar dentro do sistema.
Para quem está construindo um SaaS ou micro-SaaS com suporte a agentes, essa decisão merece ser tomada desde o desenho das capacidades do produto. Uma API bem estruturada continua sendo valiosa, mas seu modelo de recursos não precisa determinar automaticamente o catálogo de ferramentas MCP.
Uma boa tool não é aquela que oferece ao agente acesso a mais um endpoint. É aquela que permite executar uma intenção com segurança, clareza e o menor número possível de decisões desnecessárias.
Referências
- Model Context Protocol — Tools Specification. Contratos de ferramentas, schemas, resultados e tratamento de erros no MCP.
- Anthropic — Writing effective tools for agents. Princípios de projeto, escopo, eficiência de contexto e avaliação de ferramentas para agentes.
- AWS Prescriptive Guidance — MCP Tool Scope. Comparação entre ferramentas granulares e orientadas a workflows, incluindo recomendações de desenho.
- AWS Prescriptive Guidance — MCP Tool Discovery. Estratégias de descoberta e disponibilização de ferramentas para agentes.
