Trabalhando com múltiplas instâncias n8n sobre MCP

Quando Usar

Use esta habilidade sempre que uma conexão MCP puder ter como alvo múltiplas instâncias n8n, antes de leituras ou escritas específicas da instância, e sempre que os resultados sugerirem que a sessão tem como alvo o ambiente errado.

Resolva o alvo por ID de instância estável, verifique-o com uma verificação de integridade somente leitura e declare o ambiente resolvido antes das mutações. Exija confirmação explícita para operações de criação/atualização/exclusão de credenciais, nunca imprima valores secretos e pare em alvos ambíguos em vez de adivinhar.

Quando a ferramenta n8n_instances estiver disponível, o usuário terá o modo multi-instância ativado: uma conexão MCP pode alcançar várias instâncias n8n (por exemplo, prod, staging, ou uma por cliente/equipe). Todas as outras ferramentas n8n (n8n_get_workflow, n8n_list_workflows, n8n_update_partial_workflow, n8n_manage_datatable, n8n_manage_credentials, n8n_executions, n8n_test_workflow, …) são executadas contra qualquer instância que esta sessão esteja atualmente visando. Não há argumento de instância por chamada: você muda o alvo apenas alternando. Mire na instância errada e uma leitura retornará os dados errados e uma escrita cairá no lugar errado — geralmente sem erro (a única exceção é uma escrita de credencial ambígua, que falha fechada; veja abaixo). Portanto, mire deliberadamente.

Se a ferramenta n8n_instances não estiver presente, a conta é de instância única: ignore esta habilidade e use as ferramentas n8n diretamente.

Regras de Ouro

Seis regras. Cada uma impede uma classe de roteamento incorreto silencioso.

1. Descubra primeiro. Chame n8n_instances({mode:"list"}) antes de agir para que você saiba os nomes das instâncias e qual delas é current.
2. Mude pelo nome para o seu alvo antes de fazer trabalho em uma instância não padrão: n8n_instances({mode:"switch", name:"<instance name>"}). A correspondência não diferencia maiúsculas de minúsculas.
3. Mude em sua própria vez. Nunca coloque um switch e uma operação dependente na mesma chamada de ferramenta paralela. Chamadas em um lote não têm ordem garantida, então a chamada dependente pode ser resolvida contra a instância anterior antes que o estado da sessão da mudança seja visível. Mude, deixe retornar, depois opere.
4. Verifique antes de operações de alto risco. Imediatamente antes de criar/atualizar/excluir credenciais (e antes de edições destrutivas de fluxo de trabalho), confirme se current é a instância que você pretende — a verificação primária é n8n_instances({mode:"list"}). O sistema falha apenas no caso de credencial ambígua (regra 6); uma mudança explícita para a instância errada ainda escreve lá silenciosamente, então esta verificação é com você.
5. Um NOT_FOUND inesperado é quase sempre um roteamento incorreto de instância errada, não uma exclusão. Não recrie o objeto. Verifique novamente a instância atual e tente novamente (veja Recuperação).
6. Em INSTANCE_AMBIGUOUS, mude nesta sessão, depois tente novamente. O sistema está se recusando a gravar um segredo porque esta sessão nunca escolheu um alvo por si só. Cumpra — execute switch aqui para confirmar a instância, depois tente novamente a gravação. Não contorne ou tente novamente cegamente.

Fluxo de Trabalho Principal

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

Para mudar para outra instância, basta switch novamente. Toda a sessão segue a mudança.

A ferramenta n8n_instances

Dois modos (mode é obrigatório e validado por enumeração):

• {mode:"list"} → { current, default, available }, sem efeitos colaterais.
  • current e default são cada um uma instância { id, name, url, isDefault } (ou null).
  • available são todas as instâncias, cada uma com um booleano extra isCurrent. Corresponda por name; nunca codifique id.
• {mode:"switch", name:"<name>"} → { previous, current }, e vincula esta sessão à instância nomeada. name não diferencia maiúsculas de minúsculas.

Envelope de Erro (da ferramenta n8n_instances)

Todo erro retorna { error: "<CODE>", message, … }. Aqueles que você realmente encontrará:

…