Passo a passo: configure o servidor MCP para geração de imagens
Etapa 1: Obtenha sua chave de API e proteja-a
Obtenha uma chave de API do Freebeat pelo site do Freebeat. Guarde-a em um local seguro enquanto prepara a configuração do cliente; o servidor a lê da variável de ambiente FREEBEAT_API_KEY.
O que indica que deu certo: Você tem uma chave válida pronta para adicionar ao cliente MCP, sem colocá-la em um arquivo ou mensagem pública.
Erro comum a evitar: Manter o texto de exemplo your-api-key-here inalterado na configuração final.
Etapa 2: Confirme que o cliente consegue executar o pacote
Use um cliente MCP compatível, como o Claude Desktop ou o Cursor. Verifique se Node.js/npm e o acesso à rede estão disponíveis no ambiente que inicia o cliente, pois o comando documentado executa o pacote por meio de npx.
O que indica que deu certo: O ambiente do cliente consegue localizar o comando npx e acessar os serviços online.
Erro comum a evitar: Testar o npm em um ambiente diferente daquele usado pelo cliente para computador.
Etapa 3: Adicione a configuração do servidor
Na área de configuração MCP do seu cliente, adicione um servidor chamado freebeat. A estrutura da configuração documentada é a mesma para o Claude Desktop e o Cursor:
O que indica que deu certo: A configuração é um JSON válido e inclui o comando, os argumentos e a variável de ambiente.
Erro comum a evitar: Adicionar vírgulas no final ou alterar o nome do pacote, o que pode impedir o cliente de iniciar o servidor.
Etapa 4: Defina a variável de ambiente
Substitua o valor de exemplo pela sua chave de API na configuração local do cliente. Mantenha o nome da variável exatamente como documentado: FREEBEAT_API_KEY.
O que indica que deu certo: A chave está disponível no ambiente do servidor e a entrada do servidor continua sendo um JSON válido.
Erro comum a evitar: Usar um nome de variável diferente, adicionar espaços à chave ou expor o segredo em registros compartilhados.
Etapa 5: Salve a configuração e reconecte-se
Salve as configurações do MCP. Reinicie ou atualize o cliente se ele não recarregar automaticamente a entrada do servidor e, em seguida, verifique as ferramentas MCP do Freebeat disponíveis no cliente.
O que indica que deu certo: O cliente reconhece o servidor do Freebeat e disponibiliza as ferramentas disponíveis.
Erro comum a evitar: Tentar solucionar problemas das chamadas de geração antes de confirmar que o servidor está conectado e que suas ferramentas estão visíveis.
Etapa 6: Descubra um modelo de imagem e consulte suas orientações
Chame list_models com type: "image". Escolha um dos modelos retornados e, se for útil, chame get_model_help com o model_id numérico ou a chave de modelo da API para consultar exemplos e restrições. Esta etapa de descoberta de modelos de imagem evita que você tenha de adivinhar os identificadores dos modelos.
O que indica que deu certo: Você tem um modelo de imagem válido e conhece os requisitos específicos do modelo relevantes para sua solicitação.
Erro comum a evitar: Codificar permanentemente um nome de modelo presumido em vez de escolher um modelo da resposta atual.
Etapa 7: Gere uma imagem e consulte o lote
Chame generate_image com o modelo selecionado e um prompt descritivo. Após a remoção de espaços em branco no início e no fim, o prompt deve ter de 1 a 2.000 caracteres. Os campos opcionais incluem size, resolution, quality e count; o valor padrão de count é 1. Para GPT-Image 2 (ID do modelo 108), os valores padrão de quality e resolution, se não forem informados, são medium e 1024x1024. Se resolution não for informado e size for fornecido, o servidor também envia size como resolution para manter a compatibilidade.
O que indica que deu certo: A solicitação retorna um ID de lote que você pode usar para verificar o status da tarefa e obter as URLs das imagens quando ela for concluída.
Erro comum a evitar: Enviar um prompt vazio, longo demais ou composto apenas por espaços em branco; siga as restrições do prompt e consulte a ajuda do modelo antes de tentar novamente.
Etapa 8: Verifique o status e examine o resultado
Consulte get_task_status usando o batch_id retornado como task_id. Para um lote de imagens do Open RPC, você também pode passar serial_no para verificar um item específico. Procure um status final, como completed ou failed; os lotes de imagens concluídos incluem URLs de imagem na resposta de status, com campos como image_url ou edit_images.
O que indica que deu certo: A tarefa chega a um status final e, quando concluída, a resposta contém o resultado da imagem.
Erro comum a evitar: Chamar get_task_result para um lote de imagens do Open RPC; os resultados das imagens concluídas são retornados diretamente por get_task_status.