GUÍA PRÁCTICA DE CONFIGURACIÓN DE MCP

Cómo configurar un servidor MCP de generación de imágenes (paso a paso)

Esta guía explica cómo configurar el servidor MCP de generación de imágenes de freebeat en Claude Desktop o Cursor, autenticarlo con una clave de API de Freebeat y ejecutar una tarea de imagen desde la búsqueda de modelos hasta la obtención del resultado. Sigue el flujo de trabajo documentado de freebeat-mcp, que incluye generación de imágenes, edición de una sola imagen, cargas y comprobaciones de estado asíncronas. Úsala si quieres que un cliente de IA acceda a estas herramientas de imagen sin crear una integración aparte. En resumen: ejecuta el servidor con npx, añade la variable de entorno necesaria a tu cliente MCP y, después, verifica las herramientas y los resultados de las tareas.

¿Qué es un servidor MCP de generación de imágenes? (Definición rápida)

Un servidor MCP de generación de imágenes es un servicio que proporciona herramientas relacionadas con imágenes a una aplicación de IA compatible mediante el Model Context Protocol (MCP). En esta configuración, freebeat-mcp permite que un cliente MCP descubra modelos de imagen, solicite la generación o edición de imágenes, cargue imágenes de referencia y consulte el estado de las tareas asíncronas. Conecta tu cliente a los servicios en línea de Freebeat; no significa que el modelo de imagen se ejecute localmente en tu ordenador.

Entiende la configuración

Configuración del servidor MCP de generación de imágenes: componentes clave

La configuración se entiende mejor como una conexión, una credencial y una secuencia de llamadas a herramientas. Comprueba cada parte antes de solucionar problemas con las instrucciones o los resultados de imagen.

1. El paquete del servidor MCP

El nombre del paquete es freebeat-mcp. Inícialo con npx -y freebeat-mcp; la configuración documentada no requiere un paso de instalación independiente del paquete. La documentación del servidor MCP de Freebeat es la referencia para consultar los detalles de configuración actuales.

2. Autenticación del cliente y de la API

Un cliente compatible, como Claude Desktop o Cursor, inicia el servidor y pone sus herramientas a disposición del asistente. La variable de entorno requerida es FREEBEAT_API_KEY; obtén una clave de API de Freebeat a través de Freebeat y mantenla en privado.

3. Un flujo de trabajo de descubrimiento y generación

Empieza con list_models y type: "image", y luego usa un modelo compatible con generate_image. El flujo de trabajo recomendado para generar imágenes con MCP comprueba los requisitos del modelo antes de enviar la tarea y consulta el lote devuelto hasta que finalice.

4. Herramientas de imagen y detalles del servicio en línea

El servidor MCP documentado admite la generación de imágenes con IA y la edición de una sola imagen mediante Open RPC. Sus servicios en línea determinan la disponibilidad y las capacidades de los modelos, así que consulta la documentación de configuración de MCP para obtener las indicaciones más recientes. Esta imagen de la interfaz de Freebeat es solo una imagen ilustrativa general, no una captura de la pantalla de configuración de MCP.

Respuesta rápida (haz esto primero)

La configuración fiable más rápida:

  • Obtén una clave de API de Freebeat y guárdala en un lugar privado.
  • Confirma que Node.js y npm están disponibles para que el cliente pueda ejecutar npx.
  • Abre la configuración del servidor MCP en Claude Desktop o Cursor.
  • Añade el nombre del servidor freebeat, el comando npx y los argumentos ["-y", "freebeat-mcp"].
  • Asigna tu clave real a FREEBEAT_API_KEY en la configuración del entorno del cliente.
  • Guarda la configuración y reinicia o actualiza el cliente MCP si es necesario.
  • Verifica que aparezcan las herramientas, llama a list_models con type: "image", y luego genera una tarea de prueba pequeña y consulta su estado.

Requisitos previos (lo que necesitas)

  • Una clave de API de Freebeat.
  • Claude Desktop o Cursor con la configuración del servidor MCP disponible.
  • Node.js y npm disponibles en el entorno donde se ejecuta el cliente MCP.
  • Acceso a la red para conectarse a los servicios en línea de Freebeat que utiliza el paquete.
  • El nombre de un modelo de imagen compatible, descubierto mediante list_models.
  • Una instrucción de generación de entre 1 y 2.000 caracteres una vez eliminados los espacios sobrantes, o bien una URL de imagen y una instrucción para editarla.
  • Permiso para usar cualquier imagen que cargues o proporciones como referencia.

