Qencode MCP

Qencode permite a los asistentes de IA transcodificar, analizar, editar, optimizar y entregar video mediante lenguaje natural, impulsado por una plataforma de procesamiento de video en la nube.

GitHub

Prueba este MCPPatrocinado

Documentación

qencode-mcp

Servidor de Model Context Protocol (MCP) para la API de transcodificación de Qencode.

Conecta cualquier cliente de IA compatible con MCP — Claude, Cursor, ChatGPT, Grok, Gemini — a tu cuenta de Qencode y permite que envíe, supervise y razone sobre trabajos de transcodificación en tu nombre.

Ejemplo rápido

Una vez que tu cliente esté conectado (consulta Conectar un cliente), pídele a tu agente en lenguaje natural:

Transcodifica https://example.com/input.mp4 como una escalera HLS a 1080/720/540/360. Colócalo en mi bucket de R2 videos/demo/.

El agente selecciona la receta hls_abr, completa los parámetros de codificación por rendition, envía mediante start_encode2_raw y consulta hasta que el trabajo esté terminado.

Requisitos previos

Una cuenta de portal de Qencode con al menos un proyecto — inicia sesión en el portal de tu entorno: https://portal.qencode.com (producción) o https://portal-qa.qencode.com (QA). Seleccionas el proyecto durante el paso de consentimiento de OAuth.
Un cliente compatible con MCP (Claude, Cursor, ChatGPT, Grok, Gemini o cualquier cliente personalizado).

No hay claves de API que copiar en la configuración del cliente — la autenticación es OAuth basada en navegador.

Cómo funciona

El conector utiliza OAuth 2.1 estándar — sin claves de API en la configuración del cliente. En el primer uso, tu cliente abre un navegador, inicias sesión en tu cuenta del portal de Qencode, eliges un proyecto y apruebas los alcances solicitados. El cliente almacena el token; las llamadas posteriores son silenciosas hasta que el token expire.

Alcances que el cliente debe solicitar al autorizar (publicados mediante metadatos de recurso protegido):

Alcance	Propósito
`openid`	Identidad OIDC
`profile`	Nombre para mostrar
`email`	Correo de la cuenta
`offline_access`	Token de actualización
`transcoding:read`	`get_job_status`, `list_jobs`, herramientas de documentación
`transcoding:write`	`transcode_video`, `start_encode2_raw`

El RS aplica transcoding:read y transcoding:write en los tokens de acceso a nivel de transporte.

Tus claves de API de Qencode nunca salen del portal. El servidor MCP deriva un token de sesión de corta duración por solicitud mediante un endpoint interno del portal.

Entornos

El mismo conector está desplegado en dos entornos. Cada uno tiene sus propios dominios, cuentas, proyectos y credenciales — inicia sesión en el portal que coincida con el endpoint al que te conectas.

Rol	Producción	QA (pruebas)
Endpoint MCP (conectar aquí)	`https://mcp.qencode.com/mcp`	`https://mcp-qa.qencode.com/mcp`
Portal (iniciar sesión / proyectos)	`https://portal.qencode.com`	`https://portal-qa.qencode.com`
Servidor de autorización	`https://auth.qencode.com`	`https://auth-qa.qencode.com`
API de Qencode	`https://api.qencode.com`	`https://api-qa.qencode.com`

Las instrucciones a continuación usan el endpoint de producción. Para probar contra QA, intercambia la URL de QA e inicia sesión en el portal de QA.

Conectar un cliente

Endpoint: https://mcp.qencode.com/mcp — el mismo para cada cliente a continuación. Inicia sesión en tu cuenta de Qencode cuando se abra el navegador y aprueba el acceso.

QA (pruebas internas): usa https://mcp-qa.qencode.com/mcp e inicia sesión en el portal de QA en su lugar.

Cliente	Dónde agregarlo	URL / configuración de MCP
Claude (chat)	Cuadro de mensaje → + → Conectores → Agregar conector	`https://mcp.qencode.com/mcp`
Claude Code	Terminal	`claude mcp add --transport http qencode https://mcp.qencode.com/mcp`
ChatGPT	Apps → buscar Qencode → Conectar; o Modo Desarrollador → Crear aplicación	URL del conector: `https://mcp.qencode.com/mcp`
Gemini	`~/.gemini/settings.json` → `mcpServers`	`"httpUrl": "https://mcp.qencode.com/mcp"` — luego `/mcp auth qencode` en la CLI
Cursor	Configuración → Herramientas y MCP → Nuevo servidor MCP (o `~/.cursor/mcp.json`)	`"url": "https://mcp.qencode.com/mcp"` — reinicia Cursor después de guardar

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
    }
  }
}

