Comment connecter Claude Code ou Codex à n8n avec MCP ?

Tu demandes à Claude Code de construire un workflow n8n. Il produit un JSON de deux cents lignes, ajoute les bons noms de nœuds et relie le tout avec une assurance remarquable. Tu importes le fichier. Un paramètre n’existe plus, une expression pointe vers le mauvais item et le nœud HTTP attend un credential que personne n’a créé.

Le résultat ressemble à un workflow n8n. Il n’a pourtant jamais été confronté à ton instance, à sa version, à ses nœuds disponibles ni à une vraie exécution.

La solution actuelle repose sur trois couches. Le serveur MCP officiel de n8n donne à l’agent des outils pour rechercher, créer, valider et tester. Les Skills officiels lui apportent les conventions n8n au moment où il en a besoin. L’API REST fournit une voie plus déterministe pour sauvegarder un workflow ou relire une exécution. Le MCP lui donne les mains. Les Skills lui donnent la méthode. L’API conserve une porte de contrôle.

Dans ce guide, tu vas connecter Claude Code ou Codex à n8n, leur apprendre une routine de construction fiable, puis leur faire créer et déboguer un workflow d’inscription idempotent. Tout se déroule sur une instance ou un projet de développement. La production restera hors de portée jusqu’à ta validation.

Les trois couches de ton expert n8n

n8n intègre un serveur MCP au niveau de l’instance. Un client compatible peut appeler les outils exposés par ce serveur sans passer par le canvas. Depuis n8n 2.13, ces outils savent aussi créer et modifier des workflows. Tu peux donc décrire un besoin dans Claude Code ou Codex, laisser l’agent inspecter les définitions actuelles, puis retrouver le résultat dans l’éditeur n8n.

Le mot « MCP » recouvre trois fonctions différentes dans n8n :

Ici, nous utilisons uniquement la première fonction. Tu ne construis pas un nouveau serveur. Si ton besoin consiste justement à exposer une API maison, le guide pour créer un serveur MCP couvre cette architecture.

Le MCP et l’API REST ne partagent pas le même secret. Le serveur MCP utilise OAuth ou un jeton MCP personnel. L’API publique utilise une clé API transmise dans l’en-tête X-N8N-API-KEY. Mélanger les deux produit généralement un 401 Unauthorized alors que l’URL semble correcte.

Préparer n8n sans ouvrir la production

Commence sur une instance de développement ou dans un projet n8n réservé aux essais. Un agent capable de modifier un workflow possède déjà une capacité sensible. Le brancher directement à la production transforme une erreur de compréhension en changement réel.

Dans n8n, ouvre Settings > Instance-level MCP, puis active Enable MCP access. Cette opération demande les permissions de propriétaire ou d’administrateur de l’instance. Le bouton Connection details affiche l’URL exacte à transmettre au client. Pour une instance hébergée sur https://n8n.exemple.fr, l’endpoint ressemble à ceci :

https://n8n.exemple.fr/mcp-server/http

C’est cette adresse que le client réclame au moment de la connexion, juste à côté du choix de la méthode d’authentification.

La fenêtre pose donc deux questions en même temps : l’URL du serveur et la façon dont le client prouve son identité. n8n accepte deux réponses pour la seconde :

Choisis OAuth dès que le client le gère. Le navigateur t’envoie sur ton instance n8n, tu autorises la connexion et le client conserve le jeton résultant. Avec un Access Token, copie la valeur immédiatement. n8n masque ensuite le jeton et révoque l’ancien quand tu en génères un nouveau.

L’accès reste lié à l’utilisateur connecté. search_workflows peut afficher un aperçu des workflows auxquels cet utilisateur a accès. Les détails, les modifications et l’exécution demandent que le workflow soit explicitement disponible dans MCP. Tu peux l’activer depuis les réglages MCP, la fiche du workflow ou Workflow settings > Available in MCP.

Cette sélection n’est pas propre à Claude Code ou à Codex. Si les deux clients utilisent le même compte n8n, ils voient les mêmes workflows autorisés. Crée un compte ou un projet distinct si tu as besoin d’une séparation plus forte.

Installer les Skills n8n dans Claude Code

Une connexion MCP seule permet à Claude Code d’appeler les tools. Elle ne lui enseigne pas automatiquement les subtilités de $json, les règles de pagination, les stratégies de reprise ou les limites des credentials. n8n publie pour cela un plugin officiel de Skills.

Depuis une session Claude Code, ajoute le marketplace et installe le plugin :

/plugin marketplace add n8n-io/skills
/plugin install n8n-skills@n8n-io
/reload-plugins