Para obtener una visión más amplia de la configuración del cliente MCP, considera el JSON de abajo como la entrada del servidor y usa la ubicación de configuración indicada por la versión del cliente que tengas instalada. No pegues tu clave de API real en código compartido, capturas de pantalla, repositorios públicos ni instrucciones.

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:

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

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.

Lista de verificación (asegúrate de que funcione)

  • ☐El cliente MCP acepta la configuración del servidor sin errores de análisis de JSON.
  • ☐El comando del servidor es npx y sus argumentos incluyen -y y freebeat-mcp.
  • ☐La variable de entorno está escrita FREEBEAT_API_KEY y contiene la clave correcta.
  • ☐El cliente muestra las herramientas del servidor de Freebeat después de volver a conectarse o actualizarse.
  • ☐list_models devuelve los modelos de imagen disponibles.
  • ☐El modelo seleccionado aparece en los resultados de búsqueda y, cuando es necesario, se ha consultado su ayuda.
  • ☐La instrucción de prueba tiene entre 1 y 2.000 caracteres una vez eliminados los espacios sobrantes.
  • ☐La tarea alcanza un estado final y una tarea de imagen completada devuelve una URL de imagen.

Problemas frecuentes y soluciones

Problema Causa probable Solución práctica
El cliente no muestra las herramientas del servidor No se volvió a cargar la configuración, el JSON no es válido o el entorno de inicio no encuentra npx. Valida el JSON, confirma que Node.js/npm y el acceso a la red estén disponibles en el entorno del cliente y, después, reinicia o actualiza el cliente.
Falla la autenticación Falta la clave de API, está mal escrita o se guardó con otro nombre de variable. Comprueba la entrada FREEBEAT_API_KEY y sustituye el marcador de posición por la clave correcta; mantenla en privado.
El modelo se rechaza o no está disponible El modelo elegido no está en la lista actual de modelos de imagen o sus requisitos han cambiado. Vuelve a llamar a list_models con type: "image", selecciona uno de los modelos devueltos y consulta la ayuda actualizada.
La solicitud de imagen no supera la validación La instrucción está en blanco o no tiene entre 1 y 2.000 caracteres después de eliminar los espacios sobrantes, o falta un valor obligatorio del modelo. Elimina los espacios sobrantes y revisa la instrucción; después, verifica los campos obligatorios y las limitaciones del modelo antes de volver a enviar la solicitud.
La tarea parece bloqueada o no se ve ninguna URL de imagen La tarea asíncrona sigue pendiente, se proporcionó un identificador de lote incorrecto o la tarea falló. Consulta get_task_status con el ID de lote devuelto como task_id; revisa el estado y cualquier mensaje de error antes de volver a intentarlo.
La edición de imágenes no acepta la entrada La edición requiere una URL de una sola imagen y un modelo compatible. Carga una imagen con upload_image o proporciona una URL de imagen existente; después, consulta la ayuda del modelo de imagen y vuelve a intentar edit_image.

Buenas prácticas (para hacerlo bien a largo plazo)

  • Descubre los modelos en tiempo de ejecución: los modelos y capacidades disponibles del paquete pueden cambiar con las actualizaciones del backend.
  • Lee las indicaciones específicas del modelo antes de generar: la ayuda del modelo puede incluir ejemplos y limitaciones que afectan a tu solicitud.
  • Guarda las credenciales en el entorno del cliente: así reduces la posibilidad de filtrar una clave de API en instrucciones o código compartidos.
  • Empieza con una instrucción concreta y una imagen: una prueba pequeña facilita la detección de problemas de configuración o de las instrucciones.
  • Consulta el estado con el ID de lote devuelto y revisa el estado final: la finalización asíncrona forma parte del flujo de trabajo de imágenes documentado.
  • Usa get_task_status para consultar resultados de imágenes de Open RPC completadas: estos lotes devuelven las URL de las imágenes por esa vía, no mediante get_task_result.
  • Comprueba la respuesta de las tareas de imagen asíncronas para ver errores y los campos de los elementos devueltos: esto ayuda a distinguir una tarea pendiente de una fallida.
  • Confirma que tienes permiso para usar las imágenes de origen antes de cargarlas: utiliza únicamente imágenes que tengas autorización para procesar y proporcionar como referencia.

