Aller au contenu principal

Accéder au serveur MCP n8n

Connectez des clients MCP pris en charge à vos workflows n8n via le serveur MCP intégré de n8n.

Ce serveur permet à des clients comme Lovable ou Claude Desktop de se connecter en toute sécurité à votre instance n8n. Une fois connectés, ces clients peuvent :

  • rechercher parmi les workflows marqués comme disponibles dans MCP ;
  • récupérer les métadonnées des workflows et leurs informations de déclenchement ;
  • déclencher et exécuter les workflows rendus accessibles.

Différence entre l’accès MCP à l’échelle de l’instance et le nœud MCP Server Trigger​

L’accès MCP à l’échelle de l’instance vous permet de créer une connexion par instance n8n, avec une authentification centralisée, puis de choisir quels workflows sont accessibles. Les workflows activés peuvent être facilement trouvés et exécutés, sans configuration distincte pour chaque workflow.

À l’inverse, le nœud MCP Server Trigger se configure dans un seul workflow. Ce nœud n’expose à MCP que les outils de ce workflow, ce qui est utile lorsque vous souhaitez personnaliser un comportement spécifique du serveur MCP dans un workflow donné.

Points importants lors de l’utilisation de l’accès MCP à l’échelle de l’instance​

  • Il ne s’agit pas d’un moyen de créer ou de modifier des workflows via un client IA ; la création des workflows se fait toujours dans n8n.
  • Cette fonctionnalité n’expose pas automatiquement tous les workflows de l’instance : vous devez d’abord activer MCP au niveau de l’instance, puis l’activer individuellement pour chaque workflow.
  • La portée n’est pas différenciée par client MCP : tout client connecté peut voir tous les workflows que vous avez activés pour l’accès MCP.

Activer l’accès MCP​

Pour les instances Cloud et auto-hébergées​

  1. Accédez à Settings > Instance-level MCP
  2. Activez Enable MCP access (droits de propriétaire d’instance ou d’administrateur requis).

enable-mcp-access.png

Une fois activé, vous verrez :

  1. la liste des workflows accessibles aux clients MCP ;
  2. la liste des clients OAuth connectés ;
  3. l’interrupteur principal MCP permettant d’activer ou de désactiver l’accès au niveau de l’instance ;
  4. le bouton Connection details, qui affiche des instructions détaillées pour connecter un client MCP.

mcp_page_content.png

Désactiver : désactivez simplement l’interrupteur principal MCP.

Pour les utilisateurs auto-hébergés : désactivation complète​

Pour supprimer complètement cette fonctionnalité, définissez la variable d’environnement suivante :

N8N_DISABLED_MODULES=mcp

Cette action supprimera les points de terminaison MCP et masquera tous les éléments d’interface associés.

Configurer l’authentification MCP​

La fenêtre Connection details propose deux options d’authentification pour les clients MCP :

  • OAuth2
  • Access Token

mcp_connect_menu.png

Utiliser OAuth2​

Copiez l’URL du serveur de votre instance depuis l’onglet OAuth et utilisez-la pour configurer votre client MCP. Une fois la connexion lancée, le client vous redirigera vers n8n pour autoriser l’accès.

Révoquer l’accès d’un client​

Pour révoquer l’accès d’un client MCP déjà connecté :

  1. Accédez à Settings > Instance-level MCP.
  2. Ouvrez l’onglet Connected clients ; vous y verrez un tableau des clients OAuth connectés.
  3. Utilisez le menu d’actions sur la ligne du client concerné pour révoquer son accès.

mcp_revoke_client_access.png

Utiliser un jeton d’accès​

Utilisez l’URL du serveur de votre instance ainsi que le jeton d’accès MCP personnel récupéré dans l’onglet Access Token du menu Connection details.

Lors de votre premier accès à la page Instance-level MCP, n8n génère automatiquement pour votre compte un jeton d’accès MCP personnel associé à votre compte utilisateur.

Attention

Copiez immédiatement votre jeton. Lors des consultations suivantes, vous ne verrez qu’une valeur masquée et le bouton de copie sera désactivé.

Rotation du jeton​

Si vous avez perdu votre jeton ou si vous devez le renouveler :

  1. Accédez à Settings > Instance-level MCP.
  2. Cliquez sur le bouton en haut à droite pour ouvrir le menu Connection details.
  3. Ouvrez l’onglet Access Token.
  4. Utilisez le bouton situé à côté de la valeur masquée du jeton pour générer un nouveau jeton.

Lorsque vous générez un nouveau jeton, n8n révoque le précédent.

  1. Mettez à jour tous les clients MCP connectés avec cette nouvelle valeur.

