ViewMax MCP

MCP remoto para geração de vídeo, imagem, música e fala por IA no Claude, Cursor e ChatGPT.

Ver em viewmax.studioExperimente este MCPPatrocinado

Documentação

Guia de Configuração e Setup do ViewMax MCP

Conecte um cliente MCP ao ViewMax - ferramentas, argumentos, custos de créditos, polling de tarefas, tentativas idempotentes e tratamento de erros para geração de vídeo, imagem, música e áudio.

Procurando uma visão geral do que o servidor pode fazer? Comece pela página principal do ViewMax MCP - este guia cobre setup e configuração em detalhes.

Endpoint e autenticação

O ViewMax expõe um servidor MCP remoto chamado viewmax:

https://viewmax.studio/api/mcp

Ele usa apenas Streamable HTTP: GET retorna 405 e não há endpoint SSE legado.

OAuth (claude.ai e Claude Desktop). Adicione um conector personalizado com a URL acima, clique em Conectar e faça login com sua conta ViewMax. Os clientes descobrem o fluxo por meio de /.well-known/oauth-protected-resource; nenhuma chave de API é necessária.

Chave de API (Claude Code, Cursor, Codex, VS Code, SDKs). Crie uma chave em Configurações → Chaves de API e envie-a em cada requisição:

Authorization: Bearer sk-your-api-key

Sem um cabeçalho Authorization, o servidor ainda responde a initialize, tools/list e às ferramentas 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 e toda ferramenta generate_* retornam um erro unauthorized. Um token bearer que não é nem uma chave de API válida nem um token de acesso OAuth válido recebe HTTP 401 com um desafio OAuth, então um cliente configurado com uma chave revogada pode pedir que você faça login; crie uma nova chave.

Conecte um cliente

Cada trecho aponta para o mesmo endpoint. Mantenha a chave na variável de ambiente VIEWMAX_API_KEY em vez de em um arquivo versionado. Esses trechos seguem o formato de configuração documentado de cada cliente; a sintaxe do cliente muda entre versões, então, se um campo for rejeitado, use o guia MCP do seu cliente com a URL e o cabeçalho acima.

claude.ai e Claude Desktop. Configurações → Conectores → Adicionar conector personalizado. Nomeie como ViewMax, cole https://viewmax.studio/api/mcp, clique em Conectar e faça login.

Claude Code.

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

Para compartilhar o servidor com um projeto, faça commit de .mcp.json. O Claude Code expande ${VIEWMAX_API_KEY} a partir do ambiente de cada desenvolvedor:

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

Cursor. Adicione a ~/.cursor/mcp.json (ou .cursor/mcp.json em um projeto) e recarregue o Cursor:

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

Codex (ChatGPT). O Codex lê a chave da variável de ambiente nomeada:

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

A entrada ~/.codex/config.toml equivalente:

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

VS Code. Adicione .vscode/mcp.json; o VS Code solicita a chave uma vez e a armazena com segurança:

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

Qualquer outro cliente. Agentes que podem editar sua própria configuração MCP podem se conectar. Cole: "Adicione o servidor MCP ViewMax a este cliente: transporte Streamable HTTP, URL https://viewmax.studio/api/mcp, cabeçalho HTTP Authorization: Bearer <my API key>. Em seguida, chame get_credits para verificar a conexão."

list_video_models funciona sem autenticação, então apenas prova que o servidor está acessível; get_credits prova que a conexão está autenticada.

Ferramentas

O servidor gera vídeo, imagem, música e áudio. A geração consome créditos da conta conectada. No Pro/Ultra, imagens principais (GPT Image 2, GPT Image 2.5, Nano Banana 2, Grok Imagine) usam o pool compartilhado diário de uso justo, e o mesmo vale para ViewMax C1 no Ultra; cost_credits é 0 quando o pool cobre uma tarefa.

Todo resultado de ferramenta é um bloco de texto contendo JSON. Ferramentas de catálogo, get_task, wait_for_task e get_credits são marcadas como somente leitura (readOnlyHint), então os clientes podem executá-las sem perguntar. Ferramentas generate_* são marcadas como não somente leitura, não destrutivas, não idempotentes e de mundo aberto.

