Connectez le serveur MCP fal.ai à Claude Code et Codex en quelques minutes. Découvrez les commandes pour les configurations OAuth et par token, les onze outils dont dispose votre agent, un prompt de contrôle des coûts, les solutions aux erreurs courantes, et une seconde option MCP pour les images et la vidéo.
Vous êtes à mi-chemin d’une fonctionnalité dans Claude Code, la page d’accueil a besoin d’une image principale, et la routine habituelle est pénible : ouvrir un onglet de navigateur, choisir un modèle, attendre le rendu, télécharger le fichier, le renommer, le glisser dans le dépôt. Le serveur MCP fal.ai supprime tout ce détour. Une fois connecté, votre agent de code peut parcourir le catalogue de plus de 1 000 modèles génératifs de fal, lire le schéma d’entrée d’un modèle, vérifier le prix, lancer la tâche et vous renvoyer une URL d’image, sans quitter le terminal.
Cet article montre comment connecter le serveur à Claude Code et à Codex, quelles commandes exécuter, quels outils vous obtenez, comment garder des dépenses prévisibles et quels sont les problèmes les plus fréquents. Il indique aussi où se place le connecteur MCP de PicassoIA si vous voulez un second back end pour le même flux de travail. Les commandes suivent les pages de configuration publiées par fal et la documentation MCP de chaque client. Lorsque les pages de fal se contredisent, je le signale.
MCP, le Model Context Protocol, est le standard ouvert qui permet à un client d’IA d’appeler des outils externes. Le serveur fal est un point de terminaison hébergé : il n’y a rien à installer, à compiler ni à faire tourner sur votre machine. Votre agent appelle les outils, et fal exécute les modèles sur ses propres GPU. La documentation de fal précise clairement la facturation : vous ne payez que les exécutions de modèles que vous déclenchez, au même tarif que les appels API directs.
Cela compte particulièrement pour le travail sur les images. Au lieu de figer un modèle dans un script, vous laissez l’agent choisir dans le catalogue, demander quelles entrées le modèle accepte et vérifier son coût, le tout en langage courant.
| Outil | Ce qu’il fait |
|---|---|
search_models | Recherche dans le catalogue par sujet ou par catégorie |
get_model_schema | Lit les paramètres d’entrée et de sortie d’un modèle |
get_pricing | Vérifie le prix avant une exécution |
search_docs | Recherche dans la documentation de fal |
recommend_model | Suggère des modèles pour une tâche précise |
run_model | Exécute un modèle et attend, 45 secondes par défaut |
submit_job | Lance une tâche longue sans attendre |
check_job | Indique l’état d’une tâche |
get_job_result | Récupère le résultat d’une tâche terminée |
cancel_job | Arrête une tâche en file d’attente ou en cours |
upload_file | Importe un fichier sur le CDN de fal pour l’utiliser comme entrée d’un modèle |
💡 Astuce : l’annonce de fal sur son blog mentionne neuf outils, alors que la page de documentation actuelle en liste onze. Attendez-vous à ce que la liste continue d’évoluer, et demandez à votre agent « quels outils fal voyez-vous ? » juste après la connexion.
get_pricing transforme la question « combien coûtera cette exécution ? » en une question à laquelle l’agent répond avant d’agir.
fal documente deux voies, qui utilisent des URL différentes. Choisissez-en une par machine plutôt que d’ajouter les deux sous le même nom.
La documentation renvoie vers https://mcp.fal.ai/mcp-relay, qui utilise Streamable HTTP et vous authentifie via le navigateur. Vous ne collez jamais de token dans un fichier de configuration ni dans une conversation. C’est le meilleur choix pour un ordinateur portable où vous pouvez ouvrir une fenêtre de navigateur.
L’article de blog de fal décrit https://mcp.fal.ai/mcp, où vous envoyez votre token API fal dans un en-tête Authorization: Bearer. Cette voie convient aux serveurs, aux conteneurs et à la CI, où aucun navigateur n’est disponible. fal indique que le token n’est jamais stocké de son côté, mais traitez-le tout de même comme un mot de passe : gardez-le dans une variable d’environnement, jamais dans un dépôt.
| Voie | URL | Authentification | Idéal pour |
|---|---|---|---|
| OAuth relay | https://mcp.fal.ai/mcp-relay | Connexion par navigateur | Ordinateurs portables et de bureau |
| Token Bearer | https://mcp.fal.ai/mcp | En-tête d’autorisation | Serveurs, CI, machines sans écran |
💡 Astuce : après la connexion par l’une ou l’autre voie, envoyez un prompt de test inoffensif : « Utilise fal pour rechercher des modèles de génération d’images. Ne lance aucun modèle. » Une liste de résultats de recherche prouve que l’authentification et les outils fonctionnent, et cela ne coûte rien.
Claude Code ajoute les serveurs distants avec claude mcp add. Les deux voies se font en une seule commande. Pour la voie OAuth :
claude mcp add --transport http fal https://mcp.fal.ai/mcp-relay
Ouvrez Claude Code et exécutez /mcp. Sélectionnez fal et terminez la connexion dans le navigateur. Cela correspond à la formulation de fal : ajouter le serveur distant, puis s’authentifier avec /mcp.
Pour la voie 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"
Le nom de variable FAL_TOKEN n’est qu’une étiquette, vous pouvez donc utiliser le nom de votre choix. Ajoutez --scope user pour rendre le serveur disponible dans chaque projet, ou --scope project pour l’écrire dans un .mcp.json partagé. Si une équipe partage ce fichier, référencez la variable à cet endroit au lieu de coller le token.
Pour vérifier la connexion, listez vos serveurs :
claude mcp list
Dans une session, /mcp affiche chaque serveur et son état. Si fal apparaît comme connecté, demandez la liste des outils. S’il demande une authentification, relancez l’étape de connexion.
Codex conserve les réglages MCP dans ~/.codex/config.toml, et les projets de confiance peuvent ajouter leur propre .codex/config.toml. Vous pouvez modifier le fichier à la main ou utiliser la famille de commandes codex mcp. La voie en une commande ressemble à ceci :
codex mcp add fal --url https://mcp.fal.ai/mcp-relay
codex mcp login fal
L’étape de connexion est celle que la documentation de fal signale pour Codex : ajoutez le serveur, puis exécutez codex mcp login fal. Codex évolue vite : si une option est refusée, exécutez codex mcp add --help pour obtenir la syntaxe actuelle.
La voie config.toml fait le même travail à la main :
[mcp_servers.fal]
url = "https://mcp.fal.ai/mcp-relay"
Pour la voie token Bearer, faites pointer Codex vers une variable d’environnement au lieu d’écrire le token dans le fichier :
[mcp_servers.fal_token]
url = "https://mcp.fal.ai/mcp"
bearer_token_env_var = "FAL_TOKEN"
Exportez FAL_TOKEN dans votre shell avant de lancer Codex. Ensuite, codex mcp list devrait afficher le serveur.
| Étape | Claude Code | Codex |
|---|---|---|
| Ajouter le serveur | claude mcp add --transport http | codex mcp add --url |
| Se connecter | /mcp dans une session | codex mcp login fal |
| Emplacement de la configuration | .claude.json ou .mcp.json | ~/.codex/config.toml |
| Fichier de règles du projet | CLAUDE.md | AGENTS.md |
| Lister les serveurs | claude mcp list | codex mcp list |
Soyez précis, et faites détailler sa démarche à l’agent avant qu’il ne dépense quoi que ce soit :
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.
Une session bien menée exécute search_models, puis get_model_schema et get_pricing, attend votre approbation, et seulement alors appelle run_model. La documentation de fal demande elle-même aux assistants d’afficher le coût estimé et de demander une approbation avant de générer, ce flux correspond donc à la conception voulue.
Enregistrez le résultat dans votre dépôt. L’outil renvoie une URL. Demandez l’étape suivante dans la même foulée : « Télécharge l’image dans public/images/harbor.jpg avec curl et référence-la dans le composant de l’image principale. » Un fichier local signifie que votre page ne dépend pas du maintien en ligne d’un lien distant.
run_model attend jusqu’à 45 secondes par défaut, ce qui convient à la plupart des modèles d’images. Les travaux plus lents, comme la vidéo ou l’upscaling lourd, passent par la file d’attente :
submit_job lance le travail et rend la main immédiatement.check_job indique l’état.get_job_result récupère le résultat quand la tâche se termine.cancel_job arrête une tâche lancée par erreur.Indiquez à l’agent le mode souhaité. « Soumets ceci comme une tâche et vérifie-la toutes les 20 secondes » fonctionne bien pour la vidéo.
Placez la règle là où l’agent la lit à chaque session : CLAUDE.md pour Claude Code, AGENTS.md pour 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.
Lisez le schéma une seule fois. get_model_schema liste les entrées d’un modèle : format, nombre d’images, seed, guidance. Lorsque l’agent le lit en premier, vous évitez les requêtes échouées dues à un nom de paramètre deviné à tort. Demandez à l’agent d’enregistrer les réglages qui fonctionnent dans les notes de votre projet afin que la session suivante évite cette recherche.
fal indique que le serveur MCP respecte les mêmes limites de concurrence que les appels API directs. Si vous demandez douze variantes d’un coup, attendez-vous à ce que certaines soient mises en file d’attente. Des lots de trois ou quatre se terminent plus vite et sont plus faciles à examiner.
| Symptôme | Cause probable | Solution |
|---|---|---|
| Aucun outil fal n’apparaît | La session a démarré avant l’ajout du serveur | Redémarrez Claude Code ou Codex, puis vérifiez avec /mcp ou codex mcp list |
| La connexion dans le navigateur ne se termine jamais | L’étape OAuth a été sautée | Exécutez /mcp dans Claude Code ou codex mcp login fal dans Codex |
| Erreur Unauthorized sur la voie token | La variable est vide ou l’en-tête est mal formé | Exportez de nouveau FAL_TOKEN et vérifiez que l’en-tête commence par Bearer |
| Une tâche expire | run_model cesse d’attendre au bout de 45 secondes | Passez à submit_job, puis interrogez avec check_job |
| La liste des outils affiche des logs et des apps au lieu des modèles | Le Platform MCP a été ajouté par erreur | Supprimez-le pour le travail sur les images et ajoutez le serveur principal de fal |
| L’image revient avec de mauvaises proportions | Le format a été laissé à sa valeur par défaut | Demandez à l’agent de lire get_model_schema et de définir le format explicitement |
Le serveur hébergé n’est pas la seule façon d’atteindre fal depuis un agent, et fal n’est pas le seul back end qui vaut la peine d’être branché.
| Serveur | Outils | Où il s’exécute | Points notables |
|---|---|---|---|
| raveenb/fal-mcp-server | 18 | Votre machine ou Docker | Licence MIT, STDIO et HTTP/SSE, installation en plugin Claude Code |
| wynandw87/claude-code-fal_ai-mcp | 22 | Votre machine avec Node | Outils de vidéo, de synchronisation labiale, d’échange de visage, de 3D et de musique |
Le premier s’installe comme plugin Claude Code :
/plugin install fal-ai@raveenb/fal-mcp-server
Les serveurs communautaires exécutent du code sur votre ordinateur avec votre token fal dans l’environnement : lisez donc le code source avant d’en ajouter un. Le serveur hébergé évite ce risque, puisque c’est fal qui l’exécute.
fal propose aussi un Platform MCP distinct à https://api.fal.ai/v1/mcp/platform. Il est strictement en lecture seule, et ses 16 outils servent à gérer votre compte : applications serverless, historique des requêtes, logs et analytics. Il utilise un schéma d’autorisation différent de celui du serveur principal, ne réutilisez donc jamais l’en-tête de l’un pour l’autre. Ce n’est pas un outil de génération d’images, mais vous pouvez connecter les deux en même temps.
Si vous voulez le même flux de travail d’agent sur un autre back end, PicassoIA propose son propre connecteur MCP. Dans Claude, il expose neuf outils : generate_image, edit_image, generate_video_picassoia, generate_video_seedance, get_generation, list_generations, cancel_generation, list_models et get_account.
Les tâches sont asynchrones. Un appel de génération renvoie un predict_id dès qu’un GPU accepte la tâche, puis vous interrogez get_generation après le délai suggéré jusqu’à ce que le statut indique succeeded ou failed. Le connecteur propose quatre modèles : PicassoIA Image, PicassoIA Image Editor Pro, PicassoIA Video et Seedance 2.5 Lite, les deux derniers produisant de la vidéo. Un compte autorise cinq prédictions simultanées, partagées entre toutes les connexions.
💡 Astuce : la description du connecteur indique que les générations sur les modèles GPU de PicassoIA sont gratuites avec les forfaits Infinite et Wonder. Consultez la page tarifaire pour voir ce que comprend votre forfait avant de construire un flux de travail autour.
Quel que soit le serveur utilisé, le bon modèle dépend de la tâche. Voici ceux que j’essaierais en premier, tous disponibles dans le catalogue de PicassoIA :
| Tâche | Modèles à essayer |
|---|---|
| Brouillons rapides | Flux Schnell, P Image |
| Images fixes photoréalistes | Flux 2 Pro, Imagen 4 Ultra |
| Texte dans les images | GPT Image 2 |
| Sortie 4K nette | Nano Banana Pro, Seedream 4.5 |
| Retoucher une image existante | Flux Kontext Pro, PicassoIA Image Editor Pro |
| Courte vidéo à partir d’une image fixe | Seedance 2.5 Lite, Kling v3 Video |
Le modèle de texte compte aussi, car c’est lui qui rédige le prompt que reçoit votre modèle d’image. Claude Sonnet 5 et GPT 5.6 Sol figurent tous deux dans le catalogue de PicassoIA, vous pouvez donc tester côte à côte la rédaction de prompts avant de vous engager.
Quelle voie vous convient ? Ce tableau met les trois options côte à côte :
| Option | Hébergement | Point fort | À choisir quand |
|---|---|---|---|
| MCP fal hébergé | fal | Plus de 1 000 modèles, vérifications de prix et de schéma | Vous voulez le catalogue le plus large sans rien installer |
| Serveur fal communautaire | Votre machine | Outils supplémentaires comme la synchronisation labiale et la 3D | Vous voulez un contrôle local et pouvez examiner le code |
| Connecteur PicassoIA | PicassoIA | Quatre modèles maison et interrogation asynchrone | Vous voulez un ensemble d’outils réduit et ciblé sur l’image et la vidéo |
Connecter un serveur prend cinq minutes. Choisir le bon modèle demande quelques essais, et cette partie est plus agréable dans un navigateur. Ouvrez Picasso IA, parcourez la liste complète des modèles, et lancez un même prompt sur deux ou trois modèles côte à côte. Commencez par PicassoIA Image, présenté comme un générateur de texte vers image illimité, puis essayez Flux 2 Pro et Seedream 4.5 avec la même formulation.
Une fois que vous savez quel modèle donne l’aspect souhaité, reportez ce choix dans Claude Code ou Codex et inscrivez-le dans votre fichier de règles. Votre agent cessera alors de deviner, et chaque image principale de votre prochain projet partira d’un modèle choisi délibérément.
Choisissez votre langue
