ViewMax MCP

MCP remoto para generación de video, imagen, música y voz con IA en Claude, Cursor y ChatGPT.

Ver en viewmax.studioPrueba este MCPPatrocinado

Documentación

Guía de Configuración y Ajustes de ViewMax MCP

Conecta un cliente MCP a ViewMax: herramientas, argumentos, costos de créditos, sondeo de tareas, reintentos idempotentes y manejo de errores para generación de video, imagen, música y audio.

¿Buscas una descripción general de lo que puede hacer el servidor? Comienza desde la página principal de ViewMax MCP: esta guía cubre la configuración y los ajustes en detalle.

Endpoint y autenticación

ViewMax expone un servidor MCP remoto llamado viewmax:

https://viewmax.studio/api/mcp

Usa solo Streamable HTTP: GET devuelve 405 y no hay un endpoint SSE heredado.

OAuth (claude.ai y Claude Desktop). Agrega un conector personalizado con la URL anterior, haz clic en Conectar e inicia sesión con tu cuenta de ViewMax. Los clientes descubren el flujo a través de /.well-known/oauth-protected-resource; no se necesita clave API.

Clave API (Claude Code, Cursor, Codex, VS Code, SDKs). Crea una clave en Configuración → Claves API y envíala en cada solicitud:

Authorization: Bearer sk-your-api-key

Sin un encabezado Authorization, el servidor aún responde a initialize, tools/list y las herramientas de catálogo (list_video_models, get_video_model, list_image_models, get_image_model, list_music_models, list_voices). get_task, wait_for_task, get_credits y cada herramienta generate_* devuelven un error unauthorized. Un token de portador que no sea ni una clave API válida ni un token de acceso OAuth válido recibe HTTP 401 con un desafío OAuth, por lo que un cliente configurado con una clave revocada puede pedirte que inicies sesión; crea una clave nueva.

Conectar un cliente

Cada fragmento apunta al mismo endpoint. Mantén la clave en la variable de entorno VIEWMAX_API_KEY en lugar de en un archivo confirmado. Estos fragmentos siguen el formato de configuración documentado de cada cliente; la sintaxis del cliente cambia entre versiones, así que si un campo es rechazado, usa la guía MCP de tu cliente con la URL y el encabezado anteriores.

claude.ai y Claude Desktop. Configuración → Conectores → Agregar conector personalizado. Nómbralo ViewMax, pega https://viewmax.studio/api/mcp, haz clic en Conectar e inicia sesión.

Claude Code.

claude mcp add --transport http viewmax https://viewmax.studio/api/mcp \
  --header "Authorization: Bearer $VIEWMAX_API_KEY"

Para compartir el servidor con un proyecto, confirma .mcp.json. Claude Code expande ${VIEWMAX_API_KEY} desde el entorno de cada desarrollador:

{
  "mcpServers": {
    "viewmax": {
      "type": "http",
      "url": "https://viewmax.studio/api/mcp",
      "headers": {
        "Authorization": "Bearer ${VIEWMAX_API_KEY}"
      }
    }
  }
}

Cursor. Agrega a ~/.cursor/mcp.json (o .cursor/mcp.json en un proyecto), luego recarga Cursor:

{
  "mcpServers": {
    "viewmax": {
      "url": "https://viewmax.studio/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:VIEWMAX_API_KEY}"
      }
    }
  }
}

Codex (ChatGPT). Codex lee la clave de la variable de entorno nombrada:

codex mcp add viewmax --url https://viewmax.studio/api/mcp \
  --bearer-token-env-var VIEWMAX_API_KEY

La entrada equivalente de ~/.codex/config.toml:

[mcp_servers.viewmax]
url = "https://viewmax.studio/api/mcp"
bearer_token_env_var = "VIEWMAX_API_KEY"

VS Code. Agrega .vscode/mcp.json; VS Code solicita la clave una vez y la almacena de forma segura:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "viewmax-api-key",
      "description": "ViewMax API key",
      "password": true
    }
  ],
  "servers": {
    "viewmax": {
      "type": "http",
      "url": "https://viewmax.studio/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:viewmax-api-key}"
      }
    }
  }
}

Cualquier otro cliente. Los agentes que pueden editar su propia configuración MCP pueden conectarse ellos mismos. Pega: "Agrega el servidor MCP de ViewMax a este cliente: transporte Streamable HTTP, URL https://viewmax.studio/api/mcp,, encabezado HTTP Authorization: Bearer <my API key>. Luego llama a get_credits para verificar la conexión."

list_video_models funciona sin autenticación, por lo que solo demuestra que el servidor es accesible; get_credits demuestra que la conexión está autenticada.

