Use when an n8n-mcp account targets more than one n8n instance — i.e. the `n8n_instances` tool is available, the user mentions multiple n8n instances or environments (prod vs staging, several teams or clients), a workflow / datatable / credential / execution call returns an unexpected NOT_FOUND or r

Working with multiple n8n instances over MCP When the n8n instances tool is available, the user has multi instance mode on: one MCP connection can reach several n8n instances (e.g. prod , staging , or one per client/team). Every other n8n tool ( n8n get workflow , n8n list workflows , n8n update partial workflow , n8n manage datatable , n8n manage credentials , n8n executions , n8n test workflow , …) runs against whichever instance this session is currently targeting . There is no per call instance argument: you change the target only by switching. Target the wrong instance and a read returns the wrong data and a write lands in the wrong place — usually with no error (the one exception is an ambiguous credential write, which fails closed; see below). So target deliberately. If the n8n instances tool is not present, the account is single instance: ignore this skill and use the n8n tools directly. Golden rules Six rules. Each prevents a class of silent misroute. 1. Discover first. Call n8n instances({mode:"list"}) before acting so you know the instance names and which one is current . 2. Switch by name to your target before doing work on a non default instance: n8n instances({mode:"switch", name:"<instance name "}) . The match is case insensitive. 3. Switch in its own turn. Never put a switch and a dependent operation in the same parallel tool call batch . Calls in one batch have no guaranteed order, so the dependent call can be resolved against the previous instance before the switch's session state is visible. Switch, let it return, then operate. 4. Verify before high stakes ops. Immediately before creating/updating/deleting credentials (and before destructive workflow edits), confirm current is the instance you intend — primary check is n8n instances({mode:"list"}) . The system fail closes only the ambiguous credential case (rule 6); an explicit switch to the wrong instance still writes there silently, so this check is on you. 5. An unexpected NOT FOUND is almost always a wrong instance misroute, not a deletion. Don't recreate the object. Re check the current instance and retry (see Recovery). 6. On INSTANCE AMBIGUOUS , switch on this session, then retry. The system is refusing to write a secret because this session never picked a target itself. Comply — run switch here to confirm the instance, then retry the write. Don't work around it or retry blindly. Core workflow To move to another instance, just switch again. The whole session follows the switch. The n8n instances tool Two modes ( mode is required and enum validated): {mode:"list"} → { current, default, available } , no side effects. current and default are each one instance { id, name, url, isDefault } (or null ). available is every instance, each with an extra isCurrent boolean. Match by name ; never hard code id . {mode:"switch", name:"<name "} → { previous, current } , and binds this session to the named instance. name is case insensitive. Error envelope (from the n8n instances tool) Every error returns { error: "<CODE ", message, … } . The ones you'll actually hit: Code When What to do UNKNOWN INSTANCE name matches no instance Pick a name from the available list in the error payload and retry. NAME REQUIRED switch with no name Re call with a name (the error lists the valid ones in available ). MULTI INSTANCE DISABLED multi instance mode is off There's nothing to switch; use the n8n tools directly. The user can enable it at the n8n mcp dashboard. NO SESSION the request has neither an MCP session id nor a credential id A selection has nowhere to land. Reconnect / initialize a session, then switch. UNKNOWN MODE mode wasn't list / switch Use list or switch . INVALID CONTEXT server side metadata missing A server bug, not your input — report it. Instance names can never be default , current , list , or switch (reserved), so you'll never see an instance literally named after a mode or field. INSTANCE AMBIGUOUS (from the credential write path, not the tool) A separate, higher stakes error. It is not returned by n8n instances — it's returned by the server when you call n8n manage credentials to create/update/delete a credential and the target instance is ambiguous: this session never switched on its own but inherited a switch made elsewhere (a fan out / reconnect), pointing at a non default instance. Rather than risk writing a secret to the wrong instance, the server blocks the write (it never reaches n8n, no quota is charged) and returns: Fix: decide which instance you actually want ( lastSelected is the inherited switch, default is the account default), run n8n instances({mode:"switch", name:"…"}) on this session, then retry the write. See rule 6. How targeting behaves (mental model) A switch binds this session to the chosen instance. The binding persists for the rest of the session and survives reconnects, idle, and backend deploys (~24h, the MCP session lifetime) — you should not need to re switch before every call. Other sessions / terminals are independent : switching here does not move them. One session targets one instance at a time . There is no per call instance argument; you change the target only via switch . Reads and non credential writes route to the currently selected instance, silently — a misroute produces wrong data or a NOT FOUND , not an error. Credential writes are the one guarded case. They route the same way, except the server fail closes the ambiguous state (a session that never switched, recovered onto a non default instance) with INSTANCE AMBIGUOUS . This is a safety net, not a substitute for rule 4: an explicit switch to the wrong instance still writes there. If your selected instance is deleted (the user removes it mid session), the next call silently falls back to your default instance — no error. So default's data appearing where you expected another instance's can look like "my data vanished." Re list to see where you are. Recovery playbook Symptom What it usually means Do this INSTANCE AMBIGUOUS on a credential create/update/delete This session never switched itself; the system won't guess which instance to write the secret to Run n8n instances({mode:"switch", name:"<target "}) on this session (the error names lastSelected and default — pick the one you want), then retry the write. Never retry blindly. NOT FOUND for a workflow/datatable/credential you know exists You're pointed at the wrong instance — not that it was deleted n8n instances({mode:"list"}) → check current . If it's not your target, switch and retry. Do not recreate the object. A read returns empty or unfamiliar data Wrong instance read, or a silent fallback to default after your instance was deleted n8n instances({mode:"list"}) , confirm current , switch if needed, re read before drawing conclusions. UNKNOWN INSTANCE on switch The name is wrong (typo, or you guessed) Read the available names in the error and switch to one of those. Names are case insensitive. n8n health check reports an instanceName you didn't expect This session is on a different instance than you think switch to the intended instance, then proceed. Repeated misroutes within one turn You batched a switch with dependent work Split them: switch alone, await the result, then operate one logical step at a time. After any recovery switch, sanity check with n8n instances({mode:"list"}) (read current ) as the primary signal. n8n health check also returns the resolved instance under details.instanceName , but it can be absent on some paths (legacy/chat), so treat it as a secondary confirmation. Credential operations (highest stakes) Credentials hold live secrets, and a misrouted credential write puts a secret on the wrong instance . The server protects the ambiguous case automatically — if this session never picked a target and inherited a switch to a non default instance, the write fails closed with INSTANCE AMBIGUOUS (rule 6) and never reaches n8n. But that net is narrow: a credential write on a session that did switch goes through to whatever instance it switched to, with no second guess. So: Verify current immediately before n8n manage credentials create/update/delete — call n8n instances({mode:"list"}) in the same short sequence, not 10 steps earlier where a later switch could have moved you. On INSTANCE AMBIGUOUS , switch on this session to confirm the target, then retry — don't work around it. Credential reads ( action:"list" / "get" / "getSchema" ) are not gated and don't write a secret, but a read off the wrong instance returns the wrong schema or list — so still verify current if the result looks wrong. For the n8n manage credentials tool itself (CRUD shapes, getSchema discovery, never inlining secrets into text fields), see n8n mcp tools expert . Common multi instance task: copy something between instances To recreate a credential or workflow from instance A on instance B: Do each instance's steps in its own turn; never overlap switch → B with the create on B call (rule 3), and switch explicitly on this session before the credential write so it isn't ambiguous (rules 4 and 6). Quick reference See instances + where you are: n8n instances({mode:"list"}) → { current, default, available } Change target: n8n instances({mode:"switch", name:"<name "}) — its own turn, then operate Confirm target: current from list (primary); details.instanceName from n8n health check (secondary, may be absent) UNKNOWN INSTANCE → switch to a name from the error's available list, then retry INSTANCE AMBIGUOUS (credential write) → switch on this session to confirm the target, then retry Unexpected NOT FOUND → verify the instance, switch, retry; do not recreate Before credential writes → re list , confirm current , then write (the fail close only covers the ambiguous case) Integration with other skills n8n mcp tools expert — owns n8n manage credentials (CRUD + getSchema ) and the rule that secrets go through the credential system, never text fields. This skill adds the "which instance?" layer on top. using n8n mcp skills — the router; consult it for which skill owns a given build step.

n8n-multi-instance