Tarefas e conta

Ferramenta	Argumentos	Resultado
`get_task`	`task_id`	`task_id`, `status`, `media_type`, `cost_credits`; `output_urls` assim que os resultados existirem (tarefas de vídeo também `video_urls`); `error_code` e `error_message` quando `failed` ou `canceled`
`wait_for_task`	`task_id`, opcional `timeout_seconds` (inteiro 1–50, padrão 45)	Verifica a cada 5 segundos até a tarefa terminar ou o tempo limite passar; retorna os campos `get_task`, além de `poll_hint` enquanto a tarefa ainda está em execução
`get_credits`	nenhum	`remaining_credits`

Vídeo

Ferramenta	Argumentos	Resultado
`list_video_models`	nenhum	`id`, `label`, `vendor` de cada modelo, durações e resoluções por modo, e `credits_label`
`get_video_model`	`model`	Entrada completa do catálogo: durações por modo, resoluções, proporções de aspecto, `audio_toggle`, créditos, `defaults` e `max_prompt_length` quando o modelo tiver um
`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`

Se mode for omitido, será image-to-video quando image_urls estiver definido, video-to-video quando video_urls estiver definido e, caso contrário, text-to-video.
duration, resolution e aspect_ratio omitidos são preenchidos a partir do defaults do modo antes da precificação, então cost_credits corresponde ao que é renderizado.
Envie audio: true apenas quando o audio_toggle do modo for true.
Modelos por segundo (Seedance 2.x, Seedance 2.5, MiniMax H3) precisam de source_video_duration_seconds com video_urls.
URLs de mídia devem ser URLs públicas http(s) que o provedor possa buscar sem autenticação.

Imagem

Ferramenta	Argumentos	Resultado
`list_image_models`	nenhum	`id`, `label`, `vendor` de cada modelo, proporções de aspecto e qualidades por modo, e `credits_label`
`get_image_model`	`model`	Capacidade completa e precificação de créditos para um modelo de imagem
`generate_image`	`model`, `prompt`; opcional `scene` (`text-to-image` ou `image-to-image`), `image_urls`, `aspect_ratio`, `quality`, `idempotency_key`	`task_id`, `status`, `cost_credits`, `poll_hint`

Se scene for omitido, será image-to-image quando image_urls estiver definido. O GPT Image 2.5 rejeita um quality ou tamanho desconhecido; outros modelos substituem um aspect_ratio ou quality desconhecido pelo padrão e cobram esse valor, então envie apenas valores que o modelo liste.

Música

Ferramenta	Argumentos	Resultado
`list_music_models`	nenhum	O modelo de música, seus controles e custo de créditos
`generate_music`	`prompt`; opcional `duration_seconds` (3–300, padrão 60), `instrumental`, `style`, `lyrics`, `idempotency_key`	`task_id`, `status`, `cost_credits`; geralmente já `output_urls`

Música custa 60 créditos até 60 segundos, depois 1 crédito por segundo; as franquias do plano não cobrem música. Para descrever uma faixa, coloque a descrição em prompt e omita style. Enviar style faz o provedor tratar prompt como a letra da música, então, ao usá-lo, não envie também lyrics.

Áudio

Ferramenta	Argumentos	Resultado
`list_voices`	nenhum	`default_model`, `characters_per_credit` (20), `minimum_credits` (1) e `voices` (`id`, `name`, `gender`, `language`, `languages`, `accent`, `use_case`, `description`, `preview_url`, `recommended_model`)
`generate_speech`	`text`, `voice_id`; opcional `model_id` (padrão é o `recommended_model` da voz), `speed` (0,25–4), `stability` (0–1), `similarity_boost` (0–1), `idempotency_key`	`task_id`, `status`, `cost_credits`; geralmente já `output_urls`
`generate_sound_effect`	`prompt`; opcional `duration_seconds` (0,5–22), `prompt_influence` (0–1), `idempotency_key`	`task_id`, `status`, `cost_credits`; geralmente já `output_urls`

