4 lições aprendidas ao desenvolver com as ferramentas MCP e as APIs da Vonage

O Protocolo de Contexto de Modelo (MCP) evoluiu rapidamente. Lembro-me de quando ouvi falar dele pela primeira vez em março passado, no FOSSASIA 2025. É difícil acreditar que faz menos de um ano, mas já parece que ele se tornou onipresente na programação.

Embora eu já tivesse ouvido falar disso há algum tempo, só nos últimos meses é que realmente me aprofundei no assunto. Tenho experimentado a documentação da Vonage e servidores MCP da Tooling; primeiro localmente, depois por meio de posts em blogs, demonstrações e, por fim, ajudando no servidor de ferramentas de código aberto. Este não é um resumo dos recursos do MCP nem um guia de introdução: é um conjunto de lições que surgiram ao tentar tornar as ferramentas utilizáveis na prática.

Lição 1: Um erro inicial: os agentes recorrem automaticamente à geração de código

O primeiro fracasso de verdade não foi um bug técnico. Foi um modelo mental falho.

Conectei meu IDE ao servidor MCP, confirmei que as ferramentas estavam registradas e pedi ao agente para enviar uma mensagem pelo WhatsApp. Em vez de chamar a ferramenta existente, o agente abriu um novo arquivo e começou a escrever um script em Node.js. Ele tentou importar o SDK da Vonage, configurar a autenticação e fazer a chamada à API diretamente.

Não havia nada de “errado” com o modelo. Ele estava fazendo exatamente o que havia sido treinado para fazer: resolver problemas escrevendo código.

A questão era como eu havia concebido o sistema. O agente estava atuando como um gerador de código mais inteligente, em vez de como uma camada de orquestração. As ferramentas já existiam. O agente não precisava criar nada: precisava selecionar e invocar o que já estava disponível.

Depois que ajustei a forma como dava instruções ao agente, tudo se encaixou. Em vez de pedir que ele criasse funcionalidades, pedi que ele as utilizasse.

Essa mudança pode parecer pequena, mas, na verdade, representa uma grande mudança de mentalidade.

Conclusão: O MCP funciona melhor quando você para de pensar em termos de scripts e passa a pensar em termos de ferramentas. Se o agente está escrevendo código de ligação, isso geralmente significa que algo a montante não está estruturado corretamente.

Lição 2: A configuração foi um verdadeiro devorador de tempo

Depois que o modelo mental foi corrigido, eu esperava que o resto do trabalho fosse simples. Mas não foi.

A parte mais demorada do desenvolvimento local foi fazer com que o IDE se conectasse de forma confiável ao servidor MCP. A maioria das falhas se apresentava como “a ferramenta não está aparecendo”, o que levava facilmente a supor que o servidor estivesse com defeito. Quase sempre, o problema era de configuração.

Diferentes IDEs esperam que a configuração do MCP esteja em locais diferentes. Por exemplo, o Windsurf se parece com o VS Code, mas não é o VS Code, e o caminho da configuração não está onde a memória muscular sugere que deveria estar. Passei mais tempo do que gostaria de admitir procurando por bugs inexistentes, porque o servidor nem sequer havia sido iniciado.

As configurações do MCP também não funcionam como scripts de shell. O cliente inicia um processo diretamente. Não é possível contar com sh -c, cdou comandos encadeados. Se você não usar caminhos absolutos e comandos explícitos, as falhas tendem a ocorrer sem aviso prévio.

Depois que tudo foi configurado corretamente, a experiência transcorreu sem percalços, da melhor maneira possível. Basta reiniciar o IDE, atualizar o painel de plug-ins e as ferramentas aparecem.

Conclusão: O MCP segue um padrão de programação conhecido: é na configuração que surgem a maioria dos problemas. Quando algo não funciona, geralmente é uma questão de configuração. Depois que a configuração estiver pronta, o MCP permite que você voe!

Lição 3: O Stdio funciona bem localmente, mas não tão bem em outros lugares

O transporte stdio padrão do MCP é uma boa opção para o desenvolvimento local. É simples, rápido e evita a exposição de portas ou credenciais. Para fluxos de trabalho baseados em IDE, ele faz exatamente o que você deseja. E é exatamente por isso que o utilizamos para nosso Tooling Server. Queríamos colocá-lo à disposição dos desenvolvedores de forma rápida e flexível.

No entanto, surgem algumas limitações quando se tenta usar as mesmas ferramentas fora de um IDE, como ao integrar um sistema externo. Não é possível fazer uma solicitação HTTP para o stdin. Não há nenhum endpoint para proteger, nem um local óbvio para implementar a autenticação.

