n8n-multi-instance

Files (2)

• README.md
• SKILL.md

SKILL.md (first lines)

# 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`).
  - `available` is every instance, each with an extra `isCurrent` boolean. Match by **`name`**;
    never hard-code `id`.
- `{mode:"switch", name:"<name>"}` → `{ previous, current }`, and sets the default for calls that
  don't name an 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` | `switch` `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 — or just name the `instance` on each call. |
| `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)

Returned when you call `n8n_manage_credentials` (or an `n8n_manage_agents` write) **without**
`instance`, and the default this call inherited is ambiguous: this session never switched on its own
but picked up a switch made elsewhere, 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:

From czlonkowski/n8n-skills, MIT.

More from czlonkowski/n8n-skills