n8n-multi-instance

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.