Transforme Qualquer Especificação OpenAPI em Ferramentas MCP Seguras para Claude em Segundos

Se você já tentou conectar APIs REST a agentes de IA, provavelmente já passou por este momento:

O servidor MCP inicia. Claude vê as ferramentas. Você pede para ele buscar alguns dados.

E ele chama o endpoint errado. Ou dispara um DELETE que não deveria. Ou fica confuso entre duas ferramentas que parecem similares e simplesmente... escolhe uma.

Seu especificação passou em todos os linters. A conversão funcionou bem.

O agente ainda quebrou.

Essa é a lacuna que ninguém fala. As especificações OpenAPI foram projetadas para desenvolvedores humanos que podem ler documentações vagas, inferir intenções e aplicar bom senso. Agentes de IA não conseguem fazer nada disso. Eles precisam:

• Que cada endpoint tenha um nome claro e inequívoco (operationId)
• Descrições que digam quando chamar uma ferramenta, e não apenas o que ela faz
• Sinais de segurança explícitos em operações destrutivas
• Nenhuma duas ferramentas que pareçam similares o suficiente para causar confusão

Linters padrão não verificam nada disso. Então a especificação parece limpa, o linter passa verde, e o agente silenciosamente toma decisões ruins.

Esse é o problema que eu continuei enfrentando. Então eu construí mcp-openapi-doctor para consertá-lo.

O que o mcp-openapi-doctor faz

É uma ferramenta CLI com quatro comandos que pegam uma especificação OpenAPI ou Swagger bruta e a tornam genuinamente pronta para agentes.

Especificação OpenAPI → mcp-openapi-doctor → especificação limpa + sobreposição MCP → seu servidor MCP → Claude

É um pré-processador, não um substituto. Ele se encaixa na frente de qualquer ferramenta MCP que você já esteja usando — AWS OpenAPI MCP, FastMCP, Tyk, ou seu próprio servidor.

Passo 1: Inspecionar — Veja Sua Pontuação de Prontidão para Agentes

A primeira coisa que você quer saber é quão quebrada sua especificação realmente está para uso do agente.

npx mcp-openapi-doctor inspect https://petstore3.swagger.io/api/v3/openapi.json

Você recebe uma pontuação de 0–100 dividida em três dimensões:

MCP OpenAPI Doctor 🩺
─────────────────────────────────────
API:        Petstore API v1.0.0
Operações: 19 em 9 caminhos
Versão:    OpenAPI 3.0.3

Pontuação de prontidão do agente: 61/100

Segurança       ████░░░░░░  24/40
Clareza      ███░░░░░░░  21/35
Eficiência   █████░░░░░  16/25

Problemas encontrados:
  ✗ erro   6x falta de operationId
  ✗ erro   3x endpoint destrutivo sem aviso
  ⚠ aviso    8x descrição vaga ou ausente
  ⚠ aviso    1x esquema de resposta excede 30 campos

Esses não são problemas de estilo. Cada um é um modo real de falha do agente:

Passo 2: Gerar — Visualize Exatamente o Que Claude Verá

Antes de executar um servidor, generate mostra exatamente as ferramentas que Claude terá acesso — nomes, descrições, entradas e classificação de segurança.

npx mcp-openapi-doctor generate ./openapi.yaml

Ferramentas geradas: 4

✓ list_users
  Operação: GET /users
  Segurança:    SAFE_READ
  Entradas:    nenhuma

✓ get_user
  Operação: GET /users/{id}
  Segurança:    SAFE_READ
  Entradas:    id*

⚠ update_user
  Operação: PUT /users/{id}
  Segurança:    WRITE
  Entradas:    id*, corpo

✗ delete_user
  Operação: DELETE /users/{id}
  Segurança:    DESTRUCTIVE
  Entradas:    id*

Use --read-only para ver apenas as ferramentas que seriam expostas em modo seguro:

npx mcp-openapi-doctor generate ./openapi.yaml --read-only
# Apenas ferramentas SAFE_READ aparecem — WRITE e DESTRUCTIVE estão ocultas do agente

Isso é útil quando você está definindo o que deseja que Claude acesse antes de abrir operações de escrita.

Passo 3: Corrigir — Corrigir Automaticamente o Que É Seguro Corrigir

fix gera uma especificação limpa em uma pasta de saída. Ele nunca modifica seu arquivo original.

npx mcp-openapi-doctor fix ./openapi.yaml --out ./output/ --diff

O que é gerado:

output/
├── cleaned-openapi.yaml    ← especificação corrigida com as correções aplicadas
├── mcp-overlay.yaml        ← metadados x-mcp-* para servidores MCP a jusante
├── doctor-report.json      ← problemas estruturados + pontuação
├── fixes.md                ← log legível por humanos de cada alteração
├── summary.md              ← pontuação antes/depois + ações restantes
├── diff.md                 ← diff legível de cada alteração
└── diff.json               ← diff estruturado para ferramentas

O que o consertador mudará com segurança:

• Gerar operationId ausentes a partir do método + caminho, slugificado e deduplicado
• Normalizar todos os valores de operationId para snake_case
• Adicionar resumos de fallback onde estiverem ausentes
• Injetar x-mcp-destructive: true em endpoints DELETE
• Adicionar esquemas de espaço reservado para corpos de solicitação e respostas ausentes

O que ele nunca fará:

• Remover qualquer endpoint
• Mudar o comportamento em tempo de execução
• Tocar no seu arquivo fonte
• Usar IA para reescrever qualquer coisa (todas as correções são determinísticas)

O summary.md mostra a pontuação antes/depois e o que ainda precisa de um humano:

Antes: 61/100
Depois:  88/100

Corrigido automaticamente:
  ✓ 6 operationIds ausentes gerados
  ✓ 3 endpoints destrutivos sinalizados com x-mcp-destructive
  ✓ 4 resumos ausentes adicionados

Ainda precisa da sua atenção:
  ⚠ 8 descrições vagas — essas precisam de contexto humano para serem corrigidas bem
  ⚠ 1 esquema de resposta com 87 campos — considere um endpoint filtrado

Passo 4: Servir — Conectar Diretamente ao Claude Desktop

Uma vez que sua especificação esteja limpa, serve inicia um servidor stdio MCP ao qual o Claude Desktop se conecta diretamente.

npx mcp-openapi-doctor serve ./openapi.yaml --read-only

O terminal parecerá ocioso — isso é esperado. Ele está aguardando um cliente MCP via stdio.

Adicione-o à sua configuração do Claude Desktop:

{
  "mcpServers": {