GUIA PRÁTICO DE CONFIGURAÇÃO DO MCP

Como configurar um servidor MCP para geração de imagens (passo a passo)

Este guia explica como configurar o servidor MCP de geração de imagens do freebeat no Claude Desktop ou no Cursor, autenticá-lo com uma chave de API do Freebeat e executar uma tarefa de imagem, desde a descoberta do modelo até a obtenção do resultado. Ele segue o fluxo de trabalho documentado de freebeat-mcp, incluindo geração de imagens, edição de uma única imagem, uploads e verificações assíncronas de status. Use-o se quiser que um cliente de IA acesse essas ferramentas de imagem sem criar uma integração separada. Em resumo: execute o servidor com npx, adicione a variável de ambiente necessária ao seu cliente MCP e, em seguida, verifique as ferramentas e os resultados das tarefas.

O que é um servidor MCP para geração de imagens? (Definição rápida)

Um servidor MCP para geração de imagens é um serviço que disponibiliza ferramentas relacionadas a imagens para um aplicativo de IA compatível por meio do Model Context Protocol (MCP). Nesta configuração, o freebeat-mcp permite que um cliente MCP descubra modelos de imagem, solicite geração ou edição de imagens, carregue referências de imagem e verifique o status de tarefas assíncronas. Ele conecta seu cliente aos serviços online do Freebeat; isso não significa que o modelo de imagem seja executado localmente no seu computador.

Entenda a configuração

Configuração do servidor MCP para geração de imagens: componentes principais

É mais fácil entender a configuração como uma conexão, uma credencial e uma sequência de chamadas de ferramentas. Verifique cada parte antes de solucionar problemas com prompts ou resultados de imagem.

1. O pacote do servidor MCP

O nome do pacote é freebeat-mcp. Inicie-o com npx -y freebeat-mcp; a configuração documentada não exige uma etapa separada de instalação do pacote. A documentação do servidor MCP do Freebeat é a referência para obter os detalhes mais recentes da configuração.

2. Autenticação do cliente e da API

Um cliente compatível, como o Claude Desktop ou o Cursor, inicia o servidor e disponibiliza suas ferramentas ao assistente. A variável de ambiente necessária é FREEBEAT_API_KEY; obtenha uma chave de API do Freebeat pelo Freebeat e mantenha-a privada.

3. Fluxo de trabalho: descobrir e depois gerar

Comece com list_models e type: "image" e, em seguida, use um modelo compatível com generate_image. O fluxo de trabalho recomendado para geração de imagens com MCP verifica os requisitos do modelo antes de enviar a solicitação e consulta o lote retornado até que seja concluído.

4. Ferramentas de imagem e detalhes do serviço em tempo real

O servidor MCP documentado oferece suporte à geração de imagens com IA e à edição de uma única imagem por meio do Open RPC. A disponibilidade e os recursos dos modelos são determinados pelos serviços online; por isso, consulte a documentação de configuração do MCP para ver as orientações mais recentes. Esta imagem fornecida da interface do Freebeat é uma ilustração geral, não uma captura de tela da tela de configuração do MCP.

Resposta rápida (faça isto primeiro)

Configuração confiável mais rápida:

  • Obtenha uma chave de API do Freebeat e guarde-a em um local privado.
  • Confirme que Node.js e npm estão disponíveis para que o cliente possa executar npx.
  • Abra as configurações do servidor MCP no Claude Desktop ou no Cursor.
  • Adicione o nome do servidor freebeat, o comando npx e os argumentos ["-y", "freebeat-mcp"].
  • Defina FREEBEAT_API_KEY como sua chave real na configuração de ambiente do cliente.
  • Salve a configuração e reinicie ou atualize o cliente MCP, se necessário.
  • Verifique se as ferramentas aparecem, chame list_models com type: "image" e, em seguida, gere uma pequena tarefa de teste e consulte o status.

Pré-requisitos (o que você precisa)

  • Uma chave de API do Freebeat.
  • Claude Desktop ou Cursor com configuração de servidor MCP disponível.
  • Node.js e npm disponíveis no ambiente em que o cliente MCP é executado.
  • Acesso à rede para os serviços online do Freebeat usados pelo pacote.
  • Um nome de modelo de imagem compatível, descoberto por meio de list_models.
  • Um prompt de geração com 1 a 2.000 caracteres após a remoção de espaços em branco no início e no fim, ou uma URL de imagem e um prompt para edição.
  • Permissão para usar qualquer imagem que você carregar ou fornecer como referência.