Le plugin te demande l’URL de base de l’instance, par exemple https://n8n.exemple.fr. Ne colle pas /mcp-server/http dans ce champ, le plugin l’ajoute. Lance ensuite :

/mcp

Sélectionne n8n-mcp, choisis Authenticate, puis autorise Claude Code dans le navigateur. Le plugin installe treize Skills spécialisés et un méta-skill chargé au démarrage. Des hooks rappellent également à l’agent de consulter la bonne référence avant un appel MCP important. Le panneau /mcp confirme ensuite le résultat de cette autorisation.

Un serveur marqué connecté et une liste de tools visible signifient que Claude Code interroge désormais ton instance. Un serveur absent ou en erreur à ce stade vient presque toujours d’une URL mal recopiée ou d’une autorisation interrompue dans le navigateur.

Si tu préfères une connexion sans plugin, Claude Code accepte directement un serveur HTTP distant :

claude mcp add --transport http n8n-mcp \
  https://n8n.exemple.fr/mcp-server/http

Dans une session, /mcp lance l’authentification OAuth. Hors session, les commandes suivantes vérifient la configuration :

claude mcp list
claude mcp get n8n-mcp

Pour une authentification par jeton sans l’écrire dans l’historique du terminal, un fichier .mcp.json peut référencer des variables d’environnement :

{
  "mcpServers": {
    "n8n-mcp": {
      "type": "http",
      "url": "${N8N_URL}/mcp-server/http",
      "headers": {
        "Authorization": "Bearer ${N8N_MCP_TOKEN}"
      }
    }
  }
}

Un serveur au scope project place sa configuration dans .mcp.json et peut être partagé avec l’équipe. Conserve seulement les noms des variables dans Git. Le scope local, utilisé par défaut, reste privé au projet et à ton utilisateur. Le scope user rend le serveur disponible dans tous tes projets.

Si le plugin a déjà créé n8n-mcp, n’ajoute pas une seconde configuration manuelle portant un autre nom. Deux jeux de tools identiques consomment du contexte et l’agent peut alterner entre deux authentifications différentes.

Installer les Skills n8n dans Codex

Le dépôt officiel indique actuellement une version minimale de Codex 0.142.0 pour son plugin. Vérifie ta version et mets Codex à jour avant de chercher une panne MCP plus compliquée.

Dans un terminal, installe le marketplace et le plugin :

codex plugin marketplace add n8n-io/skills
codex plugin add n8n-skills@n8n-io

Redémarre Codex, puis accepte la demande de confiance concernant les hooks. Ajoute ensuite le serveur MCP, car le plugin Codex ne configure pas automatiquement l’URL :

codex mcp add n8n-mcp \
  --url https://n8n.exemple.fr/mcp-server/http

Codex lance le parcours OAuth à la première utilisation. Dans l’application, tu peux aussi ouvrir Settings > MCP servers > Add server, choisir Streamable HTTP, coller l’URL et redémarrer.

Pour un jeton personnel conservé dans une variable d’environnement, ajoute cette configuration dans ~/.codex/config.toml :

[mcp_servers.n8n-mcp]
url = "https://n8n.exemple.fr/mcp-server/http"
bearer_token_env_var = "N8N_MCP_TOKEN"

La commande suivante confirme que Codex voit le serveur :

codex mcp list

Dans une session Codex, /mcp affiche les tools disponibles. Tu peux aussi limiter ceux que le serveur expose au modèle avec enabled_tools et disabled_tools dans config.toml. Une bonne politique autorise facilement la recherche et la validation, puis demande une approbation pour la création, la modification, l’archivage et la publication.

Écrire le contrat de travail de l’agent

Les Skills apportent les pratiques générales de n8n. Ton projet doit encore préciser ses propres frontières : instance autorisée, convention de nommage, politique de publication, tests requis et données interdites.

Place le bloc suivant dans CLAUDE.md pour Claude Code ou dans AGENTS.md pour Codex. Adapte les noms de projet et les règles métier, mais conserve les points d’arrêt :

# Travail Sur Les Workflows n8n

- Utilise uniquement l'instance et le projet de développement indiqués.
- Charge le méta-skill `using-n8n-skills-official` avant toute action n8n.
- Commence par lire la référence SDK et les définitions actuelles des nœuds.
- Recherche un workflow existant avant d'en créer un nouveau.
- Valide le workflow avant sa création et après chaque modification.
- Crée et modifie uniquement des versions non publiées.
- Ne crée, ne remplace et n'affiche jamais un secret ou un credential.
- Prépare des données de test sans donnée personnelle réelle.
- Après un échec, récupère l'exécution et identifie le premier nœud fautif.
- Applique une seule correction causale, puis rejoue le test.
- Ne publie, n'archive et ne supprime rien sans approbation explicite.
- Termine avec l'ID du workflow, les tests effectués, leurs résultats et les risques restants.

