Route n8n operations across multiple instances safely

This skill governs working with multiple n8n instances reachable through a single MCP connection - when the n8n_instances tool is present, one MCP connection can reach several n8n instances (e.g. prod, staging, or one per client/team), and 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, etc.) runs against whichever instance the current session is targeting, with no per-call instance argument - the target changes only by switching. Targeting the wrong instance usually returns wrong data or lands a write in the wrong place with no error at all (the sole exception being an ambiguous credential write, which fails closed). If n8n_instances isn't present, the account is single-instance and this skill doesn't apply.

Six golden rules each prevent a class of silent misroute: discover first by calling n8n_instances({mode:"list"}) before acting to see instance names and the current one; switch by name to the target instance before working on a non-default one, matching case-insensitively; switch in its own turn, never batching a switch with a dependent operation in the same parallel tool-call batch, since batched calls have no guaranteed order and the dependent call can resolve against the previous instance before the switch's session state is visible; verify current is the intended instance immediately before high-stakes operations like credential create/update/delete or destructive workflow edits, since the system only fail-closes the ambiguous credential case - an explicit switch to the wrong instance still writes there silently; treat an unexpected NOT_FOUND as almost always a wrong-instance misroute rather than a deletion, and re-check and retry instead of recreating the object; and on INSTANCE_AMBIGUOUS, switch on the current session to confirm the target, then retry, rather than working around it.

The n8n_instances tool has two modes: {mode:"list"} returns current, default, and available (every instance with an isCurrent flag) with no side effects - match instances by name, never hard-code id; {mode:"switch", name:"<name>"} returns previous and current and binds the session to the named instance case-insensitively. Its error envelope always returns {error: "<CODE>", message, ...}: UNKNOWN_INSTANCE means the name matched nothing (pick from the available list and retry), NAME_REQUIRED means switch was called with no name, MULTI_INSTANCE_DISABLED means there's nothing to switch (use n8n tools directly), NO_SESSION means the request has neither an MCP session id nor a credential id (reconnect and switch), UNKNOWN_MODE means mode wasn't list or switch, and INVALID_CONTEXT signals a server bug worth reporting. Instance names can never be "default", "current", "list", or "switch" since those are reserved.

INSTANCE_AMBIGUOUS is a separate, higher-stakes error returned not by n8n_instances but by the credential-write path itself: when calling n8n_manage_credentials to create/update/delete a credential and the session never switched on its own but inherited a switch made elsewhere (a fan-out or reconnect) pointing at a non-default instance, the server blocks the write entirely - it never reaches n8n and no quota is charged - and returns the error with lastSelected (the inherited switch) and default (the account default) so the caller can decide which instance to explicitly switch to before retrying.

The mental model for targeting: a switch binds the current session to the chosen instance, persisting for the rest of the session and surviving reconnects, idle time, and backend deploys for roughly the 24-hour MCP session lifetime, so re-switching before every call isn't needed; other sessions are independent and unaffected by a switch here; one session targets one instance at a time with no per-call override; reads and non-credential writes route to the currently-selected instance silently, so a misroute produces wrong data or a NOT_FOUND rather than an error; credential writes are the one guarded case, failing closed only on the specific ambiguous-session state, not as a substitute for manually verifying current; and if the selected instance is deleted mid-session, the next call silently falls back to the default instance with no error, which can look like "my data vanished."

A recovery playbook maps symptoms to fixes: INSTANCE_AMBIGUOUS on a credential write means switching explicitly then retrying (never blindly); NOT_FOUND for something known to exist means checking and switching to the right instance rather than recreating the object; empty or unfamiliar read data means checking current and re-reading; UNKNOWN_INSTANCE on switch means using one of the error's listed available names; an unexpected instanceName from n8n_health_check means switching to the intended instance; and repeated misroutes within one turn usually mean a switch was batched with dependent work and needs splitting into separate turns. After any recovery switch, n8n_instances({mode:"list"})'s current field is the primary confirmation signal, with n8n_health_check's details.instanceName as a secondary one that can be absent on some paths.

Credential operations are the highest-stakes case since they hold live secrets: the server only automatically protects the specific ambiguous-session scenario, so a credential write on a session that did switch goes through to wherever it switched with no second guess - meaning current must be verified immediately before the write, in the same short sequence, not steps earlier where a later switch could have moved the session. Credential reads (list/get/getSchema) aren't gated and don't write a secret, but still return wrong data if the instance is wrong. To copy a credential or workflow between instances: switch to the source and read it, switch to the destination as its own separate call, re-confirm current, then create - never overlapping the destination switch with the create call, and switching explicitly before any credential write so it isn't ambiguous.

Use whenever one MCP connection can target multiple n8n instances, before any instance-specific reads or writes, and whenever results suggest the session is aimed at the wrong environment. Resolve the target by stable instance ID, verify it with a read-only health check, and state the resolved environment before mutations; require explicit confirmation for credential create/update/delete operations, never print secret values, and stop on ambiguous targeting rather than guessing. If n8n_instances isn't available, the account is single-instance and this skill doesn't apply.

Input is an MCP session with the n8n_instances tool available and a target instance name. Output is a session correctly bound to the intended instance, confirmed via n8n_instances({mode:"list"})'s current field before any read, write, or especially credential operation.

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", ...})

n8n-mcp-tools-expert (owns n8n_manage_credentials's CRUD shapes and getSchema, plus the rule that secrets go through the credential system, never text fields - this skill adds the "which instance?" layer on top), and using-n8n-mcp-skills as the router for which skill owns a given build step.

n8n workflow builders operating an MCP connection against multiple instances (prod/staging, or per-client/team) who need to avoid silent misroutes, especially on credential writes where a mistargeted write puts a secret on the wrong environment.