Recursos avançados

Servidor MCP: Claude Code, Cursor e VS Code no Geramaker

Resposta rápida: O servidor MCP do Geramaker deixa o Claude Code, o Cursor, o VS Code e outros clientes MCP gerarem vídeo, imagem, narração e música e rodarem templates com os créditos da sua conta. É um servidor remoto (nada para instalar) em https://www.geramaker.com.br/api/mcp, acessado com uma chave pessoal criada em Configurações. Está em beta: entra quem está na lista de espera.

MCP (Model Context Protocol) é o padrão aberto que ensina assistentes de IA a usar ferramentas externas. Com o servidor do Geramaker conectado, você pede em português no chat ("transforme este print em render") e o assistente chama as ferramentas, mostra o preço e entrega o arquivo.

1. Entre na lista de espera em geramaker.com.br/mcp. Quando o seu acesso for liberado, aparece a área "Chaves de API (MCP)" em Configurações → Conta e segurança.
2. Crie uma chave. Ela começa com gm_ e aparece uma vez só: copie na hora. Escolha se ela pode gerar (gasta créditos) ou só ler, e um teto de créditos por dia, se quiser.
3. Cole a configuração no seu cliente MCP (abaixo) e reinicie o cliente.
4. Peça no chat. Toda ferramenta que gasta créditos devolve primeiro a cotação; a geração só começa depois que você confirma.

claude mcp add --transport http geramaker \
  https://www.geramaker.com.br/api/mcp \
  --header "Authorization: Bearer gm_SUA_CHAVE"

# ou, no .mcp.json do projeto:
{
  "mcpServers": {
"geramaker": {
  "type": "http",
  "url": "https://www.geramaker.com.br/api/mcp",
  "headers": {
    "Authorization": "Bearer ${GERAMAKER_API_KEY}"
  }
}
  }
}

{
  "mcpServers": {
"geramaker": {
  "url": "https://www.geramaker.com.br/api/mcp",
  "headers": {
    "Authorization": "Bearer ${env:GERAMAKER_API_KEY}"
  }
}
  }
}

{
  "inputs": [
{ "type": "promptString", "id": "geramaker-key", "description": "Chave de API do Geramaker", "password": true }
  ],
  "servers": {
"geramaker": {
  "type": "http",
  "url": "https://www.geramaker.com.br/api/mcp",
  "headers": {
    "Authorization": "Bearer ${input:geramaker-key}"
  }
}
  }
}

Os arquivos de configuração leem a chave da variável GERAMAKER_API_KEY: exporte no seu shell (export GERAMAKER_API_KEY=...) e não comite a chave, porque .mcp.json e .cursor/mcp.json costumam ir para o repositório. O VS Code pede a chave na primeira conexão e guarda em lugar seguro. O comando claude mcp add grava a chave em ~/.claude.json, fora do projeto, mas fica no histórico do terminal.

Ferramentas que não gastam créditos: estimar_custo (preço de um modelo ou template), listar_modelos, listar_templates, descrever_template (campos e etapas), status_geracao (acompanha e entrega o arquivo; aguardar_segundos segura a resposta por até 50 segundos enquanto a geração anda), enviar_arquivo (guarda uma foto, print ou áudio na sua Biblioteca e devolve o media_id), minha_biblioteca e meu_saldo.

Como o seu arquivo entra (foto, print, render): pelo site, entrando com a mesma conta da chave. Abra um template, toque na caixa da foto e escolha Suas fotos (nos de arquitetura; nos demais, Enviar foto). O arquivo sobe na hora, sem gerar nada nem gastar créditos, e fica na Biblioteca, em Uploads. Depois o assistente chama minha_biblioteca para pegar o media_id e confirma com você qual é o arquivo. Ou por um link público, com enviar_arquivo e url (até 25 MB). enviar_arquivo também aceita base64 até 5 MB, mas isso serve para arquivos pequenos: uma foto ou um print de alguns MB não cabe no argumento de uma ferramenta. Os atalhos de arquitetura (render-do-print, tour-do-ambiente, apresentacao-do-projeto) funcionam sem o media_id: o assistente lista os arquivos mais novos da Biblioteca e confirma com você qual usar.

Ferramentas que gastam créditos: gerar_imagem, gerar_video, gerar_narracao (vozes prontas, sem clonagem), gerar_musica e rodar_template. Chamadas sem creditos_confirmados só cotam e não reservam nada. Com o valor da cotação, os créditos são reservados e volta um run_id. Se o preço mudou entre a cotação e a confirmação, a resposta é cotacao_desatualizada com o valor novo, e nada é cobrado. Para repetir com segurança depois de uma queda de rede, mande chave_idempotencia: a mesma chave em até 15 minutos devolve o mesmo run_id, sem cobrar de novo. Sem chave_idempotencia, repetir a chamada gera e cobra de novo.

Os templates de arquitetura funcionam pelo MCP: arq-render-do-print (print do SketchUp, do Revit ou croqui vira render), arq-tour-do-ambiente, arq-dia-vira-noite, arq-apresentacao-projeto e os demais. O recurso geramaker://skills/arquitetos explica ao assistente como encadear print, render, vídeo e apresentação.

O arquivo pronto chega com um link que vale 24 horas e fica na sua Biblioteca. Conta que ainda não comprou créditos recebe o arquivo com a marca d'água do Geramaker, como no site.

Erros voltam com um código e com retryable dizendo se vale repetir: cotacao_desatualizada, creditos_insuficientes (vem com comprar_em, o link https://www.geramaker.com.br/planos, e, quando dá para calcular, creditos_faltantes e reais_faltantes; a compra é no site, o MCP não vende), nao_encontrado, validacao (com a lista do que faltou), moderacao, limite (com tente_em_segundos), teto_diario, escopo_insuficiente, manutencao e interno (com request_id para o suporte).

Limites por chave: 120 chamadas por minuto, 60 gerações por hora, 60 envios de arquivo por hora e o teto diário que você escolheu. Revogar a chave em Configurações corta o acesso em até um minuto.