mcp_rotate_token.png

Rendre des workflows accessibles aux clients MCP​

Conditions d’éligibilité d’un workflow​

Pour qu’un workflow soit accessible à un client MCP, il doit remplir les conditions suivantes :

  1. être publié ;
  2. contenir l’un des nœuds déclencheurs suivants :
    • Webhook
    • Schedule
    • Chat
    • Form

Par défaut, aucun workflow n’est visible par les clients MCP. Vous devez activer explicitement l’accès pour chaque workflow éligible que vous souhaitez rendre accessible.

Lors de l’évaluation de l’éligibilité d’un workflow, n8n ne prend en compte que sa version publiée. Si un déclencheur pris en charge est ajouté dans la version brouillon d’un workflow, celui-ci ne sera pas considéré comme éligible tant que cette version ne sera pas publiée.

Attention

Lorsqu’un workflow n’est plus publié, n8n supprime son accès MCP. Si vous republiez le workflow, vous devrez réactiver l’accès.

Activer l’accès​

Méthode 1 : depuis la page des paramètres MCP (disponible à partir de n8n v2.2.0)​

  1. Cliquez sur le bouton Enable workflow (affiché dans l’en-tête du tableau des workflows ou dans l’état vide du tableau)
  2. Recherchez le workflow cible (par nom ou description), puis sélectionnez-le dans la liste
  3. Cliquez sur le bouton Enable pour confirmer

Méthode 2 : depuis l’éditeur de workflow​

  1. Ouvrez le workflow.
  2. Cliquez sur le menu principal du workflow en haut à droite (...).
  3. Sélectionnez Settings.
  4. Activez Available in MCP.

Méthode 3 : depuis la liste des workflows​

  1. Accédez à Workflows.
  2. Ouvrez le menu sur la carte du workflow.
  3. Sélectionnez Enable MCP access.

Gérer l’accès​

La page de paramètres Instance-level MCP affiche tous les workflows disponibles pour les clients MCP. Depuis cette liste, vous pouvez :

  • ouvrir directement le workflow, son projet ou son dossier parent ;
  • révoquer l’accès via le menu d’actions (ou utiliser Disable MCP access dans le menu de la carte du workflow) ;
  • mettre à jour la description du workflow via le menu d’actions (ou via le menu dans l’éditeur de workflow) ;
  • utiliser le bouton Enable workflow pour autoriser davantage de workflows (disponible à partir de n8n v2.2.0).

Description du workflow​

Pour aider les clients MCP à identifier un workflow, vous pouvez ajouter une description libre comme suit :

  1. Méthode 1 : depuis la page Instance-level MCP

    1. Accédez à Settings > Instance-level MCP.
    2. Assurez-vous d’être dans l’onglet Workflows.
    3. Utilisez le menu d’actions sur la ligne du workflow cible et sélectionnez l’action Edit description.
    4. Vous pouvez aussi cliquer directement sur le texte de la description pour ouvrir la fenêtre d’édition.

  2. Méthode 2 : depuis l’éditeur de workflow

    1. Ouvrez le workflow.
    2. Cliquez sur le menu principal du workflow en haut à droite (...).
    3. Sélectionnez Edit description.

mcp_workflow_description.png

Exécuter un workflow via un client MCP​

Les clients MCP peuvent exécuter des workflows éligibles en fonction de votre demande. Lorsqu’un client déclenche un workflow, celui-ci s’exécute dans n8n comme d’habitude, et vous pouvez en suivre l’exécution dans la liste Executions. Une fois l’exécution terminée, le client MCP récupère le résultat.

Fournir des données d’entrée​

Les clients MCP sont généralement capables de déterminer les données d’entrée requises par un workflow. Si vous utilisez un déclencheur Webhook et constatez que le client a du mal à déterminer les bonnes données d’entrée, il est recommandé de fournir ces informations dans la description du workflow.

Délai d’expiration du workflow​

n8n impose un délai d’expiration de 5 minutes pour l’exécution des workflows déclenchés par des clients MCP. Si le workflow ne se termine pas à temps, n8n interrompt l’exécution et envoie une erreur au client MCP, en ignorant le délai d’expiration que vous avez défini dans les paramètres du workflow pour les exécutions déclenchées par MCP.

Limites​

  • Si un workflow contient plusieurs déclencheurs pris en charge, le client MCP peut n’en utiliser qu’un seul (le premier) pour déclencher le workflow.
  • L’exécution des workflows comportant des formulaires en plusieurs étapes ou tout autre flux nécessitant une interaction humaine n’est pas prise en charge.
  • Les données d’entrée binaires ne sont pas prises en charge ; les clients MCP ne peuvent fournir au workflow que des entrées textuelles.

