# Multi-Instance Overview

Learn how to manage multiple n8n environments (production, staging, development) from a single MCP server.

---

## What is Multi-Instance?

Multi-instance support allows you to connect to and manage multiple n8n environments simultaneously:

- **Production** - Live workflows serving real users
- **Staging** - Pre-production testing environment
- **Development** - Local development and experimentation
- **Custom** - Any additional environments (QA, UAT, demo, etc.)

### Single vs Multi-Instance

=== "Single-Instance"

    **Configuration:** `.env` file

    ```bash
    N8N_HOST=https://n8n.example.com
    N8N_API_KEY=your_key
    ```

    **Use Case:**
    - Personal projects
    - Single environment
    - Simple setups

=== "Multi-Instance"

    **Configuration:** `.config.json` file

    ```json
    {
      "environments": {
        "production": {
          "n8n_host": "https://prod.n8n.example.com",
          "n8n_api_key": "prod_key"
        },
        "staging": {
          "n8n_host": "https://staging.n8n.example.com",
          "n8n_api_key": "staging_key"
        },
        "development": {
          "n8n_host": "http://localhost:5678",
          "n8n_api_key": "dev_key"
        }
      },
      "defaultEnv": "development"
    }
    ```

    **Use Case:**
    - Team collaboration
    - Multiple environments
    - Professional workflows

---

## Benefits

### 1. Environment Isolation

**Test safely:**
- Develop workflows in development
- Test in staging
- Deploy to production
- No risk to production data

### 2. Team Collaboration

**Separate concerns:**
- Developers: work in development
- QA: test in staging
- Ops: manage production
- Each team member uses appropriate environment

### 3. Workflow Promotion

**Lifecycle management:**
```
Development → Staging → Production

1. Create workflow in dev
2. Test in dev
3. Clone to staging
4. QA validation in staging
5. Deploy to production
6. Monitor in production
```

### 4. Simplified Management

**Single interface:**
- One Claude Desktop configuration
- One MCP server instance
- Manage all environments
- Switch between instances easily

---

## Architecture

### Configuration Hierarchy

```
.config.json (primary)
    ↓
EnvironmentManager (singleton)
    ↓
N8NApiWrapper (per instance)
    ↓
n8n REST API (per environment)
```

### Component Roles

**ConfigLoader:**
- Discovers and loads configuration
- Supports `.config.json` and `.env`
- Validates structure
- Priority: `.config.json` > `.env` > environment variables

**EnvironmentManager:**
- Singleton pattern
- Manages multiple API instances
- Routes requests to correct environment
- Caches connections for performance

**N8NApiWrapper:**
- One instance per environment
- Encapsulates n8n REST API
- Handles authentication
- Provides unified interface

---

## How It Works

### Request Flow

```
Claude: "List workflows in production"
    ↓
MCP Server receives request
    ↓
Parse instance parameter: "production"
    ↓
EnvironmentManager.getInstance()
    ↓
Route to production N8NApiWrapper
    ↓
GET https://prod.n8n.example.com/api/v1/workflows
    ↓
Return workflows from production
```

### Default Instance

If no instance specified, uses `defaultEnv`:

```
Claude: "List workflows"
    ↓
No instance parameter
    ↓
Use defaultEnv from .config.json
    ↓
Route to default environment
```

### Instance Discovery

Claude AI automatically discovers available instances:

```
User: "What n8n instances do you have?"

Claude reads .config.json:
- production (default)
- staging
- development

Response: Lists all 3 instances
```

---

## Use Cases

### Development Workflow

```
1. Create workflow in development
   → "Create workflow in development"

2. Test locally
   → "List executions from development"

3. Promote to staging
   → "Clone workflow 5 from development to staging"

4. QA testing in staging
   → "Activate workflow in staging"

5. Deploy to production
   → "Clone workflow from staging to production"
```

### Multi-Team Setup

**Developer Team:**
- Primary: `development` instance
- Testing: Local n8n (localhost:5678)
- Push to staging when ready

**QA Team:**
- Primary: `staging` instance
- Validate workflows
- Approve for production

**Operations Team:**
- Primary: `production` instance
- Monitor executions
- Manage live workflows

### Geographic Distribution

```json
{
  "environments": {
    "us-east": {
      "n8n_host": "https://n8n-us-east.example.com",
      "n8n_api_key": "us_east_key"
    },
    "eu-west": {
      "n8n_host": "https://n8n-eu-west.example.com",
      "n8n_api_key": "eu_west_key"
    },
    "asia-pacific": {
      "n8n_host": "https://n8n-apac.example.com",
      "n8n_api_key": "apac_key"
    }
  },
  "defaultEnv": "us-east"
}
```

---

## Migration Path

### From Single to Multi-Instance

**Step 1: Current Setup (Single)**

```bash
# .env
N8N_HOST=https://n8n.example.com
N8N_API_KEY=your_key
```

**Step 2: Create Multi-Instance Config**

```bash
# Create .config.json
cat > .config.json << 'EOF'
{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.example.com",
      "n8n_api_key": "your_key"
    }
  },
  "defaultEnv": "production"
}
EOF
```

**Step 3: Test**

```
List workflows
# Should work exactly as before
```

**Step 4: Add More Environments**

```json
{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.example.com",
      "n8n_api_key": "prod_key"
    },
    "development": {
      "n8n_host": "http://localhost:5678",
      "n8n_api_key": "dev_key"
    }
  },
  "defaultEnv": "development"
}
```

**Step 5: Remove .env**

```bash
# Backup first
cp .env .env.backup

# Remove (optional, .config.json takes priority anyway)
rm .env
```

---

## Configuration Priority

```
.config.json (highest priority)
    ↓
.env file
    ↓
Environment variables (lowest priority)
```

**Why this order:**
- `.config.json` enables multi-instance
- `.env` for backward compatibility
- Environment variables for CI/CD or Docker

---

## Next Steps

- **[Configuration Guide](configuration.md)** - Detailed configuration instructions
- **[Environment Manager](environment-manager.md)** - Architecture details
- **[Instance Routing](instance-routing.md)** - How routing works
- **[Testing Guide](testing.md)** - Validate multi-instance setup
- **[Examples](examples.md)** - Real-world scenarios

---

!!! success "Why Multi-Instance?"
    Multi-instance support provides professional workflow management with environment isolation, team collaboration, and safe testing practices.