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

Documentación

qencode-mcp

Servidor del 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 deja 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 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 del 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 basado en navegador.

Cómo funciona

El conector utiliza OAuth 2.1 estándar: no hay 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 caduca.

Alcances que el cliente debe solicitar al autorizar (publicados mediante Protected Resource Metadata):

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`, `wait_for_job`, herramientas de documentación
`transcoding:write`	`transcode_video`, `start_encode2_raw`

El RS aplica transcoding:read y transcoding:write en los tokens de acceso en la capa 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 utilizan el endpoint de producción. Para probar contra QA, sustituye 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)	Message box → + → Connectors → Add connector	`https://mcp.qencode.com/mcp`
Claude Code	Terminal	`claude mcp add --transport http qencode https://mcp.qencode.com/mcp`
ChatGPT	Apps → search Qencode → Connect; or Developer Mode → Build app	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	Settings → Tools & MCP → New MCP Server (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 será 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 llamada por `task_token`.
`get_job_status_detailed`	Estado completo y autoritativo del trabajo, incluido el progreso por rendition y los detalles de salida.
`wait_for_job`	Consulta hasta el estado terminal, tiempo de espera o límite interno de consultas. No lo llames en paralelo con otras herramientas en el mismo lote del cliente.
`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 `qencode://` (contraparte basada en herramientas de `resources/read`).

Media Storage

Gestión de buckets e ingesta para Qencode Media Storage. Estos utilizan la misma concesión OAuth que las herramientas de transcodificación: sin alcance adicional y sin 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 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 evidentes de la API
qencode://schema/digest — referencia completa de atributos para start_encode2
qencode://recipe/<slug> — uno por flujo de funcionalidad: hls_abr, mp4_ladder, audio_outputs, thumbnails, speech_to_text, subtitles, stitching, drm_widevine_ezdrm, drm_fairplay_ezdrm, drm_playready_ezdrm, drm_aes128, drm_buydrm, drm_expressplay, codec_av1, per_title_encoding, incremental_abr, refresh_abr_playlist, callbacks, reliability, video_metadata

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

Prompts (comandos de barra)

En clientes que muestran prompts de MCP, hay 21 plantillas de una sola ejecución 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

Códecs / calidad: encode_av1, tune_per_title

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

Sondeo / unión: get_video_metadata, stitch_videos

Hooks 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

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 un 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 (~540 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 (Authorization Server, portal y API de Qencode simulados). CI es el trabajo de Jenkins mcp_automated_tests (Jenkinsfile.manual): casillas de verificación manuales para cualquier capa, cron L3 nocturno, cron L4 semanal.

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 declaramos soporte para 2025-03-26 ni semánticas de protocolo más antiguas más allá de lo que negocia el SDK subyacente.

Versión	Soporte	Notas
2025-11-25	Principal	Streamable HTTP, SSE reanudable donde se use
2025-06-18	Matriz de CI	Protección 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

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 agentes L4: evals/README.md
Puerta de pre-lanzamiento: docs/release-checklist.md

Política de versionado

El conector sigue SemVer aplicado a la superficie MCP — herramientas, prompts, recursos, alcances de OAuth y versiones de protocolo compatibles. Los cambios en la API HTTP de Qencode están fuera del alcance (son responsabilidad 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 antes opcional se vuelve obligatorio, se agrega o restringe un alcance de OAuth de forma que obligue a un nuevo consentimiento, o se elimina una versión de protocolo MCP compatible.
MINOR — una adición compatible con versiones anteriores: una nueva herramienta/prompt/recurso, un nuevo argumento opcional o una versión de protocolo recientemente compatible.
PATCH — sin cambios 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.

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