Multi-Instance Mode

Run several n8n instances (prod, staging, client A, client B…) from a single MCP session. Your AI agent picks the right one for each task on its own — no reconfiguration, no second account, no juggling API keys.

At a glance

Opt-in — off by default. Existing single-instance setups behave exactly as before.
Same API key — your existing nmcp_… key (or OAuth connection) keeps working. No client-side reconfiguration.
Session-scoped — each MCP session has its own “current instance”. Parallel agents on the same key can target different instances simultaneously.
Agent-driven — the n8n_instances tool lets the AI list and switch instances based on your prompt.
Available on every plan (free / supporter / enterprise).

When to use it

You manage multiple environments (dev / staging / prod) and want your agent to deploy through them.
You're an agency running several client n8n instances and want to operate all of them from one Claude / Cursor / ChatGPT session.
You run parallel agents (e.g., two Claude Code windows) and want each on its own instance without separate accounts.
You want to compare the same workflow's behavior across instances quickly.

1. Enable multi-instance mode

Head to dashboard.n8n-mcp.com/dashboard/instances and flip the Multi-instance mode toggle in the page header.

What changes when you turn it on:

Multiple instances can stay active simultaneously (the previous flow auto-deactivated others).
The n8n_instances MCP tool becomes visible to your agent.
You can mark one instance as the default — new MCP sessions start on it.

Turning it back off prompts a confirm dialog and deactivates every active row except the default — restoring single-instance behavior cleanly.

2. Add and name your instances

From the same page, click Add Instance for each n8n you want to register. Each one needs:

A friendly name (optional — auto-derived from the URL if you skip it). Used by the agent in prompts like “deploy to staging”. 1–32 characters, letters / digits / underscores / hyphens. Reserved words (default, current, list, switch) are rejected to avoid confusing the agent.
The n8n URL (HTTPS).
Its n8n API key.

Each instance card shows: name, URL, status badges, and (in multi-instance mode) the Default badge with a star icon when applicable.

Setting the default

Open the 3-dot menu on any active, non-default instance card and pick Set as default. The badge moves immediately and every new MCP session you start lands there.

3. How the agent uses it

Once enabled, the agent sees a new tool called n8n_instances alongside the standard n8n-mcp tools. It has two modes:

List — see what's available

javascript

n8n_instances({mode: "list"})

// →
{
  "current":  { "id": "...", "name": "prod",    "url": "https://n8n.example.com" },
  "default":  { "id": "...", "name": "prod",    "url": "https://n8n.example.com", "isDefault": true },
  "available": [
    { "id": "...", "name": "prod",    "url": "https://n8n.example.com", "isDefault": true,  "isCurrent": true  },
    { "id": "...", "name": "staging", "url": "https://staging.example", "isDefault": false, "isCurrent": false }
  ]
}

Switch — change the current selection

javascript

n8n_instances({mode: "switch", name: "staging"})

// →
{
  "previous": { "id": "...", "name": "prod",    "url": "https://n8n.example.com" },
  "current":  { "id": "...", "name": "staging", "url": "https://staging.example" }
}

After the switch, every subsequent tool call in the same MCP session targets the new instance. n8n_list_workflows lists staging's workflows. n8n_create_workflow creates there. n8n_health_check reports on staging. No re-prompting required.

You don't usually invoke the tool yourself

Just say what you want in natural language. The agent picks the right switches:

"Compare the workflow count on prod vs staging."
"Promote the 'daily-recap' workflow from staging to prod."
"Run a health check on each of my client instances and tell me which one is down."

4. Parallel sessions — each gets its own current

Open two Claude Code windows (or any two MCP clients) with the same API key. Window A switches to prod; Window B switches to staging. They don't interfere — each MCP session keeps its own current-instance selection on the backend.

Selections also persist across our deploys. We use an encrypted on-disk store so a backend restart doesn't reset which instance each session is currently on.

5. Example flow

Toggle Multi-instance mode on in the dashboard.
Add a second instance, name it staging.
Open Claude Code (or any MCP client). Ask: "List my n8n instances." → the agent calls n8n_instances({mode: "list"}) and shows you what's there.
Ask: "Switch to staging and list its workflows." → the agent runs switch then n8n_list_workflows.
Ask: "Now switch back to prod and deploy that one workflow." → the agent runs switch then n8n_create_workflow.

Security notes

Your nmcp_… API key now grants access to all your active instances. Treat it like an admin credential for your whole n8n estate.
The n8n_instances tool never exposes decrypted n8n API keys — only id / name / URL flow through MCP responses.
Cross-user isolation is preserved: a stored session selection is only honored if the userId matches the caller (defense in depth — MCP session IDs are UUID-suffixed and collision is astronomical, but we don't trust unverified state).

Common gotchas

The tool doesn't appear in tools/list. → Multi-instance mode is off, or your client cached the tool list at connect time. Toggle the dashboard switch, then reconnect the MCP server in your client.

I changed the default but the agent still shows the old one. → Cached for up to 5 minutes (token cache TTL). It auto-refreshes after that. Dashboard mutations also invalidate the cache, so a one-off pause + retry usually shows the new state immediately.

“NO_SESSION” error on switch. → The MCP client didn't send a session ID on the call. This should never happen for tools/call per the MCP protocol — if you see it, reconnect the client.

Switching to an instance I just deleted. → Falls back to the default, the agent's next list reflects the updated set.