Qencode MCP

O Qencode permite que assistentes de IA transcode, analise, edite, otimize e entregue vídeos usando linguagem natural, com o suporte de uma plataforma de processamento de vídeo em nuvem.

GitHub

Experimente este MCPPatrocinado

Documentação

qencode-mcp

Servidor Model Context Protocol (MCP) para a Qencode Transcoding API.

Conecte qualquer cliente de IA compatível com MCP — Claude, Cursor, ChatGPT, Grok, Gemini — à sua conta Qencode e deixe-o enviar, monitorar e raciocinar sobre trabalhos de transcodificação em seu nome.

Exemplo rápido

Depois que seu cliente estiver conectado (veja Conectar um cliente), pergunte ao seu agente em linguagem natural:

Transcodifique https://example.com/input.mp4 como uma escada HLS em 1080/720/540/360. Coloque no meu bucket R2 videos/demo/.

O agente escolhe a receita hls_abr, preenche os parâmetros de codificação por renderização, envia via start_encode2_raw e faz polling até o trabalho ser concluído.

Pré-requisitos

Uma conta no portal Qencode com pelo menos um projeto — faça login no portal do seu ambiente: https://portal.qencode.com (produção) ou https://portal-qa.qencode.com (QA). Você seleciona o projeto durante a etapa de consentimento OAuth.
Um cliente compatível com MCP (Claude, Cursor, ChatGPT, Grok, Gemini ou qualquer cliente personalizado).

Não há chaves de API para copiar na configuração do cliente — a autenticação é OAuth baseado em navegador.

Como funciona

O conector usa OAuth 2.1 padrão — sem chaves de API na configuração do cliente. No primeiro uso, seu cliente abre um navegador, você faz login na sua conta do portal Qencode, escolhe um projeto e aprova os escopos solicitados. O cliente armazena o token; chamadas subsequentes são silenciosas até o token expirar.

Escopos que o cliente deve solicitar na autorização (publicados via Protected Resource Metadata):

Escopo	Finalidade
`openid`	Identidade OIDC
`profile`	Nome de exibição
`email`	E-mail da conta
`offline_access`	Token de atualização
`transcoding:read`	`get_job_status`, `list_jobs`, ferramentas de documentação
`transcoding:write`	`transcode_video`, `start_encode2_raw`

O RS aplica transcoding:read e transcoding:write em tokens de acesso na camada de transporte.

Suas chaves de API Qencode nunca saem do portal. O servidor MCP deriva um token de sessão de curta duração por requisição através de um endpoint interno do portal.

Ambientes

O mesmo conector é implantado em dois ambientes. Cada um tem seus próprios domínios, contas, projetos e credenciais — faça login no portal que corresponde ao endpoint ao qual você se conecta.

Função	Produção	QA (testes)
Endpoint MCP (conecte aqui)	`https://mcp.qencode.com/mcp`	`https://mcp-qa.qencode.com/mcp`
Portal (login / projetos)	`https://portal.qencode.com`	`https://portal-qa.qencode.com`
Servidor de autorização	`https://auth.qencode.com`	`https://auth-qa.qencode.com`
API Qencode	`https://api.qencode.com`	`https://api-qa.qencode.com`

As instruções abaixo usam o endpoint de produção. Para testar contra QA, troque pela URL de QA e faça login no portal de QA.

Conectar um cliente

Endpoint: https://mcp.qencode.com/mcp — o mesmo para todos os clientes abaixo. Faça login na sua conta Qencode quando o navegador abrir e aprove o acesso.

QA (testes internos): use https://mcp-qa.qencode.com/mcp e faça login no portal de QA.

Cliente	Onde adicionar	URL / configuração MCP
Claude (chat)	Caixa de mensagem → + → Conectores → Adicionar conector	`https://mcp.qencode.com/mcp`
Claude Code	Terminal	`claude mcp add --transport http qencode https://mcp.qencode.com/mcp`
ChatGPT	Apps → pesquise Qencode → Conectar; ou Modo Desenvolvedor → Criar app	URL do conector: `https://mcp.qencode.com/mcp`
Gemini	`~/.gemini/settings.json` → `mcpServers`	`"httpUrl": "https://mcp.qencode.com/mcp"` — depois `/mcp auth qencode` no CLI
Cursor	Configurações → Ferramentas e MCP → Novo servidor MCP (ou `~/.cursor/mcp.json`)	`"url": "https://mcp.qencode.com/mcp"` — reinicie o Cursor após salvar

Cursor (mcp.json):

{
  "mcpServers": {
    "qencode": { "url": "https://mcp.qencode.com/mcp" }
  }
}

Gemini (settings.json):

{
  "mcpServers": {
    "qencode": {
      "httpUrl": "https://mcp.qencode.com/mcp",
      "timeout": 30000,
      "trust": false
    }
  }
}

