n8n Multi-Instance Targeting

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

1. n8n_instances({mode:"list"})                      # see available[] + current + default
2. n8n_instances({mode:"switch", name:"prod"})       # bind THIS session to "prod"
   → returns { previous, current }; confirm current.name == "prod"
3. (do your work) n8n_list_workflows / n8n_get_workflow / n8n_manage_datatable / ...
4. Before a credential write or a delete:
   n8n_instances({mode:"list"})  → re-confirm current, THEN n8n_manage_credentials({action:"create", ...})

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:

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:

{
  "error": "INSTANCE_AMBIGUOUS",
  "message": "… the session issuing this request never switched there itself … Re-run n8n_instances({mode:\"switch\", name:\"…\"}) on this session to confirm the target …",
  "lastSelected": { "id": "…", "name": "…" },
  "default":      { "id": "…", "name": "…" }
}

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.