Exemples​

Connecter Lovable au serveur MCP n8n​

  1. Configurez le serveur MCP dans Lovable (OAuth).
    • Accédez à Settings > Integrations dans votre espace de travail.
    • Dans la section MCP Servers, trouvez n8n puis cliquez sur Connect.
    • Saisissez l’URL de votre serveur n8n (affichée sur la page MCP access).
    • Enregistrez la connexion. Si elle réussit, n8n vous redirigera pour autoriser l’accès à Lovable.
  2. Vérifiez la connexion.
    • Une fois connecté, Lovable peut interroger les workflows pour lesquels l’accès MCP a été activé.
    • Exemple : demandez à Lovable de créer une interface utilisateur pour un workflow qui liste les utilisateurs et permet de supprimer un utilisateur.

Connecter Claude Desktop au serveur MCP n8n​

Utiliser OAuth2​
  1. Dans Claude Desktop, accédez à Settings > Connectors.
  2. Cliquez sur Add custom connector.
  3. Saisissez les informations suivantes :
    • Nom : n8n MCP
    • Remote MCP server URL : l’URL de base de votre n8n (affichée sur la page Instance-level MCP)
  4. Enregistrez le connecteur.
  5. Lorsque vous y êtes invité, autorisez Claude Desktop à accéder à votre instance n8n.
Utiliser un jeton d’accès​

Attention

Cette opération nécessite la dernière version de Node.js.

Ajoutez l’entrée suivante à votre fichier claude_desktop_config.json :

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--streamableHttp",
        "https://<YOUR_N8N_HOST>/mcp-server/http",
        "--header",
        "authorization: Bearer <YOUR_TOKEN>"
      ]
    }
  }
}

Remplacez :

  • <YOUR_N8N_HOST> : l’URL de base de votre n8n (affichée sur la page Instance-level MCP)
  • <YOUR_TOKEN> : le jeton que vous avez généré

Connecter Claude Code au serveur MCP n8n​

Utilisez la commande CLI suivante :

claude mcp add --transport http n8n-mcp https://<YOUR_N8N_HOST>/mcp-server/http \
  --header "Authorization: Bearer <YOUR_TOKEN>"

Ou ajoutez l’entrée suivante à votre fichier claude.json en remplaçant également les placeholders par les valeurs décrites ci-dessus.

Connecter Codex CLI au serveur MCP n8n​

Ajoutez l’entrée suivante à votre fichier ~/.codex/config.toml :

[mcp_servers.n8n_mcp]
command = "npx"
args = [
    "-y",
    "supergateway",
    "--streamableHttp",
    "https://<YOUR_N8N_HOST>/mcp-server/http",
    "--header",
    "authorization:Bearer <YOUR_TOKEN>"
]

(Utilisez l’URL de base de votre n8n et le jeton généré pour remplacer les placeholders correspondants.)

Connecter un agent Google ADK au serveur MCP n8n​

Voici un exemple de code permettant de créer un agent connecté à un serveur MCP n8n distant :

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPServerParams

N8N_INSTANCE_URL = "https://localhost:5678"
N8N_MCP_TOKEN = "YOUR_N8N_MCP_TOKEN"

root_agent = Agent(
    model="gemini-2.5-pro",
    name="n8n_agent",
    instruction="Help users manage and execute workflows in n8n",
    tools=[
        McpToolset(
            connection_params=StreamableHTTPServerParams(
                url=f"{N8N_INSTANCE_URL}/mcp-server/http",
                headers={"Authorization": f"Bearer {N8N_MCP_TOKEN}"},
            ),
        )
    ],
)

Pour plus de détails, consultez Connect ADK agent to n8n.

Dépannage​

Si vous rencontrez des problèmes lors de la connexion d’un client MCP à votre instance n8n, vérifiez les points suivants :

  • Si vous utilisez un client MCP basé sur le cloud, assurez-vous que votre instance n8n est accessible publiquement.
  • Vérifiez que l’accès MCP est bien activé dans les paramètres n8n.
  • Vérifiez que le workflow auquel vous voulez accéder est bien marqué comme disponible dans MCP.
  • Assurez-vous que la méthode d’authentification du client MCP (OAuth2 ou jeton d’accès) est correctement configurée.
  • Consultez les logs du serveur n8n pour voir s’il existe des erreurs liées à la connexion MCP.
  • Si vous utilisez un client MCP de bureau, assurez-vous que la dernière version de Node.js est installée.