n8n Multi-Instance SkillSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

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

```json
{
  "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`).
  - `avai

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: n8n Multi-Instance Skill](https://modelsatlas.com/skills/czlonkowski/n8n-multi-instance/badge.svg)](https://modelsatlas.com/skills/czlonkowski/n8n-multi-instance/)

Not your listing, or something out of date? Claim or update your listing.