Un fichier d’instructions efficace décrit des comportements vérifiables. « Construis des workflows robustes » ne donne aucun contrôle. « Valide avant la création et ne publie jamais sans approbation » produit une action observable. Le même principe est détaillé dans le guide pour écrire un CLAUDE.md utile.

Faire construire un workflow d’inscription

Le cas pratique reçoit une demande d’inscription par Webhook. Il vérifie l’email, normalise sa valeur, refuse une requête invalide et empêche qu’un nouvel essai crée un doublon. Une Data Table conserve request_id, email, status et created_at.

Ce petit workflow force l’agent à traiter les sujets qui distinguent une démonstration d’une automatisation exploitable : validation, idempotence, branches HTTP, stockage et tests négatifs.

Crée d’abord une Data Table vide nommée registrations, ou demande à l’agent de la créer dans le projet de développement. Envoie ensuite ce prompt :

Travaille uniquement dans le projet n8n de développement.

Construis un workflow non publié nommé "DEV - Inscription Idempotente".
Il reçoit un POST JSON sur un Webhook avec request_id et email.

Règles :
1. Refuse avec HTTP 422 si request_id manque ou si email est invalide.
2. Normalise email en minuscules et supprime les espaces extérieurs.
3. Recherche request_id dans la Data Table registrations.
4. Si request_id existe, ne crée aucune ligne et répond HTTP 200 avec
   {"status":"duplicate"}.
5. Sinon, ajoute la ligne avec status="created" et répond HTTP 201 avec
   {"status":"created"}.
6. Ne publie pas le workflow.

Avant de créer : charge les Skills n8n nécessaires, consulte la référence SDK,
vérifie les types de nœuds et valide le workflow.

Après la création : teste une inscription valide, la même requête rejouée,
un email invalide et un request_id absent. Donne l'ID du workflow, l'ID de
chaque exécution et le résultat observé.

L’agent ne doit pas écrire immédiatement un gros objet de mémoire. La référence des tools MCP n8n fournit une séquence plus sûre :

1. get_sdk_reference charge la syntaxe de construction attendue ;
2. search_nodes trouve les nœuds capables de répondre au besoin ;
3. get_node_types récupère leurs définitions actuelles ;
4. validate_workflow contrôle le code du workflow avant sa création ;
5. create_workflow_from_code crée une version non publiée ;
6. prepare_test_pin_data prépare les entrées des nœuds qui ne peuvent pas être appelés directement ;
7. test_workflow exécute le scénario de test ;
8. get_execution récupère le statut et les données utiles ;
9. update_workflow applique des opérations partielles de correction.

Les noms et la disponibilité de certains tools dépendent de la version de n8n. C’est précisément la raison pour laquelle l’agent doit interroger le serveur au lieu de recopier une liste mémorisée dans un prompt ancien.

Examine le canvas avant de poursuivre. Vérifie que chaque branche arrive sur une réponse HTTP, que la Data Table sélectionnée est la bonne et que le workflow reste non publié. Un workflow valide au niveau du schéma peut toujours traduire une mauvaise règle métier.

Déboguer depuis la première exécution fautive

Un agent perd vite du temps quand il modifie trois nœuds après un seul message d’erreur. Il ne sait plus quelle correction a produit le nouvel état. Imposons une boucle plus courte :

execute_workflow démarre par défaut la version publiée en mode production. Pour tester la version courante non publiée, l’agent doit utiliser le mode manuel prévu par le tool ou test_workflow. Cette distinction évite de croire qu’une correction est inefficace alors que le serveur exécute encore l’ancienne version publiée.

Demande ensuite un rapport borné :

Récupère l'exécution qui vient d'échouer.
Retourne seulement le statut, le premier nœud en erreur, son message,
son entrée utile et la valeur qui ne respecte pas sa configuration.
N'affiche aucun credential et tronque les sorties volumineuses.
Propose une seule cause, puis attends avant de modifier le workflow.

get_execution peut filtrer les données par nom de nœud et tronquer les résultats. Utilise ces options. Charger dix mille lignes de sortie dans la conversation rend le diagnostic plus cher et peut repousser les instructions importantes hors du contexte.

Pour le workflow d’inscription, la matrice suivante doit passer dans cet ordre :

