🌐 API direta: o jeito tradicional
Chamar a API HTTP do servico direto do agente parece o caminho mais simples. Voce faz curl, o servidor devolve JSON, o agente le. Funciona, mas tem custos escondidos.
📡 Como funciona na pratica
curl -X GET "https://api.exemplo.com/posts?limit=10"Resposta tipica: JSON com dezenas de KB, dezenas de campos, e o agente paga em token cada um deles — mesmo os que nao usa.
✓ Pros
- ✓Padrao universal — existe para quase tudo
- ✓Documentacao madura na maior parte das APIs
- ✓Setup zero — nada para instalar
✗ Contras
- ✗JSON cru polui contexto do agente
- ✗Paginacao precisa ser orquestrada manualmente
- ✗Auth complexa: o agente tem que gerenciar tokens
💡 Quando ainda faz sentido
Use API direta em integracoes de backend tradicional, onde o codigo do app processa o JSON antes de qualquer LLM ver. Para agente em producao, raramente vale a pena.
🔌 MCP: a promessa que nao cumpriu (toda)
O Model Context Protocol (Anthropic, 2024) padronizou como agentes descobrem ferramentas. Voce instala um MCP server e o Claude Code ve todas as tools. Em teoria, perfeito.
📊 O problema medido
- 47.000 tokens - Carga tipica de descricoes MCP por sessao no Claude Code
- 35× - Quanto MCP consome a mais que CLI para a mesma tarefa
- 72% - Reliability em tarefas complexas (CLI mantem 100%)
🔍 Veja voce mesmo
/context # no Claude Code
> MCP servers: 47.000 tokens carregados (sem voce invocar nada)Cada descricao de tool fica sempre no contexto, ainda que voce nao chame nenhuma. E o "imposto de descoberta" do MCP.
⚠️ Onde MCP fica perigoso
Tarefas com varios passos (write file, ler doc, chamar tool, decidir): cada passo carrega o overhead novamente. Em sessoes longas o agente comeca a "esquecer" — porque a janela ja estava cheia desde o inicio.
⚡ CLI: o vencedor para agentes
A CLI faz a request pesada, processa o JSON internamente, guarda em SQLite e so devolve ao agente o essencial. O JSON cru de 100k tokens nunca entra no contexto.
📟 Exemplo: pp-espn
$ espn-pp-cli games --league nba --date today
[NBA] Hoje (3 jogos):
Lakers 112 @ Celtics 109 FINAL
Warriors 98 @ Knicks 104 FINAL
Heat 99 @ Mavericks 110 4Q 2:14
Saida: ~200 tokens. O JSON original da ESPN tinha mais de 100k. O agente consome so o resumo.
✓ Vantagens fortes
- ✓Output enxuto e estavel
- ✓Cache local em SQLite (offline)
- ✓Sem overhead fixo de contexto
- ✓Auth resolvida uma vez, fica salva
- ✓Composavel: pipes,
&&, scripts
⚠️ Contras (gerenciaveis)
- ·Precisa instalar o binario
- ·Curva inicial para o time
- ·Atualizacao manual (resolvido com
regen-merge)
📊 Tabela comparativa
Olhando lado a lado, a diferenca aparece em todas as dimensoes que importam quando o agente esta em producao.
| Criterio | API | MCP | CLI |
|---|---|---|---|
| Tokens (overhead) | Alto | Alto fixo | Baixo |
| Reliability complexa | Variavel | 72% | 100% |
| Funciona offline | Nao | Nao | Sim (cache) |
| Composavel | Medio | Nao | Sim |
| Sem API publica | Nao | Nao | Sim (browser-sniff) |
| Setup | Zero | Medio | Medio |
💰 Caso real: Skool — 132k → 2k tokens
O caso mais citado nos videos oficiais do Printing Press: a API do Skool (plataforma de comunidades) devolvia 132.000 tokens para uma tarefa de listar posts. A CLI reduziu para 2.000 — 98,5% de economia.
CLI faz a chamada pesada
Em background, fora do contexto do agente
A request retorna 132k tokens de JSON cru, contendo posts, comentarios, autores, timestamps, embeds, metadados de moderacao, etc.
Persiste o bruto no SQLite
Para futuras queries locais
O JSON inteiro fica disponivel em disco. Queries como --full, --export, ou busca FTS5 leem do SQLite sem nova chamada.
Devolve so o resumo
Para o contexto do agente
~2k tokens com titulos, autor, data, engagement. Suficiente para o agente decidir o proximo passo.
💡 Implicacao pratica
Em uma sessao com 20 chamadas como essa, voce economiza 2,6 milhoes de tokens. No plano Claude Code Pro, isso e a diferenca entre terminar o trabalho ou bater o limite no meio da tarde.
🎯 Quando escolher cada um
Nem tudo precisa virar CLI. A regra de bolso para nao over-engineerar e simples:
🧭 Regra pratica
- •API direta: backend tradicional (sem LLM no loop), batch jobs noturnos, ETL.
- •MCP: prototipo rapido, tool muito dinamica usada todo dia, time sem appetite de instalar binario.
- •CLI: agente em producao, tarefas repetitivas, sites sem API, cobertura offline.
💡 Heuristica final
Se voce paga por token (Claude Code Pro, Anthropic API, OpenRouter), prefira CLI sempre que houver opcao. O payback acontece na primeira sessao.
✅ Resumo do Modulo
Proximo Modulo:
1.2 — Instalacao completa (Go, binario, skills, starter-pack)