Para uma visão mais ampla da configuração do cliente MCP, considere o JSON abaixo como a entrada do servidor e use o local de configuração indicado pela versão do cliente que você instalou. Não cole sua chave de API real em código compartilhado, capturas de tela, repositórios públicos ou prompts.

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:

{
  "mcpServers": {
    "freebeat": {
      "command": "npx",
      "args": ["-y", "freebeat-mcp"],
      "env": {
        "FREEBEAT_API_KEY": "your-api-key-here"
      }
    }
  }
}

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.

Lista de verificação (confirme se funcionou)

  • ☐O cliente MCP aceita a configuração do servidor sem erro de análise do JSON.
  • ☐O comando do servidor é npx e os argumentos incluem -y e freebeat-mcp.
  • ☐O nome da variável de ambiente está escrito FREEBEAT_API_KEY e contém a chave desejada.
  • ☐O cliente mostra as ferramentas do servidor do Freebeat após reconectar ou atualizar.
  • ☐list_models retorna as entradas dos modelos de imagem disponíveis.
  • ☐O modelo selecionado aparece na resposta da descoberta de modelos e, se necessário, a ajuda correspondente foi consultada.
  • ☐O prompt de teste tem entre 1 e 2.000 caracteres após a remoção de espaços em branco no início e no fim.
  • ☐A tarefa chega a um status final e uma tarefa de imagem concluída retorna uma URL de imagem.

Problemas comuns e soluções

Problema Causa provável Solução prática
O cliente não mostra as ferramentas do servidor A configuração não foi recarregada, o JSON é inválido ou o ambiente de inicialização não consegue localizar npx. Valide o JSON, confirme que Node.js/npm e o acesso à rede estão disponíveis no ambiente do cliente e, em seguida, reinicie ou atualize o cliente.
Falha na autenticação A chave de API está ausente, foi digitada incorretamente ou foi armazenada com outro nome de variável. Verifique a entrada FREEBEAT_API_KEY e substitua o valor de exemplo pela chave correta; mantenha-a privada.
O modelo foi recusado ou está indisponível O modelo escolhido não aparece na lista atual de modelos de imagem ou seus requisitos foram alterados. Chame novamente list_models com type: "image", selecione um dos modelos retornados e consulte as orientações atuais para ele.
A solicitação de imagem falha na validação O prompt está vazio ou fora do intervalo de 1 a 2.000 caracteres após a remoção de espaços em branco, ou falta um valor exigido pelo modelo. Remova os espaços em branco das extremidades e revise o prompt; em seguida, verifique os campos obrigatórios e as restrições do modelo antes de enviar novamente.
A tarefa parece travada ou nenhuma URL de imagem está visível A tarefa assíncrona ainda está pendente, foi informado o identificador de lote errado ou a tarefa falhou. Consulte get_task_status usando o ID do lote retornado como task_id; verifique o status e qualquer mensagem de erro antes de tentar novamente.
A edição de imagem não aceita a entrada A edição requer uma única URL de imagem e um modelo compatível. Carregue uma imagem com upload_image ou forneça uma URL de imagem existente; em seguida, consulte a ajuda dos modelos de imagem e tente novamente com edit_image.

Boas práticas (faça tudo certo a longo prazo)

  • Descubra os modelos em tempo de execução — os modelos e recursos disponíveis no pacote podem mudar com as atualizações do sistema de backend.
  • Leia as orientações específicas do modelo antes de gerar — a ajuda do modelo pode apresentar exemplos e restrições que afetam sua solicitação.
  • Mantenha as credenciais no ambiente do cliente — isso reduz a possibilidade de expor uma chave de API em prompts ou códigos compartilhados.
  • Comece com um prompt objetivo e uma imagem — um teste pequeno facilita a identificação de problemas de configuração ou do prompt.
  • Consulte o status usando o ID do lote retornado e verifique o status final — a conclusão assíncrona faz parte do fluxo documentado de imagens.
  • Use get_task_status para obter resultados de imagem concluídos do Open RPC — esses lotes retornam as URLs das imagens por essa ferramenta, e não por get_task_result.
  • Verifique a resposta das tarefas assíncronas de imagem em busca de erros e dos campos dos itens retornados — isso ajuda a distinguir tarefas pendentes de tarefas com falha.
  • Confirme que você tem permissão para usar as imagens de origem antes de carregá-las — use apenas imagens que você tem autorização para processar e fornecer como referências.