Fala custa ceil(characters / 20) créditos, no mínimo 1. Um efeito sonoro custa 5 créditos.

As mesmas regras de validação de modelo, preços e reembolso da API v1 se aplicam.

Fluxo de trabalho para agentes

Escolha um modelo. Chame a ferramenta list_* correspondente e depois get_video_model ou get_image_model para o modelo que você escolher. Leia seus modos, valores permitidos, defaults e max_prompt_length.
Confirme o custo. Informe ao usuário qual modelo você usará e quantos créditos custa, calculado a partir do catálogo de preços e dos valores que você enviará (ou o defaults do modo). Aguarde a confirmação antes de qualquer chamada generate_*. get_credits mostra o saldo.
Crie uma vez. Chame a ferramenta generate_* com um novo idempotency_key, por exemplo um UUID que você gera para esta solicitação.
Consulte. Se status for pending ou processing, chame wait_for_task com o task_id e chame novamente enquanto o resultado tiver um poll_hint. Vídeo pode levar vários minutos. O servidor não tem tempo limite de tarefa e uma tarefa nunca é perdida: defina seu próprio prazo e retome mais tarde com get_task. Música, fala e efeitos sonoros geralmente terminam na chamada de criação.
Retorne o resultado. Em success, dê ao usuário output_urls. Em failed ou canceled, relate error_message; os créditos são reembolsados automaticamente.

Repetições idempotentes

Toda ferramenta generate_* aceita idempotency_key (1–200 caracteres ASCII visíveis, sem espaços). Se uma chamada expirar ou a conexão cair, chame a ferramenta novamente com a mesma chave: o ViewMax retorna a tarefa que a primeira chamada criou, com seu cost_credits original, e não cobra novamente. Os argumentos não são comparados, então use uma nova chave para cada nova solicitação. Sem uma chave, cada chamada cria e cobra uma nova tarefa. As chaves MCP são separadas dos valores Idempotency-Key do REST.

Erros e recuperação

Uma chamada de ferramenta com falha tem isError: true e um bloco de texto contendo 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 os mesmos valores que o error.type do REST, e hint diz o que fazer a seguir. task_id é adicionado quando a chamada criou uma tarefa antes de falhar.

`error_type`	Causas típicas	O que fazer
`unauthorized`	Sem token OAuth ou chave de API na conexão	Conecte com OAuth, ou envie `Authorization: Bearer sk-...` com uma chave de Configurações → Chaves de API
`invalid_request`	Modelo desconhecido ou offline (`video model temporarily unavailable: ...`), modo ou opção não suportados, prompt maior que `max_prompt_length`, `voice_id` desconhecido, modelo desabilitado (`This capability is unavailable.`)	Corrija os argumentos usando `error`; releia `get_video_model` ou `get_image_model`. Com `task_id`, o provedor rejeitou as configurações e a tarefa foi reembolsada
`content_rejected`	O prompt menciona um uso proibido (deepfake, troca de rosto, personificação), mesmo dentro de uma instrução negativa; ou a moderação do provedor recusou o prompt ou a mídia	Mude o conteúdo. Repetir sem alterações falha novamente
`insufficient_credits`	O saldo está abaixo do custo; nenhuma tarefa foi criada	Informe o usuário. Não repita até que créditos sejam adicionados em preços
`not_found`	O `task_id` não existe ou pertence a outra conta	Use um `task_id` retornado para esta conta
`internal_error`	Uma falha do provedor ou do servidor	Siga `hint`: repita uma vez quando a tarefa falhou e foi reembolsada; quando o provedor ainda pode terminar, chame `wait_for_task` com `task_id` em vez de criar uma nova tarefa

Argumentos fora do esquema de entrada de uma ferramenta, como timeout_seconds: 120, são rejeitados antes da execução da ferramenta com uma mensagem Input validation error: ... em texto simples. Veja erros de API para a classificação compartilhada.