Herramientas

El servidor genera video, imagen, música y audio. La generación consume créditos de la cuenta conectada. En Pro/Ultra, las imágenes insignia (GPT Image 2, GPT Image 2.5, Nano Banana 2, Grok Imagine) usan el grupo compartido diario de uso justo, y también ViewMax C1 en Ultra; cost_credits es 0 cuando el grupo cubre una tarea.

Cada resultado de herramienta es un bloque de texto que contiene JSON. Las herramientas de catálogo, get_task, wait_for_task y get_credits están marcadas como de solo lectura (readOnlyHint), por lo que los clientes pueden ejecutarlas sin preguntar. Las herramientas generate_* están marcadas como no solo lectura, no destructivas, no idempotentes y de mundo abierto.

Tareas y cuenta

Herramienta	Argumentos	Resultado
`get_task`	`task_id`	`task_id`, `status`, `media_type`, `cost_credits`; `output_urls` una vez que existen resultados (las tareas de video también `video_urls`); `error_code` y `error_message` cuando `failed` o `canceled`
`wait_for_task`	`task_id`, opcional `timeout_seconds` (entero 1–50, predeterminado 45)	Verifica cada 5 segundos hasta que la tarea termine o pase el tiempo de espera; devuelve los campos `get_task`, más `poll_hint` mientras la tarea aún se está ejecutando
`get_credits`	ninguno	`remaining_credits`

Video

Herramienta	Argumentos	Resultado
`list_video_models`	ninguno	`id`, `label`, `vendor` de cada modelo, duraciones y resoluciones por modo, y `credits_label`
`get_video_model`	`model`	Entrada completa del catálogo: duraciones por modo, resoluciones, relaciones de aspecto, `audio_toggle`, créditos, `defaults` y `max_prompt_length` cuando el modelo tiene uno
`generate_video`	`model`, `prompt`; opcional `mode`, `image_urls`, `video_urls`, `duration`, `resolution`, `aspect_ratio`, `audio`, `source_video_duration_seconds` (> 0), `idempotency_key`	`task_id`, `status`, `cost_credits`, `poll_hint`

Si mode se omite, es image-to-video cuando image_urls está configurado, video-to-video cuando video_urls está configurado y, de lo contrario, text-to-video.
Los duration, resolution y aspect_ratio omitidos se completan desde el defaults del modo antes del precio, por lo que cost_credits coincide con lo que se renderiza.
Envía audio: true solo cuando el audio_toggle del modo es true.
Los modelos por segundo (Seedance 2.x, Seedance 2.5, MiniMax H3) necesitan source_video_duration_seconds con video_urls.
Las URL de medios deben ser URL públicas http(s) que el proveedor pueda obtener sin autenticación.

Imagen

Herramienta	Argumentos	Resultado
`list_image_models`	ninguno	`id`, `label`, `vendor` de cada modelo, relaciones de aspecto y calidades por modo, y `credits_label`
`get_image_model`	`model`	Capacidad completa y precio de créditos para un modelo de imagen
`generate_image`	`model`, `prompt`; opcional `scene` (`text-to-image` o `image-to-image`), `image_urls`, `aspect_ratio`, `quality`, `idempotency_key`	`task_id`, `status`, `cost_credits`, `poll_hint`

Si scene se omite, es image-to-image cuando image_urls está configurado. GPT Image 2.5 rechaza un quality o tamaño desconocido; otros modelos reemplazan un aspect_ratio o quality desconocido con su valor predeterminado y facturan ese valor, así que envía solo valores que el modelo liste.

Música

Herramienta	Argumentos	Resultado
`list_music_models`	ninguno	El modelo de música, sus controles y el costo de créditos
`generate_music`	`prompt`; opcional `duration_seconds` (3–300, predeterminado 60), `instrumental`, `style`, `lyrics`, `idempotency_key`	`task_id`, `status`, `cost_credits`; generalmente ya `output_urls`

La música cuesta 60 créditos hasta 60 segundos, luego 1 crédito por segundo; las asignaciones del plan no cubren música. Para describir una pista, pon la descripción en prompt y omite style. Enviar style hace que el proveedor trate prompt como la letra de la canción, así que cuando lo uses, no envíes también lyrics.

Audio

