Como expor sua API REST para um agente de código sem criar servidor MCP

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do Dev Eficiente. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Servidores MCP se tornaram a maneira padronizada de expor APIs e funcionalidades para agentes de código como Claude Code, Cursor, Codex e outros. Mas existe uma discussão relevante no mercado sobre a complexidade que eles trazem. No fundo, em muitos casos, você está criando um wrapper da sua API que já existe para expor ela para o agente. E se existisse uma alternativa mais leve, que não exigisse criar um servidor novo em cima de algo que já funciona?

Neste post, mostro como usei a funcionalidade de Agent Skills do Claude Code para expor uma API REST existente para o agente, sem alterar nenhum código da API e sem construir um servidor MCP.

O contexto: MCP, complexidade e alternativas

Na Dev + Eficiente temos essa discussão internamente. Daniel Romero tem uma visão crítica de que o MCP nasceu inchado, trazendo complexidade desnecessária em cenários onde você já tem uma API funcionando. Do outro lado, existe o argumento de que o MCP é a maneira padrão de expor coisas para agentes, o que facilita a integração do ponto de vista de quem consome.

Existem alternativas mais leves surgindo, como o UTCP (Universal Tool Calling Protocol). Mas o caminho que explorei aqui foi diferente: usar a funcionalidade de Skills do Claude Code como ponte entre o agente e a API REST existente.

O que são Agent Skills

Agent Skills é uma funcionalidade do Claude Code que permite carregar instruções e scripts localmente. A própria Anthropic posiciona as Skills como algo mais local, que direciona o agente e pode inclusive orientar o consumo de serviços expostos via MCP ou qualquer outra fonte.

A estrutura é simples. Dentro da pasta .claude/skills/, você cria uma pasta com a sua skill contendo:

• Um arquivo skill.md com nome, descrição e documentação dos endpoints
• Scripts que o agente pode executar para consumir a API

Se você já criou uma tool para integrar com um agente, vai reconhecer a semelhança: a skill tem um nome e uma descrição que o LLM carrega no contexto. Quando você faz um pedido, o agente verifica se existe uma skill que pode ajudar a resolver e, se houver, carrega e executa.

O experimento: Contrate um Dev Eficiente

Para testar essa abordagem, usei a plataforma Contrate um Dev Eficiente, que conecta o mercado com as pessoas que estudam conosco. O objetivo era expor o módulo de analytics da plataforma para o Claude Code sem mexer em nada no código existente.

Estrutura do arquivo de skill

O arquivo skill.md segue um formato sugerido pela Anthropic:

Nome: analytics-contrate-dev-eficiente
Descrição: Fornece acesso aos endpoints de analytics...

Autenticação:
- Token deve ser configurado
- Header de autenticação: Bearer {token}

Endpoints disponíveis:
- /api/analytics - Análise geral (parâmetros: período)
- /api/analytics/empresas - Contatos de empresas
- /api/analytics/candidatos - Candidatos com currículo
- /api/analytics/ranking - Rankings de vagas e empresas

Além da documentação dos endpoints, o arquivo referencia um bash script que o agente pode executar para consumir a API.

O bash script

O script foi gerado pelo próprio Claude Code. Subi o agente no projeto do Contrate um Dev Eficiente, passei o link da documentação de Agent Skills da Anthropic, pedi para ele ler os endpoints do módulo de analytics e gerar tanto o arquivo de skill quanto o script de consumo autenticado.

#!/bin/bash
# Verifica token, faz a requisição autenticada e retorna o resultado

O LLM carrega a skill, vê que existe um script referenciado, executa o script passando os parâmetros necessários (que estão documentados no arquivo de skill), recebe a resposta da API e trabalha em cima disso.

Na prática: como funcionou

Consultas simples

Ao pedir "quero listar as empresas cadastradas", o Claude Code identificou a skill de analytics, carregou, verificou o token de autenticação e executou a consulta. Quando passei um token expirado por engano, ele recebeu 403, tentou outro endpoint, recebeu 403 novamente e me pediu um novo token. Com o token correto, retornou os dados reais da plataforma.