Le dernier test est le plus exigeant. Une recherche suivie d’une insertion ne garantit pas toujours l’unicité si deux exécutions lisent la table au même instant. Si la Data Table ou l’architecture choisie ne permet pas une contrainte atomique, l’agent doit l’écrire dans son rapport. En production, déplace la clé d’idempotence vers un stockage capable d’imposer une unicité ou sérialise le traitement.

Utiliser l’API REST comme voie de contrôle

Le MCP convient aux tâches exploratoires : chercher un nœud, lire le SDK, construire, tester, corriger. L’API REST convient mieux à une commande dont tu veux connaître exactement la requête et conserver le résultat. Elle peut sauvegarder le workflow avant une modification ou récupérer une exécution indépendamment du contexte de l’agent.

Dans n8n, ouvre Settings > n8n API, crée une clé avec une expiration et limite ses scopes quand ton offre le permet. Le jeton MCP ne fonctionne pas ici.

Dans un terminal compatible Bash, prépare les variables suivantes :

export N8N_API_URL="https://n8n.exemple.fr"
export N8N_API_KEY="remplace-par-ta-cle-api"
export WORKFLOW_ID="remplace-par-id-workflow"

Récupère le JSON actuel avant de laisser l’agent modifier le workflow :

curl --fail-with-body --silent --show-error \
  --header "X-N8N-API-KEY: ${N8N_API_KEY}" \
  "${N8N_API_URL}/api/v1/workflows/${WORKFLOW_ID}" \
  --output "workflow-${WORKFLOW_ID}-avant.json"

La documentation de l’API n8n décrit les endpoints disponibles et leur pagination. Le fichier obtenu contient la structure du workflow, pas les secrets contenus dans les credentials n8n. Garde-le dans un répertoire privé si les noms de nœuds, les URL ou les expressions révèlent tout de même des informations internes.

Pour relire une exécution précise avec ses données, ajoute son identifiant :

export EXECUTION_ID="remplace-par-id-execution"

curl --fail-with-body --silent --show-error \
  --header "X-N8N-API-KEY: ${N8N_API_KEY}" \
  "${N8N_API_URL}/api/v1/executions/${EXECUTION_ID}?includeData=true"

Une réponse 401 Unauthorized indique d’abord un problème d’authentification : mauvaise clé, expiration, en-tête absent ou endpoint MCP appelé avec une clé API. Une réponse 404 peut signaler un identifiant erroné, mais aussi un workflow ou une exécution inaccessible à l’utilisateur de la clé.

Évite de faire écrire le workflow complet par PUT /workflows/{id} pour une petite correction si le MCP propose une modification partielle. Le remplacement intégral augmente la surface d’erreur et peut écraser une évolution concurrente. Garde l’API en lecture et en sauvegarde dans le premier montage. Tu ajouteras les écritures seulement après avoir défini un contrôle de version et une stratégie de retour arrière.

Ce qui va te bloquer

Le client répond 401 Unauthorized

Vérifie l’endpoint avant de remplacer le secret. /mcp-server/http attend OAuth ou un Bearer token MCP. /api/v1 attend X-N8N-API-KEY. Vérifie ensuite l’expiration, les espaces dans l’en-tête et la rotation du jeton. Générer un nouveau jeton MCP révoque l’ancien pour tous les clients qui l’utilisaient.

Le serveur est connecté, mais aucun workflow n’est modifiable

L’instance MCP peut être active tandis que le workflow reste indisponible. Active Available in MCP sur ce workflow. Vérifie aussi les droits du compte connecté. La recherche peut montrer un aperçu sans donner accès aux détails.

Les tools de création n’apparaissent pas

La création et la modification par MCP demandent n8n 2.13 ou une version plus récente. Une ancienne version peut exposer la recherche et l’exécution sans proposer create_workflow_from_code. Mets n8n à jour vers une version stable compatible, puis reconnecte le client pour rafraîchir la liste des tools.

Codex affiche Transport channel closed

Un ticket du dépôt Codex reproduit cette erreur avec Codex CLI 0.130.0 et le serveur MCP n8n. Commence par mettre Codex à jour, le plugin de Skills n8n demandant actuellement Codex 0.142.0 ou plus. Teste ensuite l’URL avec OAuth sans proxy ni wrapper. Si la panne persiste, conserve la version exacte de Codex, de n8n, le transport et le journal de handshake avant de conclure à un problème de jeton.

Claude Code ou Codex voit deux serveurs n8n

Le plugin et ta configuration manuelle ont probablement ajouté chacun une connexion. Désactive ou supprime le doublon. Garde un seul serveur nommé n8n-mcp, puis relance le client.

