/n8n-multi-instance

name: n8n-multi-instance
description: 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), several agents or chats work on one account in parallel, a workflow / datatable / credential / execution call returns an unexpected NOT_FOUND or reads data you don't recognize, or a call is refused with `INSTANCE_AMBIGUOUS` or `INSTANCE_NOT_FOUND`. Covers naming the target instance on each call with the `instance` argument, setting the default with `switch`, verifying the target before high-stakes work — credential writes above all — and recovering from misroutes and fail-closes. Always consult this skill before operating on a specific instance, before any credential create/update/delete on a multi-instance account, or when a call hits the wrong/empty data or an instance error.

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

Core workflow

1. n8n_instances({mode:"list"})                        # names, current, default
2. n8n_list_workflows({instance:"client-a"})            # read on client-a
3. n8n_get_workflow({id:"…", instance:"client-b"})      # read on client-b — no switch needed
4. n8n_update_partial_workflow({id:"…", operations:[…], instance:"client-b"})
5. Credential write:
   n8n_manage_credentials({action:"create", name:"…", type:"…", data:{…}, instance:"client-a"})

Every call names its target, so it doesn't matter what any other chat switched to in between, and calls can safely run in the same parallel batch even when they target different instances.

The `instance` argument

• **Value:** an instance **name** from `n8n_instances` `list` (`available[].name`), matched

case-insensitively. Not the id, not the URL — the same URL can be registered under several names.

• **Scope:** routes only the call that carries it. It does **not** change `current` or the default

for anyone.

• **Omitted (or empty):** the call uses the default — the last `switch` on this connection, or the

account default.

• **Fails closed** with `INSTANCE_NOT_FOUND` (the call never reaches n8n, no quota charged) when:
• the name matches no instance — the error lists `available`;
• the value isn't a string;
• multi-instance mode is off and the name isn't the one instance the connection reaches.

{
  "error": "INSTANCE_NOT_FOUND",
  "message": "No n8n instance named \"clinet-a\". Pass one of the available names as `instance`, …",
  "available": ["client-a", "client-b"]
}

`n8n_instances` itself doesn't take `instance` — it has its own `name` argument for `switch`.

The `n8n_instances` tool

Two modes (`mode` is required and enum-validated):

• `{mode:"list"}` → `{ current, default, available, hint }`, no side effects.
• `current` and `default` are each one instance `{ id, name, url, isDefault }` (or `null`).
• `available` is every in