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).

There are two ways to say which instance a call should hit:

• Name it on the call — every n8n tool (n8n_get_workflow, n8n_list_workflows, n8n_update_partial_workflow, n8n_manage_datatable, n8n_manage_credentials, n8n_executions, n8n_test_workflow, n8n_health_check, …) takes an optional instance: "<name>". It routes that one call and changes nothing else. Prefer this.
• Set the default with switch — n8n_instances({mode:"switch", name}) sets the instance used by calls that don't name one.

The default is shared more widely than it looks. On claude.ai (and other hosted connectors) one connection serves every chat and agent using it, so a switch in one chat moves all the others too — and their next unnamed call silently lands on your instance. A wrong target is usually silent: a read returns the wrong data and a write lands in the wrong place. So name the instance.

If the n8n_instances tool is not present, the account is single-instance: ignore this skill and use the n8n tools directly.

Availability. The instance argument needs hosted n8n-mcp backend 0.1.120+ / n8n-mcp 2.94.0+. It is there when the n8n tools' input schemas list an instance property (and the n8n_instances list output carries a hint about it). If it isn't listed, the server predates it: fall back to switch, in its own turn, as described under Switching.

Golden rules

1. Discover first. Call n8n_instances({mode:"list"}) so you know the exact instance names and which one is current. Never guess a name.
2. Name the instance on every call when it matters — whenever you work on more than one instance, on any instance other than current, or alongside other agents/chats on the same account: n8n_list_workflows({instance:"prod"}). Names are case-insensitive. Pass the name the same way on every call of the task; there is nothing to "set up" first.
3. An instance you name is never silently replaced. An unknown name fails with INSTANCE_NOT_FOUND and lists the available names — pick one from that list and retry. It never falls back to another instance.
4. Use switch only to change the default, and only when you're the sole user of the connection. Switch in its own turn — never in the same parallel batch as a call that depends on it (batch order isn't guaranteed).
5. Credential writes: name the instance. n8n_manage_credentials({action:"create", …, instance:"prod"}). A named write is explicit, so it is never INSTANCE_AMBIGUOUS. Check the name against list first — naming the wrong instance writes the secret there.
6. An unexpected NOT_FOUND is almost always a wrong-instance misroute, not a deletion. Don't recreate the object. Retry with instance set to where it lives (see Recovery).