mcpo (MCP-to-OpenAPI) — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Drop-in: qualquer MCP stdio vira HTTP+OpenAPI
UI Swagger em /docs gerada automaticamente
JSON Schema para inputs e outputs das ferramentas
OAuth (client credentials + JWT) suportado
Execute vários MCPs encapsulados em um único processo
Python leve (FastAPI), Apache 2.0

Demo ao vivo

Como fica na prática

mcpo-openapi-mcp.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcpo-openapi-mcp",
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcpo-openapi-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "mcpo",
          "--",
          "uvx",
          "mcp-server-time"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add mcpo-openapi-mcp -- uvx mcpo -- uvx mcp-server-time

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: mcpo (MCP-to-OpenAPI)

Como chamar um servidor MCP via curl, Postman ou OpenAI function-calling

👤 Devs de backend cujo runtime ainda não fala MCP ⏱ ~15 min intermediate

Quando usar: Você escolheu um ótimo servidor MCP, mas sua stack em produção é um serviço Python, OpenAI Assistants API ou algo que espera HTTP+JSON.

Pré-requisitos

Um comando MCP que você normalmente executaria — ex.: uvx mcp-server-time ou npx -y @modelcontextprotocol/server-fetch

Fluxo

Encapsular

Execute uvx mcpo --port 8000 -- uvx mcp-server-time e confirme que /docs está no ar.✓ Copiado

→ A UI Swagger mostra as ferramentas como endpoints
Chamar via curl

Mostre-me um curl funcional que chama a ferramenta de tempo com timezone=America/Los_Angeles.✓ Copiado

→ Retorna a hora atual com informações de fuso horário
Integrar ao OpenAI

Gere uma spec de function-calling a partir de /openapi.json que eu possa colar na API do OpenAI.✓ Copiado

→ Spec gerada; teste rápido com sucesso

Resultado: Um servidor MCP que um backend não-MCP pode acionar via HTTP.

Armadilhas

Ferramentas de longa duração expiram com as configurações padrão do uvicorn — Passe --timeout-keep-alive 600 ao mcpo, ou coloque um nginx na frente com timeouts correspondentes

Executar vários MCPs por trás de um único serviço HTTP

👤 Engenheiros de plataforma consolidando muitos MCPs ⏱ ~30 min intermediate

Quando usar: Você quer uma única URL hospedando os MCPs de tempo, fetch e filesystem, cada um em seu próprio prefixo de caminho.

Fluxo

Compor

Escreva a configuração do mcpo para 3 servidores — time em /time, fetch em /fetch, filesystem em /fs.✓ Copiado

→ config.yaml com 3 serviços; mcpo os serve
Adicionar OAuth

Configure autenticação JWT via o issuer do meu tenant Auth0. Os endpoints exigem um token válido.✓ Copiado

→ Chamadas sem token retornam 401

Resultado: Um único ponto de entrada HTTP seguro hospedando vários MCPs.

Armadilhas

Ferramentas colidem quando 2 servidores expõem o mesmo nome — O mcpo aplica namespace por prefixo; conflitos de ferramentas são resolvidos pelo caminho da URL

Usar um MCP como parte de uma suíte de testes HTTP de integração

👤 Equipes de QA/SDET ⏱ ~25 min advanced

Quando usar: Você quer verificar o comportamento do seu servidor MCP com ferramentas de teste HTTP padrão.

Fluxo

Subir no CI

Adicione um job no GitHub Actions que executa o mcpo encapsulando nosso MCP e depois roda Playwright/pytest contra ele.✓ Copiado

→ Arquivo de workflow escrito; passa localmente
Asserções de schema

Faça snapshot de /openapi.json. Falhe o build se o schema mudar sem uma alteração explícita na origem.✓ Copiado

→ Guard de diff de schema no CI

Resultado: Pipeline de testes HTTP padrão aplicado a um servidor MCP.

Armadilhas

Instável se o MCP subjacente importa dependências pesadas na inicialização — Adicione um loop de espera por /healthz antes de executar os testes

Combine com: github

Combinações

Combine com outros MCPs para 10× de alavancagem

mcpo-openapi-mcp + filesystem

Persistir o /openapi.json gerado no repositório para revisão

Salve o /openapi.json atual em /api/contracts/$(date +%F).json.✓ Copiado

mcpo-openapi-mcp + github

Abrir um PR quando a spec OpenAPI mudar

Se o diff do snapshot não for vazio, abra um PR com o título 'OpenAPI changed'.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
GET /docs	(navegador)	Explorar a superfície de ferramentas visualmente	gratuito
GET /openapi.json	(nenhum)	Geração de código ou specs de function-calling	gratuito
POST /<tool>	JSON body matching tool input schema	Invocar uma ferramenta MCP encapsulada via HTTP	1 chamada MCP subjacente

Custo e limites

O que custa rodar

Cota de API: Limitado pelas cotas do MCP encapsulado
Tokens por chamada: Adiciona ~50 tokens de overhead
Monetário: Gratuito (Apache 2.0)
Dica: Encapsule uma vez por processo; não suba um subprocesso novo por requisição

Segurança

Permissões, segredos, alcance

Armazenamento de credenciais: Repassado ao MCP encapsulado via variáveis de ambiente; o mcpo em si não armazena nada

Saída de dados: Aonde quer que o MCP encapsulado teria egresso

Deploy padrão é sem autenticação — sempre coloque por trás de OAuth ou de uma rede privada

Solução de problemas

Erros comuns e correções

404 em /tool

O nome da ferramenta na URL deve corresponder exatamente ao nome da ferramenta MCP (case sensitive)

Verificar: Verifique /docs para o caminho correto

MCP subjacente travou

O mcpo reinicia por padrão, mas registra o erro — verifique o stderr

OAuth 401 com token válido

Verifique se audience e issuer correspondem à sua configuração; erro comum é a barra final ausente

Verificar: Decodifique o JWT em jwt.io e compare aud/iss

Alternativas

mcpo (MCP-to-OpenAPI) vs. outros

Alternativa	Quando usar	Troca
sparfenyuk/mcp-proxy	Você só precisa de bridging de transporte stdio↔HTTP, sem superfície OpenAPI	O mcp-proxy é mais baixo nível; o mcpo oferece /docs e OAuth
Escrever um wrapper FastAPI manualmente	Você precisa de lógica de negócio muito específica junto	O mcpo oferece 90% de graça

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills