Eu só queria expor uma API como MCP. Em 5 dias, ela virou um chat de IA que gera PDF, Excel e gráficos
DEV Community

Eu só queria expor uma API como MCP. Em 5 dias, ela virou um chat de IA que gera PDF, Excel e gráficos

Quase ninguém comenta isso quando fala de MCP (Model Context Protocol): montar o servidor é a parte tranquila. O que dá trabalho, e também o que mais me interessou, vem depois que ele já está de pé.

Passei as últimas semanas nisso, mexendo na API da DKSOFT, um sistema de gestão escolar, num projeto que saiu de um pedido da minha esposa (explico logo abaixo). A ideia era só "deixar a API acessível para IA".

Acabou virando algo que não constava em roadmap nenhum: um chat onde o gestor da escola escreve, em português, quanto entrou de mensalidade na semana e recebe a resposta com um gráfico e um Excel pronto para baixar.

Vou contar o caminho: o que funcionou, onde errei e o que a empresa percebeu ao longo do processo.

Antes de começar: dois avisos

  1. Isso foi um pedido da minha esposa, e ninguém me pagou por ele. Ela quis saber se a API da DKSOFT conseguiria conversar com uma IA, e eu disse que sim, que ia tentar. É um projeto de família, tocado nas horas vagas, sem cliente e sem prazo de contrato.
  2. Montei tudo pensando em aprender. Escolhi as ferramentas e o jeito de trabalhar (MCP, LangGraph, Spec Kit, exportação de arquivos em worker threads) porque queria aprender na prática, e não porque alguém estivesse esperando uma entrega. Também não toma o lugar do meu emprego, que continua sendo meu trabalho e minha renda. O que está aqui é estudo aplicado a um problema de verdade.

Digo isso para ninguém entender o texto como "como fechar um projeto de IA em cinco dias". É um relato de aprendizado, com os acertos e os atalhos de um MVP.

Ponto de partida: uma API de integração comum

A API da DKSOFT segue o padrão de boa parte dos sistemas legados bem mantidos: REST, token Bearer, e endpoints para alunos, pacotes, contas recebidas e contas pagas. Ela existe para conectar outras plataformas, portais e ferramentas de análise. Para isso ela funciona bem.

Só que uma API que serve para integração não é uma API que uma pessoa sem perfil técnico consegue usar. Para saber quais parcelas em aberto o aluno 737 tem, alguém precisa descobrir que o endpoint existe, montar a requisição, lidar com a autenticação e interpretar o JSON que volta.

A documentação já dizia que agentes de inteligência artificial podiam usar a API. O que faltava era a ligação entre as duas pontas.

Dia 1: o MCP mais simples que deu

No dia 28 de outubro saiu o primeiro commit de verdade: um servidor MCP em TypeScript, transporte stdio, conversando com a API. Sem truque nenhum.

Já comecei separando em camadas, e indico isso para qualquer MCP que tenha chance de crescer:

  • domain/ : tipos e regras puras
  • application/ : serviços
  • infrastructure/ : clientes HTTP e tratamento de erro
  • mcp/ : apenas o registro de tools, prompts e resources

Ao final, o servidor oferece dez tools, quase uma por endpoint: list_packages , list_students , find_student , list_student_open_installments , list_receivable_accounts , list_paid_bills , entre outras.

Registrei também prompts e resources , com informações sobre cada área da API, já que MCP não se resume a tools. Eles ajudam o modelo a entender o que cada consulta faz, e eu não preciso repetir isso em todo prompt de sistema.

O que mais pesa: o modelo não sabe as regras da sua API

Se eu pudesse voltar e contar uma coisa para mim mesmo no começo, seria esta. A API de contas recebidas e pagas só aceita intervalos de no máximo 30 dias , somando as duas datas das pontas.

Para quem lê a documentação, é uma linha numa tabela. Para um modelo, é uma armadilha: perguntaram "quanto recebemos no trimestre?", e ele vai mandar 90 dias de uma vez e levar um erro 400.

Atacei em duas frentes:

  • No MCP, validei a janela de 30 dias (contando as duas pontas), tipei os erros HTTP e passei a resposta por um schema zod. Se algo fugir do contrato, o erro aparece de forma clara, em vez de o modelo inventar em cima de dado quebrado.
  • No agente, ensinei a fatiar períodos longos em várias consultas e juntar os resultados depois.

A lição: o MCP não serve só para traduzir endpoints. Ele é o lugar das regras de negócio que o modelo tem que respeitar.

Dias 2 a 5: o MCP pediu um agente, e o agente pediu uma tela

Com o MCP rodando no meu editor, a pergunta seguinte veio sozinha: se funciona para mim, por que não funcionaria para quem usa o sistema no dia a dia? O escopo cresceu a partir daí.