Dica: faça login em portal.qencode.com no seu navegador antes de conectar — o OAuth flui melhor.

O que o conector expõe

Ferramentas

Transcodificação e trabalhos

Ferramenta	Descrição
`transcode_video`	Envia um trabalho de uma URL de origem para uma ou mais saídas. Wrapper de conveniência — injeta automaticamente `encoder_version: 2` (ou `1` para VMAF) quando omitido.
`start_encode2_raw`	Válvula de escape — envia um trabalho com o JSON completo de `query` exatamente como a API Qencode espera.
`get_job_status`	Snapshot de status de uma única chamada por `task_token`.
`get_job_status_detailed`	Status completo e autoritativo do trabalho, incluindo progresso por renderização e detalhes de saída.
`list_jobs`	Cartão de trabalhos inline para o `task_tokens` da conversa atual — badges de status, filtros, linhas expansíveis, URLs de saída. O cartão se atualiza sozinho enquanto qualquer trabalho ainda estiver em execução.
`fetch_job_result`	Lê o conteúdo de um arquivo de resultado produzido por um trabalho de análise (transcrição, relatório VMAF, metadados, categorização).
`wait_for_job`	Obsoleto. Retorna imediatamente e aponta para `list_jobs`; mantido para que conversas antigas não encontrem "ferramenta não encontrada".
`search_qencode_docs`	Pesquisa a base de conhecimento integrada de receitas e documentos de referência.
`fetch_qencode_doc`	Busca o conteúdo completo de um recurso da base de conhecimento por URI `qencode://` (contraparte baseada em ferramenta de `resources/read`).

Reprodução

Ferramenta	Descrição
`open_player`	Renderiza um resultado reproduzível inline — MP4/WebM progressivo ou um manifesto HLS/DASH. O servidor aplica a política de sandbox do host chamador, então quais origens de origem são permitidas depende do cliente.
`refresh_jobs`	Poll silencioso do próprio cartão de trabalhos. Não deve ser chamado diretamente por um agente; ele dá suporte à atualização automática do cartão e ao botão Atualizar.

Armazenamento de mídia

Gerenciamento de buckets e ingestão para o Qencode Media Storage. Eles usam a mesma concessão OAuth das ferramentas de transcodificação — sem escopo extra e sem novo consentimento.

Ferramenta	Descrição
`list_buckets`	Lista os buckets de Media Storage disponíveis para a conta.
`create_bucket`	Cria um novo bucket. Chamado apenas mediante solicitação explícita — não para satisfazer um `destination` ausente.
`list_objects`	Navega pelo conteúdo de um bucket.
`get_download_url`	Retorna uma URL de download com tempo limitado para um objeto existente.
`download_url_to_bucket`	Cópia no lado do servidor de uma URL pública para um bucket (ingestão, sem transcodificação).

Recursos

O servidor inclui uma base de conhecimento de receitas e documentos de referência, expostos como recursos MCP para que o agente possa buscar apenas o que precisa. URIs notáveis:

qencode://docs/best-practices — padrões de composição que o agente aplica automaticamente
qencode://docs/storage — matriz de compatibilidade de destinos (Qencode S3, R2, AWS S3, Azure, B2, FTP/SFTP)
qencode://docs/error-codes — código de erro → causa → correção
qencode://docs/gotchas — peculiaridades não óbvias da API
qencode://schema/digest — referência completa de atributos para start_encode2
qencode://recipe/<slug> — um por fluxo de recurso: ai_detection, ai_upscaling, audio_outputs, callbacks, clip_trim, codec_av1, codec_lcevc, drm_aes128, drm_buydrm, drm_doverunner, drm_expressplay, drm_fairplay_ezdrm, drm_forensic_watermark, drm_playready_ezdrm, drm_widevine_ezdrm, hdr_to_sdr, hls_abr, incremental_abr, mp4_ladder, per_title_encoding, refresh_abr_playlist, reliability, repack, rotate_deinterlace, smart_crop, smart_thumbnail, speech_to_text, stitching, subtitles, thumbnails, video_intelligence, video_metadata, vmaf_quality, vr_360, vr_mode, watermark_logo, waveform

Use search_qencode_docs para descobrir o URI de receita correto para um objetivo.

Prompts (comandos de barra)

Em clientes que exibem prompts MCP, 40 modelos de uso único estão disponíveis. Cada um diz ao agente para ler o recurso qencode://recipe/... correspondente e enviar via start_encode2_raw.

ABR / empacotamento: encode_hls_abr, encode_dash_abr, encode_mp4_ladder, encode_incremental_rung, encode_refreshing_playlist, remux_repack

Codecs / qualidade: encode_av1, encode_lcevc, tune_per_title, check_vmaf, ai_upscale_video, convert_hdr_to_sdr