Análise composta

Ao pedir "quero uma análise geral", o agente decidiu por conta própria passar o parâmetro de período como seis meses. Consultou o endpoint, recebeu os dados e construiu uma análise com funil de conversão: empresas cadastradas, empresas com vagas, vagas com candidaturas, taxas de conversão e insights sobre a atividade da plataforma.

Cruzamento entre endpoints

Essa foi a parte mais interessante. Ao pedir "quero saber os nomes de pessoas que têm currículo e o perfil tech delas", o agente precisou combinar informações de endpoints diferentes. Primeiro consultou o endpoint que retorna currículos com perfil tech, depois identificou que não tinha os nomes, foi buscar no endpoint de candidatos com currículo e cruzou os dados.

A conexão com o nível 3 de maturidade REST

Esse comportamento lembrou o modelo de maturidade REST de Richardson. No nível 3, o conceito de HATEOAS (Hypermedia as the Engine of Application State) propõe que o protocolo seja autodocumentado, com links que guiam o cliente sobre o que fazer em seguida.

Na prática, poucos clientes HTTP implementam isso de verdade. Os clientes que construímos nas empresas são determinísticos: fazem chamadas pré-definidas, não seguem links dinamicamente. O navegador é o que mais se aproxima desse nível, por respeitar a semântica dos status codes e executar código que o servidor envia.

Mas quando um LLM consome uma API documentada via skill, algo parecido acontece. Ele consulta um endpoint, percebe que a informação que precisa não está ali, identifica outro endpoint que pode complementar e faz a segunda chamada. Não é exatamente HATEOAS, mas é uma forma de navegação dinâmica entre endpoints que até então era muito difícil de implementar em clientes tradicionais.

Uma pesquisa que fiz usando Deep Research do Claude encontrou um texto da Nord KPIs citando um arquiteto da Microsoft que argumenta que HATEOAS "chegou muito antes do que era possível, mas talvez agora seja mais possível". Concordo com essa visão.

Vantagens dessa abordagem

• Nenhuma alteração no código existente: a API continua funcionando como antes
• Sem servidor novo para manter: não é mais uma coisa para cuidar
• Localidade: a skill é local, você expõe só o que quer, da partezinha que precisa
• Flexibilidade: você pode editar o arquivo de skill para o seu contexto, limitar endpoints, adicionar instruções específicas
• Replicável para qualquer API REST: qualquer endpoint HTTP autenticado pode ser exposto dessa maneira

Aplicações possíveis

A mesma lógica se aplica a outros cenários. Se você tem um serviço de logs, métricas ou observabilidade com API HTTP, pode gerar um arquivo de skill e acessar tudo via terminal com um agente no momento de troubleshooting. Se quer consumir a API pública do GitHub sem instalar o servidor MCP do GitHub, pode criar uma skill que documente os endpoints que você precisa e um script de acesso autenticado.

O repositório público de skills do Claude Code no GitHub já tem exemplos homologados pela Anthropic, como manipulação de PDF com scripts em Python, branding e outros. Servem como referência para construir as suas.

Conclusão

Agent Skills do Claude Code oferecem uma alternativa pragmática para expor APIs REST para agentes de código. Não é uma substituição do MCP -- são coisas diferentes, para contextos diferentes. O MCP continua sendo o padrão para integração ampla e distribuída. Mas quando o que você precisa é algo local, leve, sem adicionar mais uma camada de infraestrutura sobre algo que já funciona, as Skills resolvem bem.

O ponto central é: se você tem uma API REST funcionando, não precisa necessariamente criar um servidor MCP por cima dela. Um arquivo Markdown descrevendo os endpoints e um script de acesso podem ser suficientes para que o agente faça o trabalho.

Dev + Eficiente

Desenvolva software de alta qualidade e domine Engenharia de IA com o Dev + Eficiente. Cursos práticos, acesso vitalício, comunidade ativa e acesso a vagas remotas exclusivas em diversas empresas de tecnologia. Sua jornada para se tornar um dev mais eficiente pode começar agora.