Aprendizados na Construção de um Servidor MCP

Eu construí um servidor MCP para nuzur, um projeto no qual estou trabalhando. Ele se encaixa naturalmente no meu fluxo de trabalho e me ajuda a automatizar fluxos desde o design do esquema até as mudanças de dados. Neste post, quero compartilhar o que aprendi durante o processo.

O que é MCP (contexto rápido)

MCP (Model Context Protocol) é um padrão aberto, criado pela Anthropic em 2024, para conectar modelos de IA a ferramentas externas e fontes de dados. Pense nisso como um adaptador universal para integração com qualquer assistente ou agente de IA.

Os aprendizados

Ferramentas granulares

Comecei construindo ferramentas de operação CRUD no servidor MCP. Elas funcionam, mas são caras (especialmente se seus payloads forem grandes), e pode levar vários minutos para o agente completar uma tarefa. Aqui está um exemplo mais específico:

nuzur gerencia projetos, e cada projeto pode ter n versões de projeto. Cada versão de projeto contém entidades (com seus campos), relacionamentos e enums.

Eu pedi ao agente para fazer algumas mudanças em um projeto: criar uma nova versão de projeto, adicionar uma entidade e modificar outra. Meu design inicial deu ao agente uma ferramenta para obter a versão mais recente do projeto e uma ferramenta para criar ou atualizar uma. Funcionou, mas consumiu todos os meus tokens e levou cerca de 15 minutos para completar.

O problema é que os modelos geralmente têm dificuldade com payloads grandes, e fazer mudanças específicas em estruturas profundamente aninhadas é caro.

A solução é criar ferramentas granulares para que o agente nunca precise ler e analisar o payload completo. O servidor mantém o controle da estrutura geral, e o agente recebe apenas as partes que precisa.

Como isso se traduz no exemplo acima? Eu construí ferramentas granulares para gerenciar entidades, campos, relacionamentos e enums, e também adicionei uma ferramenta que retorna uma versão enxuta da versão do projeto para dar ao agente o contexto geral quando necessário. Isso reduziu o tempo de execução de 15 minutos para menos de um minuto para as mesmas mudanças, e o uso de tokens também diminuiu drasticamente.

A lição: mantenha as ferramentas granulares, mantenha os payloads enxutos e limite-os apenas aos dados necessários. Outro truque útil é pedir ao agente que usou seu servidor MCP feedback sobre as ferramentas — o que demorou e o que poderia ser melhorado para tornar as coisas mais suaves.

Incorpore suas habilidades e forneça recursos

Este é um ponto pequeno, mas útil: você pode incorporar suas habilidades no servidor MCP como prompts. Dessa forma, elas permanecem atualizadas com seu código, e os usuários obtêm a versão mais recente sem precisar baixar ou atualizar manualmente as habilidades em seu cliente.

Na mesma linha, você pode fornecer recursos do servidor MCP para complementar as descrições de suas ferramentas. Isso melhora a experiência do usuário, agiliza fluxos de trabalho e reduz retrabalho — e, assim como os prompts, os recursos podem ser atualizados dinamicamente sem tocar no cliente.

O que eu faria diferente

Se eu estivesse começando de novo, não construiria as ferramentas CRUD de forma alguma. É tentador espelhar sua API existente, mas os agentes não consomem APIs da mesma forma que os programas — eles pagam por cada token que leem. Projetar para o agente desde o primeiro dia significa começar granular, manter as respostas enxutas e tratar o contexto como um orçamento.

Eu também faria o feedback do agente parte do ciclo de desenvolvimento mais cedo. Algumas das minhas melhores melhorias nas ferramentas vieram simplesmente de perguntar ao agente o que o desacelerou após uma sessão — é o teste de usabilidade mais barato que você já fará.

Um servidor MCP não é apenas uma camada em torno do seu produto; é uma interface projetada para um tipo de usuário muito diferente. Assim que comecei a pensar dessa forma, cada decisão de design ficou mais fácil.

Se você quiser ver essas ideias em prática, o servidor MCP da nuzur está ao vivo — experimente e me diga o que você acha.