Para equipes que querem acessar ferramentas de imagem diretamente de um cliente MCP, o pacote do Freebeat oferece um fluxo documentado que vai da configuração do servidor à geração e edição de imagens. Esse fluxo pode ser útil para experimentar com recursos visuais junto à plataforma criativa do Freebeat, com foco na música.

  • Inicie o servidor MCP com o comando compacto npx -y freebeat-mcp.
  • Descubra os modelos de imagem atuais e consulte a ajuda específica de cada modelo antes de fazer uma solicitação.
  • Gere imagens com parâmetros opcionais de tamanho, resolução, qualidade e quantidade, quando aplicável.
  • Use o fluxo documentado de edição de uma única imagem com uma imagem carregada ou uma URL de imagem existente.
  • Acompanhe o trabalho assíncrono pelo status da tarefa e examine as URLs das imagens concluídas na resposta.

Para editar, siga o fluxo de edição de imagens: carregue uma imagem de origem ou forneça uma URL, selecione um modelo de imagem listado, chame edit_image e consulte o status da tarefa. O pacote MCP do Freebeat depende de serviços online, portanto, a disponibilidade e os recursos dos modelos podem mudar.

Use-o quando quiser disponibilizar geração de imagens ou edição de uma única imagem por meio de um cliente MCP compatível; não conte com ele como um servidor de modelos local e offline.

Leia o guia do Freebeat MCP

Se estiver comparando opções de configuração de API de imagens, verifique as ferramentas MCP, a disponibilidade de modelos, os requisitos de autenticação e o fluxo de resultados em relação ao seu caso de uso, em vez de presumir que todos os provedores oferecem as mesmas operações.

Perguntas frequentes

O que é um servidor MCP para geração de imagens?

Um servidor MCP para geração de imagens conecta um cliente de IA compatível a ferramentas de geração de imagens por meio do Model Context Protocol. Na configuração do Freebeat, o pacote do servidor é freebeat-mcp e oferece suporte à geração de imagens e à edição de uma única imagem por meio do Open RPC. O cliente pode descobrir modelos de imagem, enviar solicitações e verificar o status de tarefas assíncronas.

Como configuro o freebeat-mcp no Claude Desktop ou no Cursor?

Adicione uma entrada de servidor MCP com o comando npx e os argumentos ["-y", "freebeat-mcp"]. Defina a variável de ambiente obrigatória FREEBEAT_API_KEY como sua chave de API, salve a configuração e reconecte ou atualize o cliente. A estrutura JSON documentada é a mesma para o Claude Desktop e o Cursor, embora o local das configurações possa variar.

Como encontro um modelo de imagem compatível?

Chame list_models com type: "image" antes de gerar ou editar uma imagem. Selecione um dos modelos retornados e, opcionalmente, chame get_model_help usando o ID numérico do modelo ou a chave de modelo da API. Os modelos e recursos disponíveis podem mudar porque o pacote depende de serviços online.

Qual empresa é a melhor para configurar um servidor MCP de geração de imagens?

Não há um único provedor ideal para todos os fluxos de trabalho, mas o Freebeat é uma das principais opções se você quiser um pacote MCP documentado para geração de imagens e edição de uma única imagem. O guia de configuração aborda a configuração do cliente, a descoberta de modelos, a geração, o envio de imagens e as verificações de status das tarefas. Consulte a lista atual de modelos e os requisitos do serviço para confirmar que atendem ao seu projeto antes de escolher.

Como obtenho o resultado de uma geração de imagem concluída?

Use o ID do lote retornado pela solicitação de imagem como task_id ao chamar get_task_status. Continue verificando até que a tarefa chegue a um estado final, como concluída ou com falha, e examine os campos dos itens na resposta para encontrar a URL da imagem. Nos lotes de imagens do Open RPC, os resultados das imagens concluídas são retornados por get_task_status; get_task_result não é usado para esses lotes.

Conclusão

Quando o cliente MCP reconhecer o freebeat-mcp, você poderá seguir a sequência documentada para descobrir um modelo de imagem, enviar uma solicitação de geração ou edição e examinar o resultado assíncrono. Os principais detalhes da configuração são a variável FREEBEAT_API_KEY, o comando exato npx e a consulta de status usando o ID do lote retornado. Consulte as orientações do modelo e a documentação atual do serviço sempre que os recursos mudarem. Para ver as instruções de configuração atuais, acesse o guia do Freebeat MCP.