Herramienta	Argumentos	Resultado
`list_voices`	ninguno	`default_model`, `characters_per_credit` (20), `minimum_credits` (1), y `voices` (`id`, `name`, `gender`, `language`, `languages`, `accent`, `use_case`, `description`, `preview_url`, `recommended_model`)
`generate_speech`	`text`, `voice_id`; opcional `model_id` (por defecto, el `recommended_model` de la voz), `speed` (0.25–4), `stability` (0–1), `similarity_boost` (0–1), `idempotency_key`	`task_id`, `status`, `cost_credits`; normalmente ya `output_urls`
`generate_sound_effect`	`prompt`; opcional `duration_seconds` (0.5–22), `prompt_influence` (0–1), `idempotency_key`	`task_id`, `status`, `cost_credits`; normalmente ya `output_urls`

El habla cuesta ceil(characters / 20) créditos, al menos 1. Un efecto de sonido cuesta 5 créditos.

Se aplican las mismas reglas de validación de modelos, precios y reembolsos que la API v1.

Flujo de trabajo para agentes

Elige un modelo. Llama a la herramienta list_* correspondiente y luego a get_video_model o get_image_model para el modelo que elijas. Lee sus modos, valores permitidos, defaults y max_prompt_length.
Confirma el costo. Informa al usuario qué modelo usarás y cuántos créditos cuesta, calculado a partir de los precios del catálogo y los valores que enviarás (o el defaults del modo). Espera su confirmación antes de cualquier llamada a generate_*. get_credits muestra el saldo.
Crea una vez. Llama a la herramienta generate_* con un nuevo idempotency_key, por ejemplo un UUID que generes para esta solicitud.
Consulta. Si status es pending o processing, llama a wait_for_task con el task_id y vuelve a llamarlo mientras el resultado tenga un poll_hint. El video puede tardar varios minutos. El servidor no tiene tiempo de espera para tareas y una tarea nunca se pierde: establece tu propio plazo y reanuda más tarde con get_task. La música, el habla y los efectos de sonido suelen terminar en la llamada de creación.
Devuelve el resultado. En success, entrega al usuario output_urls. En failed o canceled, informa error_message; los créditos se reembolsan automáticamente.

Reintentos idempotentes

Cada herramienta generate_* acepta idempotency_key (1–200 caracteres ASCII visibles, sin espacios). Si una llamada expira o se cae la conexión, vuelve a llamar a la herramienta con la misma clave: ViewMax devuelve la tarea que creó la primera llamada, con su cost_credits original, y no cobra de nuevo. Los argumentos no se comparan, así que usa una clave nueva para cada solicitud nueva. Sin clave, cada llamada crea y cobra una tarea nueva. Las claves MCP son independientes de los valores Idempotency-Key de REST.

Errores y recuperación

Una llamada a herramienta fallida tiene isError: true y un bloque de texto que contiene JSON:

{
  "error": "minimax-h3 prompt must be 7000 characters or fewer, got 7412",
  "error_type": "invalid_request",
  "hint": "Fix the arguments using this message, then call the tool again. Re-read the model with get_video_model or get_image_model before repeating an unsupported model or option."
}

error_type usa los mismos valores que el error.type de REST, y hint indica qué hacer a continuación. task_id se añade cuando la llamada creó una tarea antes de fallar.

`error_type`	Causas típicas	Qué hacer
`unauthorized`	Sin token OAuth o clave de API en la conexión	Conéctate con OAuth, o envía `Authorization: Bearer sk-...` con una clave de Configuración → Claves de API
`invalid_request`	Modelo desconocido o sin conexión (`video model temporarily unavailable: ...`), modo u opción no admitidos, prompt más largo que `max_prompt_length`, `voice_id` desconocido, modelo deshabilitado (`This capability is unavailable.`)	Corrige los argumentos usando `error`; vuelve a leer `get_video_model` o `get_image_model`. Con `task_id`, el proveedor rechazó la configuración y la tarea fue reembolsada
`content_rejected`	El prompt menciona un uso prohibido (deepfake, intercambio de rostro, suplantación), incluso dentro de una instrucción negativa; o la moderación del proveedor rechazó el prompt o el medio	Cambia el contenido. Reintentar sin cambios falla de nuevo
`insufficient_credits`	El saldo está por debajo del costo; no se creó ninguna tarea	Informa al usuario. No reintentes hasta que se añadan créditos en precios
`not_found`	El `task_id` no existe o pertenece a otra cuenta	Usa un `task_id` devuelto a esta cuenta
`internal_error`	Un fallo del proveedor o del servidor	Sigue `hint`: reintenta una vez cuando la tarea falló y fue reembolsada; cuando el proveedor pueda aún terminar, llama a `wait_for_task` con `task_id` en lugar de crear una tarea nueva

Los argumentos fuera del esquema de entrada de una herramienta, como timeout_seconds: 120, se rechazan antes de que la herramienta se ejecute con un mensaje de Input validation error: ... en texto plano. Consulta errores de API para la clasificación compartida.