n8n-multi-instance - Claude MCP Skill

# 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 / reconnect), pointing at a **non-default** instance. Rather than risk writing a secret to
the wrong instance, the server **blocks the write** (it never reaches n8n, no quota is charged) and
returns:

```json
{
  "error": "INSTANCE_AMBIGUOUS",
  "message": "… the session issuing this request never switched there itself … Re-run n8n_instances({mode:\"switch\", name:\"…\"}) on this session to confirm the target …",
  "lastSelected": { "id": "…", "name": "…" },
  "default":      { "id": "…", "name": "…" }
}
```

**Fix:** decide which instance you actually want (`lastSelected` is the inherited switch, `default`
is the account default), run `n8n_instances({mode:"switch", name:"…"})` on **this** session, then
retry the write. See rule 6.

## How targeting behaves (mental model)

- A `switch` **binds this session** to the chosen instance. The binding **persists for the rest of
  the session and survives reconnects, idle, and backend deploys** (~24h, the MCP session lifetime)
  — you should not need to re-switch before every call.
- Other sessions / terminals are **independent**: switching here does not move them.
- One session targets **one instance at a time**. There is no per-call instance argument; you
  change the target only via `switch`.
- **Reads and non-credential writes** route to the currently-selected instance, silently — a
  misroute produces wrong data or a `NOT_FOUND`, not an error.
- **Credential writes are the one guarded case.** They route the same way, except the server
  fail-closes the *ambiguous* state (a session that never switched, recovered onto a non-default
  instance) with `INSTANCE_AMBIGUOUS`. This is a safety net, not a substitute for rule 4: an
  explicit switch to the wrong instance still writes there.
- **If your selected instance is deleted** (the user removes it mid-session), the next call silently
  falls back to your **default** instance — no error. So default's data appearing where you expected
  another instance's can look like "my data vanished." Re-list to see where you are.

## Recovery playbook

| Symptom | What it usually means | Do this |
|---|---|---|
| `INSTANCE_AMBIGUOUS` on a credential create/update/delete | This session never switched itself; the system won't guess which instance to write the secret to | Run `n8n_instances({mode:"switch", name:"<target>"})` on this session (the error names `lastSelected` and `default` — pick the one you want), then retry the write. Never retry blindly. |
| `NOT_FOUND` for a workflow/datatable/credential you **know exists** | You're pointed at the wrong instance — **not** that it was deleted | `n8n_instances({mode:"list"})` → check `current`. If it's not your target, `switch` and retry. **Do not recreate the object.** |
| A read returns **empty or unfamiliar** data | Wrong-instance read, or a silent fallback to `default` after your instance was deleted | `n8n_instances({mode:"list"})`, confirm `current`, switch if needed, re-read before drawing conclusions. |
| `UNKNOWN_INSTANCE` on `switch` | The `name` is wrong (typo, or you guessed) | Read the `available` names in the error and switch to one of those. Names are case-insensitive. |
| `n8n_health_check` reports an `instanceName` you didn't expect | This session is on a different instance than you think | `switch` to the intended instance, then proceed. |
| Repeated misroutes within one turn | You batched a `switch` with dependent work | Split them: `switch` alone, await the result, then operate one logical step at a time. |

After any recovery switch, sanity-check with `n8n_instances({mode:"list"})` (read `current`) as the
primary signal. `n8n_health_check` also returns the resolved instance under `details.instanceName`,
but it can be absent on some paths (legacy/chat), so treat it as a secondary confirmation.

## Credential operations (highest stakes)

Credentials hold live secrets, and a misrouted credential write puts a secret on the **wrong
instance**. The server protects the **ambiguous** case automatically — if this session never picked
a target and inherited a switch to a non-default instance, the write fails closed with
`INSTANCE_AMBIGUOUS` (rule 6) and never reaches n8n. But that net is narrow: a credential write on a
session that **did** switch goes through to whatever instance it switched to, with no second
guess. So:

- **Verify `current` immediately before** `n8n_manage_credentials` create/update/delete — call
  `n8n_instances({mode:"list"})` in the same short sequence, not 10 steps earlier where a later
  switch could have moved you.
- **On `INSTANCE_AMBIGUOUS`**, switch on this session to confirm the target, then retry — don't
  work around it.
- Credential **reads** (`action:"list"`/`"get"`/`"getSchema"`) are not gated and don't write a
  secret, but a read off the wrong instance returns the wrong schema or list — so still verify
  `current` if the result looks wrong.
- For the `n8n_manage_credentials` tool itself (CRUD shapes, `getSchema` discovery, never inlining
  secrets into text fields), see `n8n-mcp-tools-expert`.

## Common multi-instance task: copy something between instances

To recreate a credential or workflow from instance A on instance B:

```
1. switch → A;  read the source (n8n_manage_credentials get / n8n_get_workflow)
2. switch → B   (its own call — never batched with the create below)
3. n8n_instances({mode:"list"})  → confirm current == B
4. create on B  (n8n_manage_credentials create / n8n_create_workflow)
```

Do each instance's steps in its own turn; never overlap `switch → B` with the create-on-B call
(rule 3), and switch explicitly on this session before the credential write so it isn't ambiguous
(rules 4 and 6).

## Quick reference

- See instances + where you are: `n8n_instances({mode:"list"})` → `{ current, default, available }`
- Change target: `n8n_instances({mode:"switch", name:"<name>"})` — its own turn, then operate
- Confirm target: `current` from `list` (primary); `details.instanceName` from `n8n_health_check` (secondary, may be absent)
- `UNKNOWN_INSTANCE` → switch to a name from the error's `available` list, then retry
- `INSTANCE_AMBIGUOUS` (credential write) → `switch` on this session to confirm the target, then retry
- Unexpected `NOT_FOUND` → verify the instance, switch, retry; **do not recreate**
- Before credential writes → re-`list`, confirm `current`, then write (the fail-close only covers the ambiguous case)

## Integration with other skills

- **n8n-mcp-tools-expert** — owns `n8n_manage_credentials` (CRUD + `getSchema`) and the rule that
  secrets go through the credential system, never text fields. This skill adds the "which instance?"
  layer on top.
- **using-n8n-mcp-skills** — the router; consult it for which skill owns a given build step.