Conecta el servidor MCP de fal.ai a Claude Code y Codex en minutos. Consulta los comandos para configurar OAuth y tokens, las once herramientas que obtiene tu agente, un prompt para controlar costos, soluciones a errores comunes y una segunda opción MCP para imágenes y video.
Estás a mitad de una función en Claude Code, la página de inicio necesita una imagen principal y la rutina habitual es un tostón: abrir una pestaña del navegador, elegir un modelo, esperar el render, descargar el archivo, renombrarlo y arrastrarlo al repositorio. El servidor MCP de fal.ai elimina todo ese rodeo. Una vez conectado, tu agente de programación puede buscar en el catálogo de fal de más de 1.000 modelos generativos, leer el esquema de entrada de un modelo, consultar el precio, ejecutar el trabajo y devolverte una URL de la imagen sin salir de la terminal.
Este artículo explica cómo conectar el servidor a Claude Code y a Codex, qué comandos ejecutar, qué herramientas obtienes, cómo mantener el gasto previsible y qué falla con más frecuencia. También muestra dónde encaja el conector MCP propio de PicassoIA si quieres un segundo back end para el mismo flujo de trabajo. Los comandos siguen las páginas de configuración publicadas por fal y la documentación MCP de cada cliente. Cuando las páginas de fal no coinciden entre sí, lo indico.
MCP, el Protocolo de contexto de modelos, es el estándar abierto que permite a un cliente de IA llamar a herramientas externas. El servidor de fal es un endpoint alojado, así que no hay nada que instalar, compilar ni mantener en ejecución en tu equipo. Tu agente llama a las herramientas y fal ejecuta los modelos en sus propias GPU. La documentación de fal lo deja claro en cuanto a la facturación: solo pagas las ejecuciones de modelos que disparas, al mismo precio que en las llamadas directas a la API.
Esto importa sobre todo para el trabajo con imágenes. En lugar de fijar un modelo en un script, dejas que el agente elija entre el catálogo, pregunte qué entradas acepta el modelo y compruebe cuánto costará, todo en lenguaje natural.
| Herramienta | Qué hace |
|---|---|
search_models | Busca en el catálogo por tema o categoría |
get_model_schema | Lee los parámetros de entrada y salida de un modelo |
get_pricing | Consulta el precio antes de una ejecución |
search_docs | Busca en la documentación de fal |
recommend_model | Sugiere modelos para una tarea específica |
run_model | Ejecuta un modelo y espera, 45 segundos por defecto |
submit_job | Inicia un trabajo largo sin esperar |
check_job | Informa del estado de un trabajo |
get_job_result | Obtiene el resultado de un trabajo terminado |
cancel_job | Detiene un trabajo en cola o en ejecución |
upload_file | Sube un archivo a la CDN de fal para usarlo como entrada de un modelo |
💡 Consejo: el anuncio de fal en su blog enumera nueve herramientas, mientras que la página actual de documentación lista once. Espera que la lista siga cambiando y pregúntale a tu agente «¿qué herramientas de fal ves?» justo después de conectar.
get_pricing convierte «¿cuánto costará esto?» en una pregunta que el agente responde antes de actuar.
fal documenta dos rutas, y usan URL distintas. Elige una por equipo en lugar de añadir las dos con el mismo nombre.
La documentación indica https://mcp.fal.ai/mcp-relay, que usa Streamable HTTP e inicia sesión desde el navegador. Nunca pegas un token en un archivo de configuración ni en un chat. Es la mejor opción para un equipo portátil donde puedas abrir una ventana del navegador.
El artículo del blog de fal describe https://mcp.fal.ai/mcp, en el que envías tu token de API de fal en una cabecera Authorization: Bearer. Encaja con servidores, contenedores y CI, donde no hay navegador disponible. fal dice que el token nunca se almacena de su lado, pero trátalo como una contraseña igualmente: guárdalo en una variable de entorno y nunca en un repositorio.
| Ruta | URL | Inicio de sesión | Ideal para |
|---|---|---|---|
| Relay OAuth | https://mcp.fal.ai/mcp-relay | Inicio de sesión en el navegador | Equipos portátiles y de escritorio |
| Token Bearer | https://mcp.fal.ai/mcp | Cabecera de autorización | Servidores, CI, equipos sin pantalla |
💡 Consejo: después de conectar cualquiera de las dos rutas, envía un prompt de prueba inofensivo: «Usa fal para buscar modelos de generación de imágenes. No ejecutes ningún modelo.» Una lista de resultados de búsqueda demuestra que el inicio de sesión y las herramientas funcionan, y no cuesta nada.
Claude Code añade servidores remotos con claude mcp add. Ambas rutas requieren un único comando. Para la ruta OAuth:
claude mcp add --transport http fal https://mcp.fal.ai/mcp-relay
Abre Claude Code y ejecuta /mcp. Selecciona fal y completa el inicio de sesión en el navegador. Esto coincide con la redacción de la propia fal: añade el servidor remoto y luego autentícate con /mcp.
Para la ruta con token Bearer:
export FAL_TOKEN="paste-your-fal-token-here"
claude mcp add --transport http fal-ai https://mcp.fal.ai/mcp \
--header "Authorization: Bearer $FAL_TOKEN"
El nombre de la variable FAL_TOKEN es solo una etiqueta, así que usa el que quieras. Añade --scope user para que el servidor esté disponible en todos los proyectos, o --scope project para escribirlo en un .mcp.json compartido. Si un equipo comparte ese archivo, haz referencia a la variable allí en lugar de pegar el token.
Para comprobar la conexión, lista tus servidores:
claude mcp list
Dentro de una sesión, /mcp muestra todos los servidores y su estado. Si fal aparece como conectado, pide la lista de herramientas. Si pide autenticarse, vuelve a ejecutar el paso de inicio de sesión.
Codex guarda la configuración de MCP en ~/.codex/config.toml, y los proyectos de confianza pueden añadir su propio .codex/config.toml. Puedes editar el archivo a mano o usar la familia de comandos codex mcp. La ruta de un solo comando es así:
codex mcp add fal --url https://mcp.fal.ai/mcp-relay
codex mcp login fal
El paso de inicio de sesión es el que la documentación de fal destaca para Codex: añade el servidor y luego ejecuta codex mcp login fal. Codex cambia con rapidez, así que si se rechaza una opción, ejecuta codex mcp add --help para ver la sintaxis actual.
La ruta de config.toml hace lo mismo a mano:
[mcp_servers.fal]
url = "https://mcp.fal.ai/mcp-relay"
Para la ruta con token Bearer, apunta Codex a una variable de entorno en lugar de escribir el token en el archivo:
[mcp_servers.fal_token]
url = "https://mcp.fal.ai/mcp"
bearer_token_env_var = "FAL_TOKEN"
Exporta FAL_TOKEN en tu shell antes de iniciar Codex. Después, codex mcp list debería mostrar el servidor.
| Paso | Claude Code | Codex |
|---|---|---|
| Añadir el servidor | claude mcp add --transport http | codex mcp add --url |
| Iniciar sesión | /mcp dentro de una sesión | codex mcp login fal |
| Ubicación de la configuración | .claude.json o .mcp.json | ~/.codex/config.toml |
| Archivo de reglas del proyecto | CLAUDE.md | AGENTS.md |
| Listar servidores | claude mcp list | codex mcp list |
Empieza con algo concreto y haz que el agente muestre su trabajo antes de gastar nada:
Use fal to find a fast photorealistic text-to-image model. Show me its price and input schema, wait for my OK, then generate one 16:9 image of a quiet harbor at dawn.
Una sesión bien encaminada ejecuta search_models, luego get_model_schema y get_pricing, se detiene para tu aprobación y solo entonces llama a run_model. La propia documentación de fal indica a los asistentes que muestren el costo estimado y pidan aprobación antes de generar, así que este flujo coincide con el diseño previsto.
Guarda el resultado en tu repositorio. La herramienta devuelve una URL. Pide el siguiente paso en el mismo mensaje: «Descarga la imagen en public/images/harbor.jpg con curl y haz referencia a ella en el componente principal.» Un archivo local significa que tu página no depende de que un enlace remoto siga activo.
run_model espera hasta 45 segundos por defecto, lo que encaja con la mayoría de modelos de imagen. El trabajo más lento, como el video o el escalado pesado, va a la cola:
submit_job inicia el trabajo y devuelve la respuesta de inmediato.check_job informa del estado.get_job_result obtiene el resultado cuando el trabajo termina.cancel_job detiene un trabajo que iniciaste por error.Dile al agente qué modo quieres. «Envía esto como trabajo y revísalo cada 20 segundos» funciona bien con video.
Coloca la regla donde el agente la lea en cada sesión: CLAUDE.md para Claude Code, AGENTS.md para Codex.
fal.ai rules:
- Call get_pricing before every run_model or submit_job.
- Show the estimated cost and wait for my approval when it is above $0.50.
- Never generate more than four images per request without asking.
Lee el esquema una vez. get_model_schema enumera las entradas de un modelo: relación de aspecto, número de imágenes, semilla y guidance scale (CFG). Cuando el agente lo lee primero, evitas solicitudes fallidas por un nombre de parámetro adivinado mal. Pídele al agente que guarde la configuración que funciona en las notas de tu proyecto para que la siguiente sesión omita la consulta.
fal indica que el servidor MCP respeta los mismos límites de concurrencia que las llamadas directas a la API. Si pides doce variaciones a la vez, espera que algunas se pongan en cola. Los lotes de tres o cuatro terminan antes y son más fáciles de revisar.
| Síntoma | Causa probable | Solución |
|---|---|---|
| No aparecen herramientas de fal | La sesión empezó antes de añadir el servidor | Reinicia Claude Code o Codex y luego comprueba /mcp o codex mcp list |
| El inicio de sesión en el navegador nunca termina | Se saltó el paso de OAuth | Ejecuta /mcp en Claude Code o codex mcp login fal en Codex |
| Error de no autorizado en la ruta con token | La variable está vacía o la cabecera está mal formada | Exporta FAL_TOKEN de nuevo y confirma que la cabecera empieza por Bearer |
| Un trabajo agota el tiempo de espera | run_model deja de esperar a los 45 segundos | Cambia a submit_job y luego consulta con check_job |
| La lista de herramientas muestra logs y apps en lugar de modelos | Se añadió la Platform MCP por error | Elimínala para el trabajo con imágenes y añade el servidor principal de fal |
| La imagen sale con la forma incorrecta | La relación de aspecto se dejó por defecto | Pide al agente que lea get_model_schema y fije la relación explícitamente |
El servidor alojado no es la única forma de llegar a fal desde un agente, y fal no es el único back end que merece la pena conectar.
| Servidor | Herramientas | Dónde se ejecuta | Destacado |
|---|---|---|---|
| raveenb/fal-mcp-server | 18 | Tu equipo o Docker | Licencia MIT, STDIO y HTTP/SSE, instalación como plugin de Claude Code |
| wynandw87/claude-code-fal_ai-mcp | 22 | Tu equipo con Node | Herramientas de video, sincronización labial, intercambio de rostros, 3D y música |
El primero se instala como plugin de Claude Code:
/plugin install fal-ai@raveenb/fal-mcp-server
Los servidores comunitarios ejecutan código en tu equipo con tu token de fal en el entorno, así que lee el código fuente antes de añadir uno. El servidor alojado evita ese riesgo porque lo ejecuta fal.
fal también publica una Platform MCP independiente en https://api.fal.ai/v1/mcp/platform. Es estrictamente de solo lectura y sus 16 herramientas están pensadas para gestionar tu cuenta: apps serverless, historial de solicitudes, logs y analíticas. Usa un esquema de autorización distinto al del servidor principal, así que nunca reutilices la cabecera entre ambos. No es una herramienta de imágenes, pero puedes conectar los dos a la vez.
Si quieres el mismo flujo de trabajo con agentes sobre otro back end, PicassoIA ejecuta su propio conector MCP. Dentro de Claude expone nueve herramientas: generate_image, edit_image, generate_video_picassoia, generate_video_seedance, get_generation, list_generations, cancel_generation, list_models y get_account.
Los trabajos son asíncronos. Una llamada de generación devuelve un predict_id en cuanto una GPU acepta el trabajo, y consultas get_generation tras el retardo sugerido hasta que el estado indique succeeded o failed. El conector sirve cuatro modelos: PicassoIA Image, PicassoIA Image Editor Pro, PicassoIA Video y Seedance 2.5 Lite, los dos últimos producen video. Una cuenta permite cinco predicciones simultáneas, compartidas entre todas las conexiones.
💡 Consejo: la propia descripción del conector indica que las generaciones con los modelos de GPU de PicassoIA son gratuitas en los planes Infinite y Wonder. Revisa la página de precios para ver qué incluye tu plan antes de construir un flujo de trabajo sobre ello.
Sea cual sea el servidor que uses, el modelo adecuado depende del trabajo. Estos son los que probaría primero, todos disponibles en el catálogo de PicassoIA:
| Tarea | Modelos para probar |
|---|---|
| Borradores rápidos | Flux Schnell, P Image |
| Imágenes fotorrealistas | Flux 2 Pro, Imagen 4 Ultra |
| Texto dentro de las imágenes | GPT Image 2 |
| Salida 4K nítida | Nano Banana Pro, Seedream 4.5 |
| Editar una imagen existente | Flux Kontext Pro, PicassoIA Image Editor Pro |
| Video corto a partir de una imagen fija | Seedance 2.5 Lite, Kling v3 Video |
El modelo de texto también importa, porque escribe el prompt que recibe tu modelo de imagen. Claude Sonnet 5 y GPT 5.6 Sol están ambos en el catálogo de PicassoIA, así que puedes probar la redacción de prompts uno al lado del otro antes de decidirte por uno.
¿Qué ruta te conviene? Esta tabla pone las tres opciones una al lado de la otra:
| Opción | Alojamiento | Fortaleza | Elígela cuando |
|---|---|---|---|
| fal MCP alojado | fal | Más de 1.000 modelos, comprobación de precios y esquemas | Quieres el catálogo más amplio sin instalar nada |
| Servidor comunitario de fal | Tu equipo | Herramientas extra como sincronización labial y 3D | Quieres control local y puedes revisar el código |
| Conector de PicassoIA | PicassoIA | Cuatro modelos propios y sondeo asíncrono | Quieres un conjunto pequeño y centrado de herramientas de imagen y video |
Conectar un servidor lleva cinco minutos. Elegir bien un modelo requiere unos cuantos experimentos, y esa parte es más divertida en el navegador. Abre PicassoIA, explora la lista completa de modelos y ejecuta un prompt con dos o tres modelos uno al lado del otro. Empieza con PicassoIA Image, que figura como generador de texto a imagen ilimitado, y luego prueba Flux 2 Pro y Seedream 4.5 con la misma redacción.
Cuando sepas qué modelo te da el aspecto que buscas, lleva esa elección de vuelta a Claude Code o Codex y escríbela en tu archivo de reglas. Así tu agente deja de adivinar, y cada imagen principal de tu próximo proyecto parte de un modelo que elegiste a conciencia.
Elige tu idioma
