n8n-multi-instance
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.
czlonkowski · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add czlonkowski/n8n-skills --skill 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.
- Discover first. Call
n8n_instances({mode:"list"})before acting so you know the instance names and which one iscurrent. - 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. - Switch in its own turn. Never put a
switchand 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. - Verify before high-stakes ops. Immediately before creating/updating/deleting credentials
(and before destructive workflow edits), confirm
currentis the instance you intend — primary check isn8n_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. - An unexpected
NOT_FOUNDis almost always a wrong-instance misroute, not a deletion. Don't recreate the object. Re-check the current instance and retry (see Recovery). - 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 — runswitchhere 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.currentanddefaultare each one instance{ id, name, url, isDefault }(ornull).availableis every instance, each with an extraisCurrentboolean. Match byname; never hard-codeid.
{mode:"switch", name:"<name>"}→{ previous, current }, and binds this session to the named instance.nameis 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, orswitch(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