O problema
Um time quer automatizar a triagem de tickets de suporte. Alguém sugere "vamos usar o Claude Code pra isso". Outra pessoa sugere "não, isso é caso de MCP server". Uma terceira acha que basta chamar a API direto do backend. As três podem estar certas — a pergunta errada é "qual ferramenta eu já conheço melhor", a pergunta certa é "qual superfície carrega esse trabalho com a menor complexidade possível".
Claude Code, o Claude Agent SDK, a API de Messages direta e o Model Context Protocol não são camadas de uma mesma pilha em ordem de sofisticação. São superfícies com propósitos diferentes, e usar a errada não é "menos elegante" — é mais caro de manter, mais difícil de testar, ou simplesmente não resolve o requisito.
As quatro superfícies e o que cada uma resolve
API de Messages direta é a camada mais básica: uma chamada, uma resposta, sem estado entre chamadas a não ser o que você reenvia. Certa para uma aplicação que já tem sua própria orquestração e só precisa de inferência pontual — um endpoint de resumo, um classificador embutido num pipeline existente.
Claude Agent SDK adiciona um harness em volta da API: gerenciamento de sessão, hooks, subagentes, e o loop de ferramentas já resolvido pra você. Certo quando a aplicação precisa de comportamento agêntico persistente — múltiplos turnos, delegação, controles determinísticos que um prompt sozinho não garante.
Claude Code é uma aplicação de desenvolvimento de software com o Agent SDK por baixo, configurável via CLAUDE.md, comandos e Skills. Certo para fluxos de trabalho de engenharia — não é a ferramenta certa pra construir uma aplicação de produção voltada ao cliente final.
MCP não é uma alternativa às outras três — é o protocolo que expõe ferramentas e recursos de forma padronizada para qualquer uma delas consumir. A pergunta não é "Agent SDK ou MCP", é "esse conjunto de ferramentas deveria ser um MCP server reutilizável, ou uma função chamada direto dentro do meu código".
O critério: requisito, não familiaridade
O erro mais comum não é escolher tecnicamente errado — é escolher pela superfície que a pessoa já sabe usar. Um engenheiro que vive no Claude Code tende a empurrar tudo pra lá, inclusive coisas que deveriam ser uma chamada de API direta dentro de um serviço já existente.
O framework de decisão é simples de enunciar e difícil de aplicar sob pressão:
- A tarefa precisa de estado entre múltiplos turnos? Se não, API direta resolve — não adicione um harness pra uma chamada única.
- A tarefa precisa de ferramentas reutilizáveis por múltiplos clientes ou agentes? Se sim, isso é candidato a MCP server, não a lógica embutida.
- A tarefa é sobre o próprio processo de desenvolvimento (gerar código, revisar PR, rodar testes)? Isso é Claude Code, não uma aplicação separada.
- A tarefa é uma aplicação de produção com comportamento agêntico contínuo? Isso é Agent SDK.
Um distrator comum em cenário: "usar Claude Code pra automatizar uma tarefa de produção porque a equipe já tem familiaridade com CLAUDE.md". Familiaridade não é requisito técnico — Claude Code não foi desenhado pra ser embutido num serviço voltado a clientes externos.
Combinar superfícies é frequentemente a resposta certa
Nem todo cenário tem uma resposta de superfície única. Um pipeline de CI pode rodar Claude Code de forma não interativa para revisão de código, enquanto o serviço de produção que ele revisa usa Agent SDK com MCP servers próprios para consultar o histórico de incidentes. As duas coexistem porque resolvem trabalhos diferentes — o erro é tratar isso como indecisão, quando na verdade é a arquitetura madura.
Coloque em prática
O laboratório desta lição implementa um classificador de requisitos: dado um conjunto de sinais sobre uma tarefa (precisa de estado? precisa de ferramentas reutilizáveis? é sobre desenvolvimento de software?), ele recomenda a superfície certa e explica por quê — a mesma lógica que você vai aplicar em segundos durante um cenário de prova.