Consegui manter o controle porque usei o Spec Kit desde o início: cada pedaço virou uma spec, com plano e lista de tarefas, antes de ganhar código.

  • Spec 001, API do agente: Fastify + LangGraph em cima do OpenRouter, streaming por SSE, histórico de conversa e o MCP rodando como processo filho da API. Tem um modelo reserva para quando o principal falhar, limite de requisições e a mesma atenção com dados pessoais.
  • Spec 002, front do chat: React + Vite, resposta em streaming, histórico que dá para retomar e um tratamento de erro razoável.
  • Spec 003, deploy: Fly.io para o back (API e MCP na mesma imagem) e Vercel para o front.
  • Spec 004, exportação e gráficos: a que mais mexeu com as conversas internas.

Spec 004: o chat passou a entregar, além de responder

Quem mostra um chat de IA sobre dados ouve sempre a mesma frase: "bacana, mas eu preciso disso numa planilha". Então o assistente passou a gerar PDF, Word e Excel a partir da consulta, e a desenhar gráficos de barras, linhas e pizza quando fazem sentido. Dá para pedir no chat ("me manda isso em Excel") ou clicar no botão de exportar.

Alguns detalhes técnicos que acho que valem o registro:

O modelo nunca digita os números. O resultado completo da consulta fica guardado no servidor, e o modelo enxerga só uma versão resumida. Gráficos e arquivos saem dos registros reais, jamais de valores que o modelo escreveu. Isso diminui o custo de contexto e acaba com toda uma categoria de erro.

Dados pessoais saem mascarados por padrão. CPF, e-mail e telefone aparecem mascarados nos arquivos. A versão completa só é gerada se a pessoa pedir isso por escrito, de forma explícita. O botão de exportar nunca gera a versão completa.

Geração em worker threads. PDF e Word pesam, e não podem travar o servidor enquanto ele faz streaming para outros usuários. Eu medi: exportar 1.000 linhas leva em torno de 1 segundo, e o maior atraso no laço de eventos foi de 12 ms, com três streams ativos ao mesmo tempo.

Nenhum dado de aluno vai para disco. Resultados e arquivos ficam só em memória, e expiram. As conversas ficam no SQLite, mas os dados consultados não.

Feature flag. Uma variável de ambiente desliga exportação e gráficos sem precisar de outro deploy.

O que a empresa percebeu

Esta é a parte que eu mais queria escrever. Enquanto o MCP era "só um servidor", parecia um detalhe técnico. Quando virou algo em que a pessoa pergunta, enxerga a resposta e baixa o arquivo, o assunto mudou.

Deixou de ser "temos uma API para integrar" e passou a render perguntas como estas:

  • E se o gestor da escola pudesse consultar tudo isso sem abrir relatório nenhum?
  • E se o suporte tirasse dúvidas de clientes olhando o dado em linguagem natural?
  • E se cada dado que o sistema já guarda virasse uma pergunta possível, em vez de mais uma tela para construir?

A API de integração segue sendo uma API de integração. Só que agora ela também é a base de um produto de conversa , e isso quase sem tocar nela, porque o contrato já estava limpo.

É o que eu levo para outros times: quanto mais bem documentada e previsível a sua API, mais barato fica pôr uma camada de IA por cima.

O que eu mudaria (e o que ainda é MVP)

Sem enfeitar: É um projeto de aprendizado, e não um produto em produção. Foi feito de graça, a pedido da minha esposa, por curiosidade técnica. Não passou pelo rigor de um projeto contratado, e não substitui o meu trabalho regular.

Um token só, sem multi-tenant. No MVP, quem tem a chave enxerga os dados daquele token. Em produção de verdade, é preciso separar por cliente. Deixei isso registrado como limitação conhecida, sem esconder.

Só leitura, de propósito. O agente nunca altera nada na DKSOFT. Foi uma escolha deliberada, para começar com segurança.

Infra de demonstração. Numa conta trial do Fly existem limites reais: a máquina desliga depois de 5 minutos, e isso apaga os resultados guardados em memória. Está descrito no README.

O MCP ainda não está no npm. Pensei em publicar, mas agora não é prioridade.

O que fica

Comece pequeno e em camadas. Um MCP simples e bem organizado aguenta crescer.

Ponha as regras de negócio no MCP. O modelo não vai adivinhar o limite de 30 dias.

Não deixe o modelo digitar números. Guarde o dado real e deixe o modelo só orquestrar.

Escreva a spec antes do código. Com o Spec Kit, em cinco dias saíram três specs completas, com plano e tarefas, mais de cem arquivos de teste e um deploy no ar.

O valor aparece quando alguém não técnico usa. Foi nesse momento que a empresa viu o que o MCP podia ser.

Projeto paralelo ensina bastante. Um pedido simples da minha esposa virou o melhor laboratório do meu ano, sem pressão de entrega e sem encostar no meu trabalho do dia a dia.

O código é público, e as decisões de arquitetura estão no README: https://github.com/Gabriel-Barbosa-de-Oliveira/dksoft-ia-chat

Se você já colocou um MCP em cima de uma API que já existia, o que foi a primeira coisa a mudar na cabeça do time? Conta nos comentários, tenho curiosidade de comparar.

MCP #ModelContextProtocol #IA #TypeScript #LangChain #Node #DesenvolvimentoDeSoftware

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.