Working with multiple n8n instances over MCP

When to Use

Use this skill whenever one MCP connection can target multiple n8n instances, before instance-specific reads or writes, and whenever results suggest the session is aimed at the wrong environment.

Resolve the target by stable instance ID, verify it with a read-only health check, and state the resolved environment before mutations. Require explicit confirmation for credential create/update/delete operations, never print secret values, and stop on ambiguous targeting rather than guessing.

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:

…