Le workflow est corrigé, mais le test rejoue l’ancienne version

Le mode production de execute_workflow utilise la version publiée. Lance un test manuel de la version courante, ou publie seulement après validation. Note toujours le mode et la version dans le rapport de test.

Le nœud HTTP n’a aucun credential

Le serveur MCP ne révèle jamais la valeur secrète des credentials. Certains outils peuvent associer une credential existante quand le choix est non ambigu, mais le nœud HTTP Request demande souvent une sélection explicite. Crée ou sélectionne le credential dans n8n. Ne colle pas une clé dans un paramètre du nœud pour faire passer le test.

Le diagnostic remplit toute la conversation

Filtre get_execution sur les nœuds utiles, désactive les données quand le statut suffit et tronque les sorties. Pour un gros fichier ou plusieurs milliers d’items, conserve l’échantillon qui reproduit l’erreur et inspecte le reste hors du contexte du modèle.

Passer en production avec des commandes de secours

Un workflow créé par un agent mérite la même revue qu’un workflow créé à la main. L’interface paraît plus rapide, mais les risques restent les mêmes : doublon, donnée perdue, secret exposé, appel répété après timeout ou branche d’erreur jamais testée.

Applique cette séquence :

1. travaille dans un projet ou une instance de développement ;
2. sauvegarde le JSON de la version précédente ;
3. crée une version non publiée ;
4. valide la structure ;
5. teste les entrées nominales et invalides ;
6. rejoue la même entrée pour vérifier l’idempotence ;
7. simule un timeout de l’API externe ;
8. vérifie les nouvelles tentatives et la file d’échec ;
9. contrôle les credentials dans l’interface ;
10. fais relire le canvas et le rapport par une personne ;
11. publie avec une approbation explicite ;
12. surveille les premières exécutions et garde la procédure de retour arrière accessible.

Une requête externe qui expire peut avoir été traitée malgré le timeout. L’agent ne doit pas répéter aveuglément une écriture. Ajoute une clé d’idempotence quand l’API la prend en charge, journalise l’état unknown et vérifie le résultat avant une nouvelle tentative. Les retries doivent être bornés et espacés. Les éléments définitivement bloqués rejoignent une file d’échec accompagnée du contexte nécessaire à leur reprise.

La concurrence demande le même soin. Deux sessions peuvent modifier le même workflow entre la sauvegarde et l’écriture. Demande à l’agent de relire la version juste avant une modification importante et de signaler toute différence. Une correction atomique réduit ce risque sans l’annuler.

Enfin, traite les données d’exécution comme des données potentiellement sensibles. Une erreur peut contenir un email, un document ou une réponse complète d’API. Limite la conservation dans n8n, filtre ce que le tool renvoie et ne copie pas ces données dans un ticket public.

Ce que cet expert ne saura jamais décider seul

n8n a retiré le label preview des réglages MCP au niveau de l’instance avec la version 2.34, publiée le 4 août 2026. La fonction est donc sortie de sa phase d’essai, mais ses tools, leurs paramètres et les versions minimales continuent de bouger d’une release à l’autre. La date de vérification de cet article compte autant que ses commandes. Relis les documentations officielles avant une migration ou un déploiement sensible.

Les Skills réduisent les erreurs de convention. Ils ne connaissent ni ton contrat client, ni ta base légale, ni la signification réelle d’un statut dans ton CRM. L’agent peut construire un workflow parfaitement valide qui envoie le mauvais message à la bonne personne.

Il ne peut pas davantage confirmer seul qu’une API externe a accepté une écriture après un timeout, qu’un credential possède les bons droits ou qu’une réponse HTTP respecte l’expérience attendue par l’application appelante. Il lui faut des tests observables et une règle humaine pour les décisions irréversibles.

Cette méthode complète bien l’AI Workflow Builder de n8n. Le Builder accélère la création depuis le canvas. Claude Code et Codex ajoutent un environnement plus large : Skills, fichiers d’instructions, API, sauvegardes, scripts et boucle de diagnostic. Le meilleur choix dépend du niveau de contrôle dont tu as besoin.

La matrice avant de lui confier un vrai workflow

Passe cette dernière série de contrôles avec un workflow sans conséquence métier :

Quand cette matrice passe, l’agent a gagné le droit de travailler sur un workflow plus sérieux. Il ne devient pas expert parce qu’un prompt le déclare. Il le devient parce qu’il consulte les définitions actuelles, suit une méthode, teste ses hypothèses et laisse derrière lui assez de preuves pour que tu puisses reprendre la main.