Se o seu agente tem um shell, dê a ele uma linha de comando

O Model Context Protocol é, nas próprias palavras, “an open-source standard for connecting AI applications to external systems”, um padrão aberto para conectar aplicações de IA a sistemas externos (modelcontextprotocol.io). O projeto o compara a uma porta USB-C: um conector para muitos dispositivos.

A especificação atual, versão 2026-07-28, define hosts (a aplicação de IA), clients (os conectores dentro dela) e servers (os serviços que fornecem dados e ferramentas), que conversam via JSON-RPC. Um servidor pode oferecer resources, prompts e tools. As tools são o que os agentes mais usam: o client pede ao servidor a lista com tools/list, e cada tool vem com nome, descrição e um JSON Schema para a entrada.

Uma linha de comando não é automaticamente boa para agentes. Ela precisa de algumas propriedades que humanos raramente pedem:

• Ela se descreve como dados: --help e um catálogo completo de comandos em JSON, para que o agente nunca precise adivinhar flags.
• A saída é um contrato: com --json, exatamente um documento JSON no stdout, erros como JSON no stderr.
• Os códigos de saída têm significado: corrigir a chamada, perguntar ao humano, esperar, tentar de novo. Um número diz ao agente o que fazer em seguida.
• Ela nunca espera uma entrada que o agente não pode dar: sem terminal, nada pede confirmação interativa. Passos destrutivos exigem uma flag explícita como --yes.
• Ela pode mostrar em vez de agir: --dry-run imprime a requisição exata sem enviá-la.
• Segredos ficam fora da saída, também com --verbose e --dry-run, porque tudo o que o agente vê vai parar no contexto dele.
• É fácil de instalar onde quer que um agente rode, de preferência sem árvore de dependências.

A equipe de engenharia da Anthropic descreveu o problema em novembro de 2025: “Most MCP clients load all tool definitions upfront directly into context”, ou seja, a maioria dos clients MCP carrega todas as definições de tools no contexto logo de início, e essas descrições aumentam o tempo de resposta e o custo (Code execution with MCP). A recomendação deles é deixar o modelo ler as definições de tools sob demanda.

Para ser justo, os clients estão evoluindo. O Claude Code agora adia as tools MCP por padrão: no início da sessão carregam só os nomes das tools e as instruções do servidor, e a definição completa vem quando o Claude busca a tool (MCP tool search). Outros clients ainda podem carregar tudo.

Uma CLI tem carregamento sob demanda de graça, porque nada está no contexto até o agente executar um comando. Medimos quanto há para carregar no tm 0.3.0: o catálogo completo (tm schema --json) tem 377.203 caracteres, a visão geral de todos os grupos de comandos (tm --json) 32.110, o grupo de faturas 104.009. Um único comando tem mediana de 934 caracteres entre 157 comandos. Método: npx -y @time-momentum/cli@0.3.0 schema --json | wc -c e o mesmo para as outras chamadas, em 10 de out. de 2026.

O catálogo não é pequeno. É justamente esse o ponto: o agente decide o que carregar, geralmente um grupo ou um comando.

Com MCP, “every intermediate result must pass through the model”, todo resultado intermediário precisa passar pelo modelo, como diz o mesmo artigo da Anthropic. Uma lista de 500 faturas que o agente só precisa contar ainda vai parar no contexto dele.

Em um shell, o agente filtra antes de ler. tm payments outstanding --json | jq '[.data[].summary.outstanding_micros] | add / 1000000' retorna um único número: o total em aberto em euros. tm invoices list --all --json | jq '[.data[] | select(.status == "draft")] | length' conta os rascunhos em todas as páginas. As mesmas linhas funcionam em um cron job ou em um shell script, sem nenhum agente.

No MCP, a autorização é opcional. Servidores remotos via HTTP devem seguir o fluxo OAuth 2.1 da especificação; servidores locais via stdio pegam as credenciais do ambiente. Para um app de chat em que cada usuário entra com a própria conta, OAuth é a opção mais cômoda.

Uma CLI costuma funcionar com uma chave de API. É simples, mas exige cuidado: a chave nunca pode aparecer no que o agente lê. O tm a guarda em um arquivo local com modo 600 ou em uma variável de ambiente, troca uma chave de escrita por um token válido por uma hora e nunca imprime a chave, nem com --verbose ou --dry-run. Um token dessa troca não pode criar novas chaves nem excluir a conta.

Cada chamada que um agente faz por uma CLI é uma linha que você pode copiar, ler e executar. --dry-run vai um passo além e mostra método, URL e corpo sem enviar nada. Isso torna o trabalho do agente revisável antes de acontecer, o que importa sobretudo para faturas.

O MCP também tem ferramentas para isso, como o MCP Inspector para desenvolvedores. Mas uma chamada de tool não é algo que você digita no seu próprio terminal para ver o que acontece.

Uma CLI é um pacote com versão. Você pode fixá-la (npx -y @time-momentum/cli@0.3.0), voltar atrás (tm update --to <version>) e saber que um script que funcionou ontem funciona hoje. Quando a API muda de um jeito que uma versão antiga entenderia errado, o servidor rejeita essa versão com um erro claro e o comando de atualização.

O MCP versiona o protocolo por data e permite que os servidores anunciem mudanças na lista de tools em tempo de execução. Um servidor remoto decide sozinho quais tools você recebe hoje. É conveniente enquanto nada quebra.

Claude Code, Codex, Cursor e a maioria dos agentes de código conseguem executar comandos de shell. Uma CLI funciona em todos eles sem que o client precise suportar mais nada, também em sandboxes e em CI.

• Clients sem shell. claude.ai, Claude Desktop e os apps móveis do Claude acessam ferramentas externas por connectors, que são servidores MCP (documentação do Claude). Uma CLI não ajuda aí.
• Descoberta padronizada. Todo servidor MCP responde a tools/list do mesmo jeito, e o MCP Registry oficial lista servidores. Cada CLI se documenta do seu jeito.
• Login por usuário. Com OAuth, cada pessoa conecta a própria conta sem lidar com uma chave.
• Usuários não técnicos. Adicionar um connector em um app de chat é mais fácil do que instalar uma linha de comando.

Os agentes dos nossos usuários já trabalham em um shell, em projetos de clientes. Por isso o Time Momentum não tem servidor MCP. Ele tem o tm, uma linha de comando que opera o produto inteiro: esforço, clientes, pedidos, projetos, faturas e faturas eletrônicas, pagamentos, relatórios de horas e rentabilidade.

O tm não tem dependências de runtime. Cada operação da API REST pensada para a linha de comando tem exatamente um comando, 143 operações na versão 0.3.0, e um teste garante isso a cada mudança na API. tm skill retorna o guia de uso correspondente à versão instalada. No Claude Code, tm skill --install adiciona uma skill curta que aponta para ele, e o Time Momentum também está disponível como plugin do Claude Code.

Emitir ou cancelar uma fatura e excluir exigem um --yes explícito. Sem terminal, o tm para caso contrário.