De OpenAPI a MCP: Como Eu Construí um Auto-Conversor em 150 Linhas de Código e O Que Quebrou

Honestamente, eu não pensei que isso funcionaria tão bem.

Depois de construir mais de 10 servidores MCP para vários projetos, eu me cansei de escrever o mesmo boilerplate repetidamente. Você sabe como é: defina suas ferramentas em JSON, escreva as funções de manipulador, mapeie parâmetros, valide entradas... Não é difícil, é apenas chato.

Mas aqui está a questão: a maioria das APIs existentes já possui uma especificação OpenAPI. Por que não podemos simplesmente gerar automaticamente um servidor MCP a partir disso?

Foi exatamente isso que eu tentei fazer. E depois de lutar com o JSON Schema, diferentes versões de especificações e o protocolo MCP por alguns dias, consegui fazê-lo funcionar em cerca de 150 linhas de código Java. Hoje eu quero compartilhar o que aprendi, o que quebrou e se você deve tentar isso por conta própria.

A Ideia: Pare de Escrever Boilerplate

Deixe-me definir o contexto. Eu venho construindo um projeto de base de conhecimento chamado Papers onde armazeno todas as minhas notas pessoais e conhecimento técnico. Eu já o converti em um servidor MCP para que qualquer cliente de IA possa acessar minhas notas diretamente. Essa parte funcionou muito bem — o MCP realmente mudou a forma como eu penso sobre integração de IA.

Mas recentemente eu queria adicionar outra API que já possui uma especificação OpenAPI perfeitamente boa. Eu realmente queria passar outra tarde mapeando manualmente cada endpoint para ferramentas MCP?

Não. Eu não queria.

A promessa do MCP é que, uma vez que você tenha um servidor MCP, qualquer cliente de IA pode usá-lo. O problema é que chegar a esse servidor MCP ainda requer trabalho manual para cada API. E se pudéssemos eliminar isso?

Especificação OpenAPI → Servidor MCP Auto-Gerado → Qualquer Cliente de IA MCP

Esse é o sonho. Deixe-me mostrar o quão perto chegamos.

A Implementação: 150 Linhas Que Realmente Funcionam

Aqui está a abordagem que eu adotei:

1. Parse a especificação OpenAPI 3.0
2. Converter cada endpoint em uma definição de ferramenta MCP
3. Gerar JSON Schema para parâmetros a partir do esquema OpenAPI
4. Roteamento de chamadas de ferramentas MCP recebidas para a API real
5. Retornar a resposta formatada para MCP

Parece simples, certo? Vamos olhar o código real.

Passo 1: O Controlador Principal

Primeiro, aqui está o controlador base que lida com os endpoints MCP:

@RestController
@RequestMapping("/mcp")
public class OpenApiMcpController {
    private final OpenApiParser parser;
    private final OpenApiMcpConverter converter;
    private final ApiInvoker invoker;

    public OpenApiMcpController(OpenApiParser parser, 
                               OpenApiMcpConverter converter,
                               ApiInvoker invoker) {
        this.parser = parser;
        this.converter = converter;
        this.invoker = invoker;
    }

    @PostMapping("/tools/list")
    public McpResponse listTools() throws IOException {
        OpenApiSpec spec = parser.parse();
        List<Tool> tools = converter.convertToTools(spec);
        return McpResponse.tools(tools);
    }

    @PostMapping("/tools/call")
    public McpResponse callTool(@RequestBody McpCallRequest request) 
        throws IOException {
        return invoker.invoke(request);
    }
}

Bastante limpo até agora. O tools/list endpoint apenas analisa a especificação OpenAPI, converte-a em ferramentas MCP e as retorna. O tools/call endpoint delega a um invocador que realmente chama a API.

Passo 2: Convertendo Endpoints em Ferramentas

É aqui que a mágica acontece. Como você converte um endpoint OpenAPI em uma ferramenta MCP?

public List<Tool> convertToTools(OpenApiSpec spec) {
    List<Tool> tools = new ArrayList<>();

    for (PathItem path : spec.getPaths().values()) {
        for (Operation operation : path.getOperations()) {
            Tool