Ferramenta que Converte Qualquer API em Algo que Seu Cliente MCP Pode Usar

Oi pessoal 👋

Eu estive imerso no mundo das ferramentas de IA ultimamente e continuei enfrentando o mesmo problema irritante: conectar LLMs a APIs existentes é muito mais difícil do que deveria ser.

Toda vez que eu queria que um LLM chamasse uma API REST, eu tinha que escrever um servidor MCP personalizado do zero. Definir as ferramentas. Mapear os parâmetros. Lidar com autenticação. Conectar as chamadas HTTP. Repetidamente.

Então eu construí algo para resolver isso.

Conheça o mcp-server-openapi

mcp-server-openapi é um CLI Go de código aberto que converte automaticamente sua especificação OpenAPI em ferramentas MCP. Se sua API tem um documento OpenAPI (e sejamos honestos, a maioria tem), você pode expô-la a qualquer cliente MCP — Claude Desktop, Cursor, VS Code, você nomeia — em cerca de 30 segundos.

Sem boilerplate. Sem conexões manuais. Apenas aponte para sua especificação e vá.

mcp-server-openapi --spec ./your-api.yaml

É isso. Seus endpoints de API agora são ferramentas que qualquer cliente MCP pode chamar.

Espera, o que é MCP?

Se você é novo nisso — Model Context Protocol (MCP) é um padrão aberto que permite que assistentes de IA interajam com ferramentas externas e fontes de dados. Pense nisso como uma porta USB-C para IA: uma conexão padrão que funciona em todo lugar.

Servidores MCP expõem "ferramentas" (basicamente funções) que um cliente MCP pode descobrir e chamar. O problema é que construir esses servidores manualmente se torna tedioso rapidamente — especialmente quando sua API já se descreve perfeitamente através do OpenAPI.

Esse é o vazio que mcp-server-openapi preenche.

O Pipeline de Processamento

  OpenAPI Spec        mcp-server-openapi           MCP Client
  ------------    --------------------------    ---------------

  +---------+     +-----+  +------+  +-----+   +-----------+
  |  YAML/  |---->|Parse|->|Filter|->|Schema|-->| Descobre  |
  |  JSON   |     |     |  |      |  | Gen  |   |   Ferramentas |
  +---------+     +-----+  +------+  +-----+   +-----+-----+
                                                      |
                  +--------------------------+         |
                  |  Quando a ferramenta é chamada:    |<--------+
                  |                          |
                  |  1. Mapear args -> requisição HTTP |
                  |  2. Injetar cabeçalhos de autenticação  |
                  |  3. Executar requisição      |---> Sua API
                  |  4. Retornar resposta      |<--- Resposta
                  +--------------------------+

Como Funciona Passo a Passo

1. Analisa sua especificação usando kin-openapi — o padrão ouro para análise de OpenAPI em Go. Resolução completa de $ref, oneOf/anyOf/allOf — tudo.
2. Filtra operações — apenas endpoints marcados com mcp são expostos (você escolhe o que fica visível)
3. Gera JSON Schema para cada entrada da ferramenta — parâmetros de caminho, parâmetros de consulta, cabeçalhos e corpo são todos mapeados automaticamente
4. Serve ferramentas via stdio ou HTTP Streamable usando o mcp-go SDK
5. Executa requisições HTTP quando um cliente MCP chama uma ferramenta, mapeando respostas de volta de forma limpa

A chave é: sua especificação OpenAPI já tem tudo o que precisa para gerar ferramentas MCP — tipos de parâmetros, descrições, campos obrigatórios, corpos de requisição. Por que escrever isso duas vezes?

Início Rápido (5 Minutos)

1. Instalar

go install github.com/soyvural/mcp-server-openapi/cmd/mcp-server-openapi@latest

2. Marque Seus Endpoints

Adicione a tag mcp a qualquer operação que você deseja expor:

paths:
  /pets/{petId}:
    get:
      tags:
        - mcp              # <-- Este é o interruptor mágico
      operationId: getPetById
      summary: Obter um animal de estimação por ID
      parameters:
        - name: petId
          in: path
          required: true
          schema:
            type: integer

3. Configure Seu Cliente MCP

Adicione isso à configuração do seu cliente MCP (funciona com qualquer aplicativo compatível com MCP — Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "my-api": {
      "command": "mcp-server-openapi",
      "args": ["--spec", "/caminho/para/seu/openapi.yaml"]
    }
  }
}

Reinicie seu cliente MCP e suas ferramentas de API aparecem automaticamente. Pronto. 🎉

As Extensões x-mcp (Minha Parte Favorita)

Você pode ajustar como sua API aparece para o cliente MCP usando extensões de fornecedor OpenAPI:

/users/{id}:
  get:
    tags: [mcp]
    operationId: getUserById
    x-mcp-tool-name: get_user            # Nome mais amigável
    x-mcp-description: |                 # Descrição otimizada para IA
      Busque informações detalhadas do usuário incluindo
      perfil, configurações e atividade.

/internal/health: