Como o mcpify passou de "funciona nos meus exemplos" para sobreviver à especificação ao vivo api.weather.gov — uma história na arqueologia do OpenAPI.

O problema que ninguém avisa

Todo tutorial sobre como conectar o Claude (ou Cursor, ou qualquer agente) à sua própria API REST termina da mesma forma: "e agora você escreve um servidor MCP personalizado."

Se sua API tem 40 endpoints, são 40 definições de ferramentas. Esquemas de parâmetros. Validação. Tratamento de erros. Infraestrutura de autenticação. E então sua API muda na próxima sprint — porque APIs reais mudam na próxima sprint — e você faz tudo de novo.

A questão é a seguinte: se sua API tem um documento OpenAPI (Swagger), todas as informações que um servidor MCP precisa já existem. Os caminhos, os tipos de parâmetros, os campos obrigatórios, os enums, as descrições que você escreveu para humanos. Escrever uma segunda versão, mantida manualmente, do mesmo contrato é trabalho desnecessário.

É por isso que eu construí o mcpify: aponte-o para qualquer especificação OpenAPI 3.x — arquivo ou URL — e ele serve toda a API como um servidor MCP via stdio. Sem geração de código. Sem repositório wrapper. Um comando.

Bash

pipx install mcpify-openapi

mcpify list https://api.weather.gov/openapi.json --read-only
mcpify serve https://api.weather.gov/openapi.json --read-only
Esse segundo comando conecta 69 ferramentas reais em qualquer cliente MCP — cada endpoint do Serviço Nacional de Meteorologia, com parâmetros tipados e valores enumerados que o modelo escolhe de uma lista em vez de digitar livremente.

"Funciona nos meus exemplos" — palavras finais famosas

A primeira versão foi honestamente ingênua. Eu a testei contra as especificações habituais do estilo petstore e a chamei de concluída. Então eu fiz algo melhor do que escrever mais exemplos eu mesmo: publiquei e deixei as pessoas testarem APIs reais.

Elas encontraram as lacunas rapidamente:

$ref'd esquemas de parâmetros a derrubaram. A especificação ao vivo do weather.gov referencia #/components/schemas/... de seus parâmetros — o OpenAPI do mundo real faz isso em toda parte. Meu resolvedor estava recebendo uma especificação vazia. Um bug de linha, cada API "séria" morta na chegada.
GET-only não é livre de efeitos colaterais. Um modo "somente leitura" que filtra por método HTTP expõe felizmente GET /admin/reset-cache. Oops.
$refs circulares, corpos multipart, variáveis de URL do servidor, URLs base relativas, respostas de 300KB — cada um é uma pequena mina terrestre que especificações de brinquedo nunca pisam.
A correção não foi apenas corrigir esses problemas — foi construir um corpus de especificações hostis a partir de estudos de falhas publicados (há um ótimo artigo no arXiv sobre geração REST→MCP em 18 APIs reais — suas 3 principais categorias de falha são todos problemas de URL base e declaração de autenticação). Cada mina terrestre agora é um teste de regressão fixo. A especificação do weather.gov é carregada em CI a cada push. 82 testes no total, mypy estrito, ruff, CodeQL, matrizes Linux + Windows.

Essa é a versão honesta de "nível de produção": não é uma sensação, é uma lista de verificação que você re-executa.

As partes das quais mais me orgulho

A camada de política. Após o feedback de mutação GET, --read-only ganhou dentes:

Bash

mcpify serve api.json --read-only --deny '/admin' --allow '/search'
--deny oculta caminhos não importa o que (para que o GET mutante desapareça), --allow reinclui endpoints POST do estilo leitura (pesquisa com corpo é uma leitura). Negar sempre vence — menos surpresa para quem o configura.

Escopo amigável a tokens. Cada descrição de ferramenta consome tokens de contexto a cada turno. Uma API de 200 endpoints como 200 ferramentas é como você é cobrado por um modelo relendo uma lista telefônica. --tag pagamentos, --include /v1/orders, --exclude /internal mantém a superfície no que o agente realmente precisa.

Segredos ficam fora da banda. --auth-env API_TOKEN --auth-style bearer — a credencial vive no ambiente, é injetada no momento da chamada e nunca aparece em esquemas de ferramentas, configurações ou logs. O parâmetro do cabeçalho de autorização é removido dos esquemas anunciados para que o modelo não possa injetar o seu próprio.

Uma tag = lançamento completo. Enviar v1.0.4 publica PyPI + o Registro MCP oficial (io.github.furkan708/mcpify) + um Lançamento do GitHub + uma imagem de contêiner GHCR, via OIDC, sem tokens armazenados.

Experimente em 60 segundos

Bash

runner sem instalação (uv):

uvx --from mcpify-openapi mcpify list ./openapi.json --read-only

ou instale:

pipx install mcpify-openapi

conecte-o ao Claude Desktop (claude_desktop_config.json):

{
"mcpServers": {
"minha-api": {
"command": "mcpify",
"args": ["serve", "./openapi.json", "--read-only"]
}
}
}
Ou como um contêiner: docker run -i ghcr.io/furkan708/mcpify:latest serve ./spec.json --read-only

O que ele deliberadamente não faz

APIs sem especificação — se não houver documento OpenAPI, o mcpify não tem nada para projetar. (Proteção contra lixo para ambos nós.)
Tentativas / limitação de taxa / disjuntores — tentar um POST não idempotente pode duplicar efeitos colaterais; isso pertence ao seu gateway, onde são observáveis. O mcpify limita o raio de explosão em vez disso: somente leitura, políticas de negação, timeouts, respostas truncadas.
Webhooks & streaming — MCP-over-stdio é requisição/resposta hoje; transportes remotos estão no roteiro.
Ser transparente sobre limites faz parte do contrato de confiança, assim como os testes.

Repositório: github.com/furkan708/mcpify · PyPI: mcpify-openapi · Docs: USAGE · Lista de verificação de auditoria

Se você apontá-lo para uma API real — o serviço interno da sua empresa, um público, qualquer coisa que quebre — eu quero saber o que explode. Cada relatório de falha até agora o tornou melhor, e há uma lista de boas primeiras questões se você preferir construir do que quebrar.