在 n8n-mcp 多实例账号下安全选择与切换目标实例（避免…

当 n8n-mcp 账号连接多个 n8n 实例（存在 n8n_instances 工具）时，如何选择、切换、验证当前目标实例，并在误路由或 INSTANCE_AMBIGUOUS 报错后恢复。

适用场景

解决思路

1. 先发现再操作：调用 n8n_instances({mode:"list"}) 获取实例名称列表以及哪个是 current。
2. 在非默认实例上工作前，按名称切换到目标实例：n8n_instances({mode:"switch", name:"<instance name>"})，名称匹配不区分大小写。
3. 切换必须单独占一个回合：绝不要把 switch 和依赖它的操作放在同一个并行工具调用批次里，因为同批次调用没有顺序保证，依赖调用可能仍按切换前的实例解析；先 switch、等它返回，再操作。
4. 高风险操作前先验证：在创建/更新/删除凭据（以及破坏性工作流编辑）之前，立即用 n8n_instances({mode:"list"}) 确认 current 是预期实例；系统只对“模糊”凭据写入做 fail-close，显式切到错误实例仍会静默写入，所以这一步必须自己做。
5. 遇到意外的 NOT_FOUND 时，几乎总是切错了实例而不是对象被删除：不要重建对象，重新检查当前实例并重试。
6. 遇到 INSTANCE_AMBIGUOUS 时，在“本会话”上执行 switch 确认目标，然后重试写入；不要绕过或盲目重试。
7. 核心工作流：1) n8n_instances({mode:"list"}) 查看 available[]、current、default；2) n8n_instances({mode:"switch", name:"prod"}) 把本会话绑定到 "prod"，返回 { previous, current }，确认 current.name == "prod"；3) 执行工作（n8n_list_workflows / n8n_get_workflow / n8n_manage_datatable 等）；4) 凭据写入或删除前，先 n8n_instances({mode:"list"}) 重新确认 current，再调用 n8n_manage_credentials({action:"create", ...})。
8. n8n_instances 的 list 模式：{mode:"list"} 返回 { current, default, available }，无副作用；current 和 default 各是一个实例 { id, name, url, isDefault }（或 null）；available 是全部实例，每个额外带 isCurrent 布尔值；按 name 匹配，绝不硬编码 id。
9. n8n_instances 的 switch 模式：{mode:"switch", name:"<name>"} 返回 { previous, current }，并把本会话绑定到指定实例；name 不区分大小写。
10. 处理 n8n_instances 工具的错误信封（每个错误返回 { error: "<CODE>", message, … }）：UNKNOWN_INSTANCE（name 不匹配任何实例）→ 从错误载荷的 available 列表里选一个名称重试；NAME_REQUIRED（switch 未带 name）→ 带上 name 重新调用（错误里会列出可用名称）；MULTI_INSTANCE_DISABLED（多实例模式关闭）→ 无需切换，直接使用 n8n 工具，用户可在 n8n-mcp dashboard 启用；NO_SESSION（请求既无 MCP session id 也无 credential id）→ 选择无处落地，需重连/初始化会话后再切换；UNKNOWN_MODE（mode 不是 list/switch）→ 使用 list 或 switch；INVALID_CONTEXT（服务端元数据缺失）→ 是服务端 bug 而非输入问题，上报即可。
11. 注意实例名称永远不会是 default、current、list、switch（保留字），所以不会看到以模式或字段命名的实例。
12. 理解 INSTANCE_AMBIGUOUS：它不由 n8n_instances 返回，而是调用 n8n_manage_credentials 创建/更新/删除凭据时，目标实例模糊（本会话自己从未切换，却继承了别处做的切换，指向非默认实例）时由服务端返回；服务端会阻止写入（不会到达 n8n，不计配额），返回 { error: "INSTANCE_AMBIGUOUS", message, lastSelected, default }；修复方式是决定真正想要的实例（lastSelected 是继承来的切换，default 是账号默认），在“本会话”上运行 n8n_instances({mode:"switch", name:"…"})，然后重试写入。
13. 理解目标绑定模型：switch 把本会话绑定到所选实例，绑定在会话剩余时间内持续，并能跨重连、空闲和后端部署存活（约 24 小时，即 MCP 会话生命周期），无需每次调用前重新切换；其他会话/终端相互独立，此处切换不会移动它们；一个会话同一时间只指向一个实例，没有按调用传实例的参数，只能通过 switch 改变目标。
14. 理解路由行为：读取和非凭据写入会静默路由到当前所选实例，误路由产生错误数据或 NOT_FOUND 而非报错；凭据写入是唯一受保护的情况，路由方式相同，但服务端会对“模糊”状态（本会话从未切换、恢复后落在非默认实例）以 INSTANCE_AMBIGUOUS fail-close，这是安全网而非规则 4 的替代。
15. 处理所选实例被删除的情况：如果用户会话中途删除所选实例，下一次调用会静默回退到 default 实例且无报错；因此本应属于另一实例的数据出现在 default 上，看起来像“我的数据消失了”，需重新 list 确认自己在哪。
16. 恢复手册：凭据创建/更新/删除时 INSTANCE_AMBIGUOUS → 本会话从未自己切换，系统不愿猜把密钥写到哪个实例，运行 n8n_instances({mode:"switch", name:"<target>"})（错误里给出 lastSelected 和 default，选你要的那个）后重试写入，绝不盲目重试；已知存在的 workflow/datatable/credential 返回 NOT_FOUND → 指向了错误实例而非被删除，n8n_instances({mode:"list"}) 检查 current，若不是目标就 switch 后重试，不要重建对象；读取返回空或陌生数据 → 错误实例读取，或实例被删除后静默回退到 default，先 list 确认 current，必要时 switch，重新读取后再下结论；switch 时 UNKNOWN_INSTANCE → name 写错（拼写错误或猜测），读错误里的 available 名称并切换到其中之一，名称不区分大小写；n8n_health_check 报告了意外的 instanceName → 本会话在你以为之外的实例上，switch 到预期实例再继续；同一回合内反复误路由 → 你把 switch 和依赖工作批处理了，拆开：单独 switch、等待结果，然后一次一个逻辑步骤地操作。
17. 任何恢复性切换之后，用 n8n_instances({mode:"list"})（读 current）作为主要信号做健全性检查；n8n_health_check 也会在 details.instanceName 下返回解析出的实例，但在某些路径（legacy/chat）可能缺失，只能作为次要确认。
18. 凭据操作（最高风险）：凭据持有实时密钥，误路由的凭据写入会把密钥放到错误实例；服务端自动保护“模糊”情况（本会话从未选目标却继承了指向非默认实例的切换时，写入以 INSTANCE_AMBIGUOUS fail-close，永不到达 n8n），但这张网很窄：已切换会话上的凭据写入会直接落到它切换到的实例，没有二次确认；因此要在 n8n_manage_credentials 创建/更新/删除前“紧接着”验证 current——在同一短序列里调用 n8n_instances({mode:"list"})，而不是在 10 步之前（之后可能有切换把你移走）；遇到 INSTANCE_AMBIGUOUS 就在本会话 switch 确认目标后重试，不要绕过；凭据读取（action:"list"/"get"/"getSchema"）不受门控、不写密钥，但读错实例会返回错误的 schema 或列表，所以结果看起来不对时仍要验证 current；n8n_manage_credentials 工具本身（CRUD 形态、getSchema 发现、绝不把密钥内联到文本字段）参见 n8n-mcp-tools-expert。
19. 跨实例复制任务的步骤：1) switch → A，读取源（n8n_manage_credentials get / n8n_get_workflow）；2) switch → B（单独调用，绝不与下面的 create 批处理）；3) n8n_instances({mode:"list"}) 确认 current == B；4) 在 B 上创建（n8n_manage_credentials create / n8n_create_workflow）；每个实例的步骤各占自己的回合，绝不把 switch → B 与在 B 上创建重叠，并在凭据写入前显式在本会话切换以免模糊。
20. 快速参考：查看实例与当前位置用 n8n_instances({mode:"list"}) → { current, default, available }；改变目标用 n8n_instances({mode:"switch", name:"<name>"})（单独回合，然后操作）；确认目标用 list 的 current（主要），n8n_health_check 的 details.instanceName（次要，可能缺失）；UNKNOWN_INSTANCE → 切换到错误 available 列表中的名称后重试；INSTANCE_AMBIGUOUS（凭据写入）→ 在本会话 switch 确认目标后重试；意外 NOT_FOUND → 验证实例、切换、重试，不要重建；凭据写入前 → 重新 list、确认 current、再写入（fail-close 只覆盖模糊情况）。

适用边界 · 注意事项

• 如果 n8n_instances 工具不存在，账号是单实例：忽略本技能，直接使用 n8n 工具。
• 不要在同一并行工具调用批次里同时放 switch 和依赖它的操作。
• 不要在遇到意外 NOT_FOUND 时重建对象，也不要盲目重试 INSTANCE_AMBIGUOUS 的写入。