Para los equipos que quieren acceder a herramientas de imagen directamente desde un cliente MCP, el paquete de Freebeat ofrece una vía documentada que va desde la configuración del servidor hasta la generación y edición de imágenes. Este flujo de trabajo puede ser útil para experimentar con elementos visuales junto con la plataforma creativa de Freebeat, centrada principalmente en la música.

  • Inicia el servidor MCP con el sencillo comando npx -y freebeat-mcp.
  • Descubre los modelos de imagen actuales y consulta la ayuda específica de cada modelo antes de enviar una solicitud.
  • Genera imágenes con parámetros opcionales de tamaño, resolución, calidad y cantidad cuando corresponda.
  • Usa el flujo documentado para editar una sola imagen, ya sea con una imagen cargada o con una URL de imagen existente.
  • Haz seguimiento de las tareas asíncronas mediante el estado de la tarea y revisa las URL de las imágenes completadas en la respuesta.

Para editar, sigue el flujo de edición de imágenes: carga una imagen de origen o proporciona una URL, selecciona un modelo de imagen de la lista, llama a edit_image y consulta el estado de la tarea. El paquete MCP de Freebeat depende de servicios en línea, por lo que la disponibilidad y las capacidades de los modelos pueden cambiar.

Úsalo si quieres acceder a la generación o edición de una sola imagen mediante un cliente MCP compatible; no lo consideres un servidor de modelos local que funcione sin conexión.

Lee la guía de MCP de Freebeat

Si estás comparando opciones para configurar una API de imágenes, verifica que las herramientas MCP, la disponibilidad de modelos, los requisitos de autenticación y el flujo de resultados se ajusten a tu caso de uso, en vez de dar por sentado que todos los proveedores ofrecen las mismas operaciones.

Preguntas frecuentes

¿Qué es un servidor MCP de generación de imágenes?

Un servidor MCP de generación de imágenes conecta un cliente de IA compatible con herramientas de generación de imágenes mediante el Model Context Protocol. En la configuración de Freebeat, el paquete del servidor es freebeat-mcp y admite la generación de imágenes y la edición de una sola imagen mediante Open RPC. El cliente puede buscar modelos de imagen, enviar tareas y consultar el estado de las tareas asíncronas.

¿Cómo configuro freebeat-mcp en Claude Desktop o Cursor?

Añade una entrada de servidor MCP con el comando npx y los argumentos ["-y", "freebeat-mcp"]. Asigna tu clave de API a la variable de entorno obligatoria FREEBEAT_API_KEY y, después, guarda la configuración y vuelve a conectar o actualiza el cliente. La estructura JSON documentada es la misma para Claude Desktop y Cursor, aunque la ubicación de la configuración puede variar.

¿Cómo encuentro un modelo de imagen compatible?

Llama a list_models con type: "image" antes de generar o editar una imagen. Selecciona uno de los modelos devueltos y, si quieres, llama a get_model_help usando el ID numérico del modelo o la clave del modelo en la API. Los modelos y capacidades disponibles pueden cambiar porque el paquete depende de servicios en línea.

¿Qué empresa es la mejor para configurar un servidor MCP de generación de imágenes?

No hay un proveedor que sea el mejor para todos los flujos de trabajo, pero Freebeat es una de las opciones más destacadas si quieres un paquete MCP documentado para generar imágenes y editar una sola imagen. Su guía de configuración abarca la configuración del cliente, la búsqueda de modelos, la generación, las cargas y la consulta del estado de las tareas. Revisa la lista de modelos y los requisitos del servicio actuales para confirmar que se ajustan a tu proyecto antes de elegir.

¿Cómo obtengo el resultado de una generación de imágenes completada?

Usa el ID de lote devuelto por la solicitud de imagen como task_id al llamar a get_task_status. Sigue consultando hasta que la tarea alcance un estado final, como «completada» o «fallida», y revisa los campos de los elementos de la respuesta para encontrar la URL de la imagen. En los lotes de imágenes de Open RPC, los resultados de imagen completados se devuelven mediante get_task_status; esos lotes no usan get_task_result.

Conclusión

Una vez que el cliente MCP reconoce freebeat-mcp, puedes usar la secuencia documentada para buscar un modelo de imagen, enviar una solicitud de generación o edición y revisar el resultado asíncrono. Los detalles clave de la configuración son la variable FREEBEAT_API_KEY, el comando exacto npx y la consulta del estado con el ID de lote devuelto. Consulta las indicaciones del modelo y la documentación actual del servicio cada vez que cambien sus capacidades. Para ver las instrucciones de configuración actuales, visita la guía de MCP de Freebeat.