Consejo: inicia sesión en portal.qencode.com en tu navegador antes de conectar — el flujo de OAuth es más fluido.

Lo que expone el conector

Herramientas

Transcodificación y trabajos

Herramienta	Descripción
`transcode_video`	Envía un trabajo desde una URL de origen a una o más salidas. Envoltorio de conveniencia — inyecta automáticamente `encoder_version: 2` (o `1` para VMAF) cuando se omite.
`start_encode2_raw`	Vía de escape — envía un trabajo con el JSON completo de `query` exactamente como lo espera la API de Qencode.
`get_job_status`	Instantánea de estado de una sola consulta por `task_token`.
`get_job_status_detailed`	Estado completo y autoritativo del trabajo, incluido el progreso por rendition y los detalles de salida.
`list_jobs`	Tarjeta de trabajos en línea para el `task_tokens` de la conversación actual — insignias de estado, filtros, filas expandibles, URLs de salida. La tarjeta se actualiza sola mientras haya algún trabajo en ejecución.
`fetch_job_result`	Lee el contenido de un archivo de resultado producido por un trabajo de análisis (transcripción, informe VMAF, metadatos, categorización).
`wait_for_job`	Obsoleta. Devuelve inmediatamente y apunta a `list_jobs`; se mantiene para que conversaciones antiguas no encuentren "herramienta no encontrada".
`search_qencode_docs`	Busca en la base de conocimiento integrada de recetas y documentación de referencia.
`fetch_qencode_doc`	Obtiene el contenido completo de un recurso de la base de conocimiento por URI de `qencode://` (contraparte basada en herramienta de `resources/read`).

Reproducción

Herramienta	Descripción
`open_player`	Renderiza un resultado reproducible en línea — MP4/WebM progresivo o un manifiesto HLS/DASH. El servidor aplica la política de sandbox del host que llama, por lo que los orígenes permitidos dependen del cliente.
`refresh_jobs`	Sondeo silencioso propio de la tarjeta de trabajos. No está pensada para ser llamada directamente por un agente; respalda la actualización automática de la tarjeta y su botón de Actualizar.

Almacenamiento de medios

Gestión de buckets e ingesta para Qencode Media Storage. Estos usan la misma concesión de OAuth que las herramientas de transcodificación — sin alcance adicional ni nuevo consentimiento.

Herramienta	Descripción
`list_buckets`	Lista los buckets de Media Storage disponibles para la cuenta.
`create_bucket`	Crea un nuevo bucket. Se llama solo ante una solicitud explícita — no para satisfacer un `destination` faltante.
`list_objects`	Explora el contenido de un bucket.
`get_download_url`	Devuelve una URL de descarga con límite de tiempo para un objeto existente.
`download_url_to_bucket`	Copia del lado del servidor de una URL pública a un bucket (ingesta, sin transcodificación).

Recursos

El servidor incluye una base de conocimiento de recetas y documentación de referencia, expuesta como recursos de MCP para que el agente pueda obtener solo lo que necesita. URIs notables:

qencode://docs/best-practices — valores predeterminados de composición que el agente aplica automáticamente
qencode://docs/storage — matriz de compatibilidad de destinos (Qencode S3, R2, AWS S3, Azure, B2, FTP/SFTP)
qencode://docs/error-codes — código de error → causa → solución
qencode://docs/gotchas — peculiaridades no obvias de la API
qencode://schema/digest — referencia completa de atributos para start_encode2
qencode://recipe/<slug> — uno por flujo de funcionalidad: 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

Usa search_qencode_docs para descubrir la URI de receta correcta para un objetivo.

Prompts (comandos de barra)

En clientes que muestran prompts de MCP, hay 40 plantillas de un solo uso disponibles. Cada una le indica al agente que lea el recurso qencode://recipe/... correspondiente y envíe mediante start_encode2_raw.

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

Códecs / calidad: encode_av1, encode_lcevc, tune_per_title, check_vmaf, ai_upscale_video, convert_hdr_to_sdr

Audio / imágenes / texto: extract_audio, generate_thumbnails, generate_smart_thumbnails, generate_waveform, transcribe, add_subtitles

