/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), a workflow / datatable / credential / execution call returns an unexpected NOT_FOUND or reads data you don't recognize, or a credential create/update/delete is refused with an `INSTANCE_AMBIGUOUS` error. Covers choosing and switching which instance this MCP session targets, verifying the target before high-stakes work — credential writes above all — and recovering from misroutes and ambiguous-write 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_AMBIGUOUS` 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). 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:

| Code | When | What to do | |---|---|---| | `UNKNOWN_INSTANCE` | `name` matches no instance | Pick a name from the `available` list in the error payload and retry. | | `NAME_REQUIRED` | `switch` with no `name` | Re-call with a `name` (the error lists the valid ones in `available`). | | `MULTI_INSTANCE_DISABLED` | multi-instance mode is off | There's nothing to switch; use the n8n tools directly. The user can enable it at the n8n-mcp dashboard. | | `NO_SESSION` | the request has **neither** an MCP session id **nor** a credential id | A selection has nowhere to land. Reconnect / initialize a session, then switch. | | `UNKNOWN_MODE` | `mode` wasn't `list`/`switch` | Use `list` or `switch`. | | `INVALID_CONTEXT` | server-side metadata missing | A server bug, not your input — report it. |

> 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 / reconn