README.md
# n8n Multi-Instance Skill
Expert guidance for accounts where one n8n-mcp connection reaches several n8n instances — naming the
target instance on each call with the `instance` argument, setting the default with
`n8n_instances` `switch`, verifying the target before high-stakes work, and recovering from
misroutes. Only relevant when the account has multi-instance mode on (the `n8n_instances` tool is
present); single-instance accounts never need it.
---
## The core problem this skill solves
In multi-instance mode, one MCP connection reaches several n8n instances (e.g. `prod`, `staging`,
or one per client). A call that doesn't name its instance goes to the connection's **default** —
and on hosted connectors (claude.ai) that default is shared by every chat and agent on the
connection, so a `switch` in one chat silently moves the others. There is no error when you operate
on the wrong instance: you read the wrong data, or get a `NOT_FOUND` that looks like a deletion.
The fix is to **name the instance on the call**: every n8n tool takes an optional
`instance: "<name>"` that routes only that call and changes nothing for anyone else. That is what
lets several agents work on different instances at the same time.
| | Get it right | Get it wrong |
|---|---|---|
| Read | `instance` named → data from the instance you meant | Unnamed → whatever the shared default points at; wrong/empty data or a `NOT_FOUND` that looks like a deletion |
| Credential write | `instance` named → the secret lands exactly there, never `INSTANCE_AMBIGUOUS` | Unnamed → the default, which another chat may have switched |
| Parallel agents | Each agent names its instance on every call | Agents `switch` and overwrite each other's target |
| Recovery | Retry with the right `instance` | Recreating an object that already exists on another instance |
---
## What This Skill Teaches
### Core concepts
1. **Discover names** — `n8n_instances({mode:"list"})` → `current`/`default`/`available`
2. **Name the instance on every call that matters** — `instance:"<name>"`, case-insensitive, stateless
3. **Unknown names fail closed** — `INSTANCE_NOT_FOUND` with the `available` names; never a silent fallback
4. **`switch` sets the shared default** — only for unnamed calls; its own turn; it moves every chat on a hosted connection
5. **Credential writes name the instance** — a named write is never `INSTANCE_AMBIGUOUS`
6. **NOT_FOUND ≈ misroute, not deletion** — retry with the right `instance`; never recreate
7. **Older servers** — no `instance` property in the tool schemas → switch in its own turn and verify `current`
### Top traps this skill prevents
1. Agents in parallel chats switching the shared default and editing each other's instances
2. Treating a `NOT_FOUND` as "it was deleted" and recreating an object that lives on another instance
3. Writing a credential to whatever instance another chat last switched to
4. Dropping the `instance` argument after `INSTANCE_NOT_FOUND`, which silently runs the call on the default
5. Racing a `switch` against dependent work in the same parallel tool-call batch
---
## Skill Activation
Activates when:
- The `n8n_instances` tool is available (multi-instance mode is on)
- The user mentions multiple n8n instances/environments (prod vs staging, several teams/clients)
- Several agents or chats work on one account at the same time
- A call returns an unexpected `NOT_FOUND`, wrong/empty data, `INSTANCE_NOT_FOUND` or `INSTANCE_AMBIGUOUS`
- You're about to create/update/delete a credential on a multi-instance account
**Example queries**:
- "I have a prod and a staging n8n — create this credential on staging, not prod."
- "I'm running three agents at once, one per client instance — keep them from stepping on each other."
- "`n8n_get_workflow` says NOT_FOUND but I can see the workflow in the UI. What's wrong?"
- "How do I copy a workflow from one of my n8n instances to another?"
- "`n8n_list_workflows` is showing workflows I don't recognize."
---
## File Structure
### SKILL.md
The full skill content — loaded when the skill activates.
- What multi-instance mode is, and when to ignore this skill
- Golden rules (discover, name the instance, fail-closed names, switch only for the default, credential writes, NOT_FOUND≈misroute)
- The `instance` argument: value, scope, fail-closed cases, availability
- The `n8n_instances` tool: modes, real response shapes, the real error envelope
- Mental model: named vs unnamed calls, who shares the default, deleted-instance fallback
- Recovery playbook (symptom → cause → fix)
- Credential operations as the highest-stakes case
- Copy-between-instances without switching; quick reference; cross-skill integration
This skill is self-contained in one file — no reference files — because the surface is small and
the rules are tightly coupled.
---
## Quick Reference
```
# See instances
n8n_instances({ mode: "list" }) → { current, default, available:[{id,name,url,isDefault,isCurrent}], hint }
# Target one call (preferred)
n8n_list_workflows({ instance: "staging" })
n8n_manage_credentials({ action: "create", ..., instance: "staging" })
# Change the default for unnamed calls (own turn; shared by every chat on a hosted connection)
n8n_instances({ mode: "switch", name: "staging" }) → { previous, current }
```
Errors: `INSTANCE_NOT_FOUND` (named instance unknown — pick from `available`), `INSTANCE_AMBIGUOUS`
(unnamed credential write on a session that never chose a target — retry with `instance`), and the
`n8n_instances` codes `UNKNOWN_INSTANCE`, `NAME_REQUIRED`, `MULTI_INSTANCE_DISABLED`, `NO_SESSION`,
`UNKNOWN_MODE`, `INVALID_CONTEXT`.
---
## Integration with Other Skills
**n8n-mcp-tools-expert**: owns the `n8n_manage_credentials` tool (CRUD, `getSchema`) and the
secrets-via-credential-system rule. This skill adds the "which instance?" layer on top.
**using-n8n-mcp-skills**: the router — names which skill owns each step of a build.
---
## Success Metrics
After using this skill, you should be able to:
- [ ] List instances and use their exact names
- [ ] Name the instance on every call of a task, including credential writes
- [ ] Run several agents on one connection without them moving each other's target
- [ ] Recover from `INSTANCE_NOT_FOUND` and `INSTANCE_AMBIGUOUS` correctly
- [ ] Diagnose an unexpected `NOT_FOUND` as a misroute and recover without recreating anything
- [ ] Copy a workflow or credential between instances without switching
---
## Version
**Version**: 2.0.0
**Compatibility**: n8n-mcp servers exposing the `n8n_instances` tool (multi-instance mode). The
per-call `instance` argument needs hosted backend 0.1.120+ / n8n-mcp 2.94.0+; on older servers the
skill falls back to `switch`. On single-instance accounts the tool is absent and this skill does not
apply.
---
**Remember**: name the instance on the call. The default is shared, a wrong target is usually
silent, and a named call is the only target nobody else can move.
SKILL.md
---
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`).
- `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:
```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) and **retry the write with `instance:"<that name>"`**. (On a server without
the `instance` argument, run `n8n_instances({mode:"switch", name:"…"})` on this session, then retry.)
## How targeting behaves (mental model)
- **A named call** goes to the named instance, full stop. It's stateless: it neither reads nor
changes the default.
- **An unnamed call** goes to the default: the last `switch` on this connection, else the account
default.
- **Who shares the default depends on the client.** A hosted connector (claude.ai, and anything that
spreads one chat over many MCP sessions) keeps **one default per connection**, shared by every
chat and agent on it. A direct client with a stable MCP session (Claude Code, Cursor) keeps a
default per terminal, but can fall back to the connection's last switch after a reconnect. Either
way, other work can move your default — that is why rule 2 says to name the instance.
- A `switch` persists across reconnects, idle and backend deploys (~24h, the MCP session lifetime).
- **Reads and non-credential writes** without `instance` route to the default silently — a misroute
produces wrong data or a `NOT_FOUND`, not an error.
- **If the default instance is deleted** (the user removes it mid-session), unnamed calls silently
fall back to the **account default** — no error. Named calls to a deleted instance fail with
`INSTANCE_NOT_FOUND`.
## Switching (only when you need to change the default)
Use `switch` when the user asks to change "the" instance, or on an older server without the
`instance` argument.
```
1. n8n_instances({mode:"switch", name:"prod"}) # its own turn
→ returns { previous, current }; confirm current.name == "prod"
2. (then, in a later turn) the unnamed calls
3. Before a credential write: n8n_instances({mode:"list"}) → re-confirm current, then write
```
Never batch the switch with the work that depends on it, and remember it moves every chat sharing
the connection.
## Recovery playbook
| Symptom | What it usually means | Do this |
|---|---|---|
| `INSTANCE_NOT_FOUND` | The `instance` name is wrong (typo, guess, or the instance was removed) | Pick a name from the error's `available` list and retry. Never drop `instance` to "make it work" — that silently runs it on the default. |
| `INSTANCE_AMBIGUOUS` on a credential create/update/delete | An unnamed secret write on a session that never chose a target | Retry the write with `instance:"<target>"` (the error names `lastSelected` and `default` — pick the one you want). 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 | Retry with `instance` set to where it lives (check names with `list`). **Do not recreate the object.** |
| A read returns **empty or unfamiliar** data | An unnamed call went to a default someone else moved, or fell back after your instance was deleted | Re-run the read with `instance:"<name>"` before drawing conclusions. |
| `UNKNOWN_INSTANCE` on `switch` | The `name` is wrong | Read the `available` names in the error and switch to one of those. |
| `n8n_health_check` reports an `instanceName` you didn't expect | Your unnamed calls are going somewhere else | Name the instance on your calls (or `switch` if you own the connection). `n8n_health_check({instance:"…"})` confirms a name resolves. |
To confirm where unnamed calls go, read `current` from `n8n_instances({mode:"list"})` (primary).
`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**. So:
- **Name the instance on every credential create/update/delete:**
`n8n_manage_credentials({action:"create", …, instance:"client-a"})`. Take the name from `list` —
a named write to the wrong instance still writes there.
- Without `instance`, the write goes to the default, which other chats may have moved. The server
only catches the *ambiguous* case (`INSTANCE_AMBIGUOUS`); an unnamed write after someone else's
explicit switch goes through to their instance.
- Credential **reads** (`action:"list"`/`"get"`/`"getSchema"`) don't write a secret, but a read off
the wrong instance returns the wrong schema or list — name the instance there too.
- 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. read the source on A: n8n_get_workflow({id:"…", instance:"A"})
(credentials: n8n_manage_credentials({action:"get", id:"…", instance:"A"}))
2. create it on B: n8n_create_workflow({…, instance:"B"})
(credentials: n8n_manage_credentials({action:"create", …, instance:"B"}))
3. verify on B: n8n_get_workflow({id:"<new id>", instance:"B"})
```
No switching, so nothing can move the target between the read and the write. n8n doesn't return
credential secret values, so for a credential the user supplies them again for the create on B.
## Quick reference
- See instances: `n8n_instances({mode:"list"})` → `{ current, default, available, hint }`
- Target one call: add `instance:"<name>"` to any n8n tool call — preferred
- Change the default for unnamed calls: `n8n_instances({mode:"switch", name:"<name>"})`, its own turn; shared by every chat on a hosted connection
- `INSTANCE_NOT_FOUND` → use a name from the error's `available` list
- `INSTANCE_AMBIGUOUS` (unnamed credential write) → retry with `instance:"<target>"`
- Unexpected `NOT_FOUND` → retry with the right `instance`; **do not recreate**
- No `instance` property in the tool schemas → older server: `switch` in its own turn, verify `current` before credential writes
## 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.