Referência do MCP

Ferramentas de leitura

consultar_saldo: saldo e plano da conta. listar_ferramentas: catálogo atual, opções, estimativas e dados de narração. listar_geracoes: histórico paginado da própria conta.

consultar_geracao: status e resultado por id UUID. baixar_midia: URL temporária de download por assetId UUID da própria conta. Essas ferramentas não iniciam uma geração.

Ferramentas de geração

gerar_midia cria imagem, vídeo ou música. gerar_narracao cria áudio a partir de texto. Elas só aparecem em conexões com a permissão generate. Os schemas retornados por tools/list são o contrato executável.

gerar_midia exige task, description, model, quality, isPrivate, idempotencyKey UUID, maxCredits e confirmCreditSpend:true. Formato, duração e referências dependem da tarefa. Referências usam assetId de mídias da própria conta; envie novos arquivos pela interface do app.

Para música, use variations=2. Para narração, consulte voz e perfil no catálogo antes de montar a chamada. Não invente identificadores de modelo, voz ou parâmetros.

Custo e idempotência

Antes de gerar, consulte saldo e catálogo, apresente os parâmetros e o custo e obtenha autorização. maxCredits é um teto por solicitação, não um orçamento total da conexão. O servidor verifica o limite antes da reserva.

Crie uma UUID para cada intenção nova. Se houver timeout, preserve a mesma idempotencyKey e o mesmo payload ao repetir. Uma chave diferente pode iniciar outra geração. Não use uma nova chave apenas para contornar um erro.

1. listar_ferramentas + consultar_saldo
2. Apresentar parâmetros, custo e privacidade
3. Obter autorização e teto maxCredits
4. gerar_midia ou gerar_narracao (UUID única)
5. consultar_geracao até estado final
6. baixar_midia para o asset concluído

Diagnóstico de conexão

401: confira expiração ou revogação e reconecte se necessário. 403: confira a permissão autorizada. 429: aguarde antes de repetir; não abra várias conexões para contornar o limite.

Erros de validação exigem revisão do schema e do catálogo. Falta de saldo ou teto insuficiente não se resolve repetindo a chamada. Em falhas de rede, consulte o histórico antes de iniciar uma nova intenção.

Transporte e descoberta

Endpoint POST /api/mcp, Streamable HTTP sem sessão persistente no servidor. A resposta sem autenticação anuncia resource_metadata no desafio WWW-Authenticate.

Metadados: /.well-known/oauth-protected-resource/api/mcp e /.well-known/oauth-authorization-server. Há registro dinâmico de clientes públicos, authorization code com PKCE S256, renovação rotativa e revogação. O recurso aglabs://guia e o prompt iniciar_criacao orientam o uso.

Proporção e referências no MCP

aspectRatio recebe uma proporção aceita pelo modelo, como 1:1, 4:5 ou 16:9 quando disponíveis. Não confunda proporção de geração com o recorte aplicado por uma página: um arquivo vertical pode parecer quadrado no preview e continuar vertical no download.

references recebe uma lista de objetos com assetId UUID de uma mídia da própria conta e role opcional. Não coloque o caminho local do computador ou uma URL arbitrária no lugar do assetId. Envie novos arquivos pelo app e consulte as mídias da conta para identificar o asset correto.

maxCredits é um teto para uma solicitação. Para um lote de várias artes, combine também um orçamento total e controle o saldo entre chamadas. Reutilize a mesma idempotencyKey somente para repetir a mesma intenção e o mesmo conteúdo após uma falha de rede.