Para preencher essa lacuna, acabei criando uma pequena camada de tradução que convertia JSON-RPC via stdio em HTTP, para que outros sistemas pudessem interagir com o servidor MCP. Funcionou, mas era uma infraestrutura adicional que não existia na configuração exclusivamente local.

Os testes também se tornaram mais complicados. A afirmação “funciona localmente” não tem muito sentido se o agente estiver acessando a ferramenta de outro lugar. Atualmente, não há uma solução intermediária adequada para validar as ferramentas MCP isoladamente, sem precisar iniciar uma sessão completa do agente.

Conclusão: O MCP simplifica os fluxos de trabalho em IDEs, e foi por isso que começamos por ele. Para desenvolvedores que se sentem à vontade para gerenciar sua própria hospedagem e autenticação, essa troca é razoável. Quando você vai além do uso local, o stdio traz desafios como autenticação, camadas de tradução e testes. Esses desafios têm menos a ver com o MCP em si e mais com a localização desse servidor. Fique de olho, pois nossas ofertas do MCP estão se expandindo.

Lição Quatro: Planejamento para o crescimento: projeto de ferramentas e orçamento contextual

Essa lição não surgiu porque algo deu errado. Ela surgiu ao analisar o servidor de ferramentas e perguntar: “O que vai acontecer quando mais pessoas começarem a contribuir?”

Ao escrever sobre uso das ferramentas do MCP da Vonage e incentivar contribuições de código aberto, ficou claro que a estrutura do repositório não havia sido projetada para crescer. Tudo estava em um único arquivo. Isso é viável no início, mas não se adapta bem ao crescimento. Nem para pessoas, nem para agentes.

Ao analisar como outros servidores MCP lidam com o crescimento, surgiu uma restrição ainda mais importante: cada ferramenta que você disponibiliza consome parte da janela de contexto do modelo.

Os esquemas das ferramentas não são gratuitos. Nomes, parâmetros e descrições são todos inseridos no prompt do sistema. À medida que o número de ferramentas aumenta, você reduz gradualmente o espaço que o modelo tem para analisar a solicitação real do usuário.

Existe uma tendência natural de criar ferramentas flexíveis e multifuncionais: uma única send_message que lide com todos os canais e comportamentos. Do ponto de vista da API, isso é organizado. Do ponto de vista do modelo, é ambíguo e oneroso.

Ferramentas menores e com finalidade única tendem a funcionar melhor. Elas são mais fáceis de serem selecionadas pelo modelo, mais baratas de serem descritas e mais simples de serem analisadas. Internamente, as implementações ainda podem ser compartilhadas. O que mais importa é o que o agente vê.

O servidor de ferramentas de código aberto atual ainda não implementa o carregamento sensível ao contexto, e isso é intencional. Mas essas restrições já estão moldando a forma como pensamos em um servidor MCP mais voltado para o mercado; um servidor que qualquer pessoa possa usar, não apenas desenvolvedores.

Conclusão: Com o MCP, o desempenho não se resume apenas à velocidade de execução. Tem a ver também com a quantidade de contexto que você consome.

Considerações finais

Trabalhar com a MCP mudou a maneira como encaro o trabalho do dia a dia. Processos que eu costumava aceitar como manuais ou repetitivos agora se tornam ferramentas em potencial. Quando essa mudança ocorre, você começa a enxergar oportunidades em todos os lugares; não para automatizar apenas por automatizar, mas para eliminar os atritos que atrasam o trabalho de verdade.

O MCP ainda é recente, e muitas das imperfeições são compreensíveis. Mas uma coisa ficou clara muito rapidamente: o sucesso de um sistema baseado em MCP não depende apenas do modelo escolhido, mas também do grau de cuidado com que as ferramentas são projetadas. Limites claros, responsabilidades bem definidas e comportamento previsível são mais importantes do que abstrações engenhosas. Quando esses elementos estão em ordem, fica mais fácil confiar no sistema e ampliá-lo.

O que acho mais interessante é como o MCP nos leva a pensar no software como algo que deve ser usado por agentes, e não apenas por humanos. Isso muda a maneira como você escreve APIs, como estrutura a documentação e como avalia se algo está “pronto”. É um conjunto diferente de compromissos, que ainda está tomando forma.

Nas próximas semanas, vou experimentar outras ferramentas do MCP, como Laravel Boost e MCP UI para ver como outras pessoas estão lidando com esses problemas. Se você está trabalhando com o MCP, ou apenas pensando em começar, adoraria saber o que você está desenvolvendo e o que aprendeu ao longo do caminho. Envie-me uma mensagem no LinkedIn ou pelo Slack dos desenvolvedores da Vonage.