Paso a paso: configura el servidor MCP de generación de imágenes
Paso 1: Obtén tu clave de API y protégela
Obtén una clave de API de Freebeat a través del sitio de Freebeat. Guárdala en un lugar seguro mientras preparas la configuración del cliente; el servidor la lee de la variable de entorno FREEBEAT_API_KEY.
Señal de que todo está bien: Tienes una clave válida lista para añadir al cliente MCP, sin incluirla en un archivo o mensaje público.
Error frecuente que debes evitar: Dejar el texto de ejemplo your-api-key-here sin cambios en la configuración final.
Paso 2: Confirma que el cliente puede ejecutar el paquete
Usa un cliente MCP compatible, como Claude Desktop o Cursor. Asegúrate de que Node.js/npm y el acceso a la red estén disponibles en el entorno que inicia el cliente, ya que el comando documentado ejecuta el paquete mediante npx.
Señal de que todo está bien: El entorno del cliente puede encontrar el comando npx y acceder a los servicios en línea.
Error frecuente que debes evitar: Probar npm en un entorno distinto al que utiliza el cliente de escritorio.
Paso 3: Añade la configuración del servidor
En el área de configuración MCP de tu cliente, añade un servidor llamado freebeat. La estructura de configuración documentada es la misma para Claude Desktop y Cursor:
Señal de que todo está bien: La configuración es JSON válido e incluye el comando, los argumentos y la variable de entorno.
Error frecuente que debes evitar: Añadir comas finales o cambiar el nombre del paquete, lo que puede impedir que el cliente inicie el servidor.
Paso 4: Configura la variable de entorno
Sustituye el valor de marcador de posición por tu clave de API en la configuración local del cliente. Mantén exactamente el nombre de la variable documentado: FREEBEAT_API_KEY.
Señal de que todo está bien: La clave está presente en el entorno del servidor y la entrada del servidor sigue siendo JSON válido.
Error frecuente que debes evitar: Usar otro nombre de variable, añadir espacios a la clave o exponer el secreto en registros compartidos.
Paso 5: Guarda la configuración y vuelve a conectarte
Guarda la configuración de MCP. Reinicia o actualiza el cliente si no vuelve a cargar automáticamente la entrada del servidor y, después, comprueba las herramientas MCP de Freebeat disponibles en el cliente.
Señal de que todo está bien: El cliente reconoce el servidor de Freebeat y muestra las herramientas disponibles.
Error frecuente que debes evitar: Solucionar problemas de las llamadas de generación antes de confirmar que el servidor está conectado y que sus herramientas están visibles.
Paso 6: Busca un modelo de imagen y consulta sus indicaciones
Llama a list_models con type: "image". Elige uno de los modelos devueltos y, si resulta útil, llama a get_model_help con su model_id numérico o la clave del modelo en la API para revisar ejemplos y limitaciones. Este paso de búsqueda de modelos de imagen evita tener que adivinar los identificadores de los modelos.
Señal de que todo está bien: Tienes un modelo de imagen válido y conoces los requisitos específicos del modelo que afectan a tu solicitud.
Error frecuente que debes evitar: Codificar de forma fija un nombre de modelo supuesto en vez de elegir uno de la respuesta actual.
Paso 7: Genera una imagen y consulta el estado del lote
Llama a generate_image con el modelo seleccionado y una instrucción descriptiva. La instrucción debe tener entre 1 y 2.000 caracteres una vez eliminados los espacios sobrantes. Los campos opcionales incluyen size, resolution, quality y count; el valor predeterminado de count es 1. Para GPT-Image 2 (ID de modelo 108), si no se especifican la calidad ni la resolución, los valores predeterminados son medium y 1024x1024. Si se omite la resolución y se especifica el tamaño, el servidor también envía el tamaño como resolución por motivos de compatibilidad.
Señal de que todo está bien: La solicitud devuelve un ID de lote que puedes usar para consultar el estado de la tarea y obtener las URL de las imágenes cuando termine.
Error frecuente que debes evitar: Enviar una instrucción vacía, demasiado larga o compuesta solo por espacios; sigue las limitaciones de las instrucciones y revisa la ayuda del modelo antes de volver a intentarlo.
Paso 8: Consulta el estado y revisa el resultado
Consulta get_task_status con el batch_id devuelto, proporcionándolo como task_id. En un lote de imágenes de Open RPC, también puedes pasar serial_no para comprobar un elemento concreto. Busca un estado final, como completed o failed; los lotes de imágenes completados incluyen las URL de las imágenes en la respuesta de estado, con campos como image_url o edit_images.
Señal de que todo está bien: La tarea alcanza un estado final y, si se completa, la respuesta contiene el resultado de la imagen.
Error frecuente que debes evitar: Llamar a get_task_result para un lote de imágenes de Open RPC; los resultados de imagen completados se devuelven directamente mediante get_task_status.