Pergunta 17 · 🧩 Sistemas de IA sob medida
Como manter um servidor MCP e uma CLI atualizados quando a API muda?
Quando um sistema oferece API, servidor MCP e CLI, uma mudança na API pode quebrar as outras duas sem ninguém perceber. Quem sente primeiro é o usuário.
Primeiro, os nomes: a API é a porta que o seu sistema oferece para outros programas conversarem com ele. O servidor MCP (o conector usado pelos assistentes de IA) e a CLI (a versão de linha de comando, usada no terminal) são dois jeitos de usar essa mesma porta.
Escreva no AGENTS.md (o arquivo de instruções que os agentes de programação leem ao abrir o projeto) uma regra simples: quando a API mudar, confira o servidor MCP e a CLI e aplique as mudanças necessárias.
A API é a base de que essas interfaces dependem. Mudar a base e esquecer o que foi construído em cima vira problema de organização e manutenção.
Cada lançamento só termina quando as interfaces ligadas a ele também receberam a mudança.
Por que tudo fica desalinhado
Cada interface costuma ser escrita em um momento diferente, às vezes por pessoas diferentes. A API ganha um campo novo, muda um nome ou passa a exigir um parâmetro. O servidor MCP e a CLI continuam com a versão antiga.
O resultado é um assistente de IA chamando uma função que já não existe, ou um comando de terminal que devolve erro sem explicação. Não é falta de técnica, é falta de um passo no processo.
Uma única fonte da verdade
Ajuda muito descrever a API em um arquivo formal, como uma especificação OpenAPI (um documento padrão que lista cada rota, campo e resposta). Com ele, parte do código do MCP e da CLI pode ser gerada ou conferida de forma automática.
Mesmo sem gerar código, esse arquivo vira a referência que o agente de programação consulta para saber o que mudou.
Instrução clara para o agente
No AGENTS.md, a regra funciona melhor quando é específica. Em vez de pedir para manter tudo atualizado, diga quais pastas conferir, quais testes rodar e o que registrar no histórico de mudanças.
Assim, quando você pedir ao agente para alterar a API, ele já sabe que a tarefa inclui as outras interfaces, e não para no meio do caminho.
Teste que trava o lançamento
A proteção mais forte é um teste automático que chama a API pelo MCP e pela CLI e confere se a resposta bate. Se não bater, o lançamento não sai.
Assim a regra deixa de depender de memória e passa a ser uma barreira do próprio processo.
- Descreva a API em um arquivo de especificação, como OpenAPI, e mantenha-o junto do código.
- Escreva no AGENTS.md a lista de pastas do MCP e da CLI que devem ser conferidas a cada mudança.
- Crie um teste curto que chama as principais funções pelas três interfaces.
- Coloque esse teste como obrigatório antes de publicar uma versão.
- Registre no histórico de mudanças o que mudou na API e nas interfaces.
- Avise os usuários quando uma mudança exigir que atualizem o MCP ou a CLI.
- Deixar a regra vaga no AGENTS.md: o agente interpreta do jeito mais curto e pula partes.
- Testar só a API: o problema costuma aparecer nas camadas de cima.
- Remover um campo sem aviso: quem usa versão antiga quebra sem entender por quê.
- Regra no AGENTS.md.
- API é a base; MCP e CLI ficam em cima.
- Lançamento só fecha com tudo atualizado.