Edición / encuadre: trim_clip, rotate_video, deinterlace_video, enable_smart_crop, add_watermark, add_html_overlay

Inmersivo: enable_vr_mode, inject_360_metadata

Análisis: get_video_metadata, analyze_video, detect_ai_generated

Sonda / unión: stitch_videos

Ganchos de producción: 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

Reglas de URL de origen

transcode_video y start_encode2_raw aceptan valores de source con esquemas https://, http://, s3:// o tus:. Las URLs FTP/SFTP y privadas/de metadatos se rechazan en el límite de la herramienta (defensa SSRF). Consulta docs/security/THREAT_MODEL.md para conocer las limitaciones.

Seguridad

La autenticación es solo OAuth 2.1 — no existe modo de clave de API estática. Tus claves de API de Qencode nunca salen del portal; el servidor deriva un token de sesión nuevo y de corta duración por solicitud mediante un endpoint interno del portal. Las URLs de origen se validan en el límite de la herramienta (defensa SSRF — consulta Reglas de URL de origen).

Modelo de amenazas completo y cobertura de pruebas adversariales: docs/security/THREAT_MODEL.md.

Desarrollo

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

Las pruebas de protocolo se ejecutan completamente sin conexión (servidor de autorización, portal y API de Qencode simulados). CI es el trabajo de Jenkins mcp_automated_tests (Jenkinsfile.manual): casillas manuales para cualquier capa, cron nocturno de L3, cron semanal de L4.

Versiones de protocolo MCP compatibles

Los clientes negocian una versión en initialize. Este servidor tiene como objetivo MCP 2025-11-25 como versión principal. CI también ejecuta pruebas de conformidad contra 2025-06-18 porque el comportamiento de agrupación JSON-RPC difiere entre revisiones anteriores. No afirmamos soporte para 2025-03-26 ni semánticas de cable más antiguas más allá de lo que negocia el SDK subyacente.

Versión	Soporte	Notas
2025-11-25	Principal	HTTP transmisible, SSE reanudable donde se use
2025-06-18	Matriz de CI	Guardia de regresión para clientes de mediados de 2025
2025-03-26	No objetivo	La semántica de agrupación difiere de 2025-06-18

Listados de directorios (Glama)

La instalación que usan los usuarios del conector es el endpoint alojado anterior. Solo para la puntuación de Glama Servers / awesome-mcp-servers, este repositorio también incluye qencode-mcp-inspect (stdio, entorno ficticio, tools/call rechazado). Ese no es un transporte de cliente compatible. Consulta docs/glama-release.md.

Más documentación

Servidor local / variables de entorno: docs/local-development.md
Capas de prueba (L1–L5): docs/testing.md y tests/README.md
L3 contra QA/PROD en vivo: tests/integration/README.md
Evaluaciones de agente L4: evals/README.md
Puerta de pre-lanzamiento: docs/release-checklist.md

Política de versionado

El conector sigue SemVer aplicado a la superficie de MCP — herramientas, prompts, recursos, alcances de OAuth y versiones de protocolo compatibles. Los cambios en la API HTTP de Qencode están fuera de alcance (son preocupación de la propia API, no del conector).

MAJOR — un cambio de superficie que rompe compatibilidad: se elimina o renombra una herramienta/prompt/recurso, un argumento previamente opcional se vuelve obligatorio, se agrega o restringe un alcance de OAuth de forma que fuerce un nuevo consentimiento, o se elimina una versión de protocolo MCP compatible.
MINOR — una adición compatible hacia atrás: una nueva herramienta/prompt/recurso, un nuevo argumento opcional o una versión de protocolo recién compatible.
PATCH — sin cambio en la forma de la superficie: reformulaciones de descripciones de herramientas/prompts, actualizaciones de la base de conocimiento/documentación y correcciones de errores. Los cambios de superficie están protegidos por pruebas de instantáneas en tests/protocol/. Cuando cambies la superficie, regenera las instantáneas (python scripts/regen_tools_snapshot.py) y aumenta la versión en el mismo PR: pyproject.toml, src/qencode_mcp/__init__.py, server.json y una nueva entrada de CHANGELOG.md deben coincidir todas.

Enlaces

Registro de cambios: CHANGELOG.md
Especificación del servidor de autorización OAuth 2.1: docs/oauth-spec.md
Portal de Qencode: https://portal.qencode.com (producción) · https://portal-qa.qencode.com (QA)
Referencia de la API de Qencode: https://docs.qencode.com/api-reference/transcoding