Áudio / imagens / texto: extract_audio, generate_thumbnails, generate_smart_thumbnails, generate_waveform, transcribe, add_subtitles

Edição / enquadramento: trim_clip, rotate_video, deinterlace_video, enable_smart_crop, add_watermark, add_html_overlay

Imersivo: enable_vr_mode, inject_360_metadata

Análise: get_video_metadata, analyze_video, detect_ai_generated

Sonda / junção: stitch_videos

Hooks de produção: enable_callbacks, enable_reliability

DRM: encode_aes128_hls, encode_widevine_ezdrm, encode_playready_ezdrm, encode_fairplay_ezdrm, encode_drm_buydrm, encode_drm_expressplay, encode_drm_doverunner, encode_forensic_watermark

Regras de URL de origem

transcode_video e start_encode2_raw aceitam valores source com esquemas https://, http://, s3:// ou tus:. URLs FTP/SFTP e privadas/de metadados são rejeitadas no limite da ferramenta (defesa SSRF). Veja docs/security/THREAT_MODEL.md para limitações.

Segurança

A autenticação é somente OAuth 2.1 — não há modo de chave de API estática. Suas chaves de API Qencode nunca saem do portal; o servidor deriva um token de sessão novo e de curta duração por requisição através de um endpoint interno do portal. URLs de origem são validadas no limite da ferramenta (defesa SSRF — veja Regras de URL de origem).

Modelo de ameaça completo e cobertura de testes adversariais: docs/security/THREAT_MODEL.md.

Desenvolvimento

uv venv && uv pip install -e ".[dev]"
NO_NETWORK=1 pytest -q              # offline L1 + L2 + L5 (~900 tests)
pytest -m protocol                # MCP wire conformance only
pytest -m unit                    # per-tool logic (FakeQencode)
pytest -m security                # OWASP MCP Top 10 adversarial suite

Os testes de protocolo são executados totalmente offline (Authorization Server, portal e API Qencode simulados). CI é o trabalho Jenkins mcp_automated_tests (Jenkinsfile.manual): caixas de seleção manuais para qualquer camada, cron L3 noturno, cron L4 semanal.

Versões de protocolo MCP suportadas

Os clientes negociam uma versão em initialize. Este servidor tem como alvo MCP 2025-11-25 como versão principal. O CI também executa testes de conformidade contra 2025-06-18 porque o comportamento de batching JSON-RPC difere entre revisões anteriores. Não afirmamos suporte para 2025-03-26 ou semânticas de wire mais antigas além do que o SDK subjacente negocia.

Versão	Suporte	Notas
2025-11-25	Principal	Streamable HTTP, SSE retomável onde usado
2025-06-18	Matriz CI	Guarda de regressão para clientes de meados de 2025
2025-03-26	Não alvo	Semântica de batching difere de 2025-06-18

Listagens de diretório (Glama)

A instalação de usuários do conector é o endpoint hospedado acima. Para pontuação apenas de Glama Servers / awesome-mcp-servers, este repositório também inclui qencode-mcp-inspect (stdio, env dummy, tools/call recusado). Isso não é um transporte de cliente suportado. Veja docs/glama-release.md.

Mais documentação

Servidor local / variáveis de ambiente: docs/local-development.md
Camadas de teste (L1–L5): docs/testing.md e tests/README.md
L3 contra QA/PROD ao vivo: tests/integration/README.md
Avaliações de agente L4: evals/README.md
Portão de pré-lançamento: docs/release-checklist.md

Política de versionamento

O conector segue SemVer aplicado à superfície MCP — ferramentas, prompts, recursos, escopos OAuth e versões de protocolo suportadas. Mudanças na API HTTP Qencode estão fora do escopo (são preocupação da própria API, não do conector).

MAJOR — uma mudança de superfície que quebra: uma ferramenta/prompt/recurso é removido ou renomeado, um argumento anteriormente opcional se torna obrigatório, um escopo OAuth é adicionado ou restringido de forma que force novo consentimento, ou uma versão de protocolo MCP suportada é descartada.
MINOR — uma adição compatível com versões anteriores: uma nova ferramenta/prompt/recurso, um novo argumento opcional ou uma versão de protocolo recém-suportada.
PATCH — nenhuma mudança na forma da superfície: reformulações de descrição de ferramenta/prompt, atualizações de base de conhecimento/documentação e correções de bugs. Alterações na superfície são protegidas por testes de snapshot em tests/protocol/. Quando você alterar a superfície, regenere os snapshots (python scripts/regen_tools_snapshot.py) e aumente a versão no mesmo PR: pyproject.toml, src/qencode_mcp/__init__.py, server.json e uma nova entrada CHANGELOG.md devem estar todas de acordo.