┌─────────────────────────────────────────────────────────────────────────────────┐
│          Traditional n8n Development vs. n8n-mcp AI-Powered Development         │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   Traditional Approach (Pre-MCP):                    AI-Powered Approach:         │
│   ┌─────────────────────────────────┐              ┌─────────────────────────┐ │
│   │  1. Open n8n editor             │              │  1. Open Claude/Cursor  │ │
│   │  2. Drag nodes from palette     │              │  2. Describe workflow:  │ │
│   │  3. Configure each node         │              │     "Build a workflow   │ │
│   │     individually                  │              │     that monitors       │ │
│   │  4. Connect nodes manually      │              │     database changes,   │ │
│   │  5. Write expressions             │              │     posts to Slack,     │ │
│   │  6. Test and debug                │              │     and handles errors" │ │
│   │  7. Export and deploy           │              │  3. AI generates        │ │
│   │                                   │              │     complete workflow   │ │
│   │  Time: 2-4 hours                  │              │  4. Review and refine   │ │
│   │  Skill: High (expressions,        │              │  5. Deploy              │ │
│   │         node configuration)       │              │                         │ │
│   │                                   │              │  Time: 10-20 minutes    │ │
│   └─────────────────────────────────┘              │  Skill: Conversational  │ │
│                                                    └─────────────────────────┘ │
│   Result: Technical bottleneck                    Result: Democratized        │
│           for non-experts                                    automation         │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────────┐
│                    MCP Architecture Overview                                    │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   ┌──────────────────────┐                    ┌──────────────────────┐         │
│   │     MCP Host         │◄──────────────────►│    MCP Server        │         │
│   │  (AI Application)    │    stdio / HTTP    │   (Tool Provider)    │         │
│   │                      │    (bidirectional) │                      │         │
│   │  • Claude Desktop    │                    │  • n8n-mcp           │         │
│   │  • Claude Code       │                    │  • Database servers  │         │
│   │  • Cursor            │                    │  • GitHub MCP        │         │
│   │  • Windsurf          │                    │  • Slack MCP         │         │
│   └──────────────────────┘                    └──────────────────────┘         │
│                                                                                 │
│   Communication Flow:                                                           │
│   ┌────────────────────────────────────────────────────────────────────────┐ │
│   │  1. Host discovers available tools/resources from Server                │ │
│   │  2. Host sends tool invocation requests with parameters                 │ │
│   │  3. Server executes operation and returns results                       │ │
│   │  4. Host incorporates results into AI context                             │ │
│   └────────────────────────────────────────────────────────────────────────┘ │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────────┐
│                    n8n-mcp System Architecture                                │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   Layer 1: AI Coding Assistants (MCP Hosts)                                     │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│   │ Claude Code  │  │   Cursor     │  │  Windsurf    │  │Claude Desktop│       │
│   │              │  │              │  │              │  │              │       │
│   │ • Terminal   │  │ • IDE Editor │  │ • AI Native  │  │ • Chat App   │       │
│   │ • File sys   │  │ • Code gen   │  │ • Code edit  │  │ • Desktop    │       │
│   └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘       │
│          │                 │                 │                 │               │
│          └─────────────────┴─────────────────┴─────────────────┘               │
│                                    │                                            │
│                                    ▼                                            │
│   Layer 2: Model Context Protocol (stdio/HTTP transport)                      │
│   ┌────────────────────────────────────────────────────────────────────────┐  │
│   │  • JSON-RPC 2.0 message format                                            │  │
│   │  • Tool/resource discovery                                              │  │
│   │  • Bidirectional streaming                                               │  │
│   │  • Authentication: API keys, OAuth, or bearer tokens                     │  │
│   └────────────────────────────────────────────────────────────────────────┘  │
│                                    │                                            │
│                                    ▼                                            │
│   Layer 3: n8n-mcp Server                                                       │
│   ┌────────────────────────────────────────────────────────────────────────┐  │
│   │  Available Tools:                                                         │  │
│   │  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐   │  │
│   │  │ create_workflow │ │ update_workflow │ │ get_workflow            │   │  │
│   │  │                 │ │                 │ │                         │   │  │
│   │  │ list_workflows  │ │ delete_workflow │ │ duplicate_workflow      │   │  │
│   │  └─────────────────┘ └─────────────────┘ └─────────────────────────┘   │  │
│   │  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐   │  │
│   │  │ execute_workflow│ │ activate_workflow│ │ deactivate_workflow    │   │  │
│   │  │                 │ │                 │ │                         │   │  │
│   │  │ get_execution   │ │ search_workflows│ │ export_workflow         │   │  │
│   │  └─────────────────┘ └─────────────────┘ └─────────────────────────┘   │  │
│   │                                                                         │  │
│   │  Available Resources:                                                   │  │
│   │  • workflow://{id} — Read workflow JSON                              │  │
│   │  • execution://{id} — Read execution results                           │  │
│   │  • node-types — List available n8n node types                          │  │
│   └────────────────────────────────────────────────────────────────────────┘  │
│                                    │                                            │
│                                    ▼                                            │
│   Layer 4: n8n REST API Integration                                             │
│   ┌────────────────────────────────────────────────────────────────────────┐  │
│   │  • n8n instance URL configuration                                       │  │
│   │  • API key authentication                                               │  │
│   │  • Webhook trigger support                                              │  │
│   │  • Error handling and retry logic                                       │  │
│   └────────────────────────────────────────────────────────────────────────┘  │
│                                    │                                            │
│                                    ▼                                            │
│   Layer 5: Target n8n Instance                                                  │
│   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│   │   n8n        │  │   n8n        │  │   n8n        │  │   n8n        │       │
│   │  Cloud       │  │ Self-Hosted  │  │ Enterprise   │  │ Embedded     │       │
│   │              │  │              │  │              │  │              │       │
│   └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

# Set environment variable for API authentication
export N8N_API_KEY="your-secure-api-key-here"

# Or configure in your docker-compose.yml
environment:
  - N8N_API_KEY=${N8N_API_KEY}

# Global installation (recommended for Claude Desktop)
npm install -g @n8n/mcp-server

# Or use npx (no installation required)
npx -y @n8n/mcp-server

# Local installation (for Cursor/Windsurf projects)
cd your-project
npm install --save-dev @n8n/mcp-server

# Create config directory if it doesn't exist
mkdir -p ~/.config/claude-code

# Edit the MCP settings file
nano ~/.config/claude-code/settings.json

# Config location
%APPDATA%\Claude\settings.json

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@n8n/mcp-server"],
      "env": {
        "N8N_HOST": "https://your-n8n-instance.n8n.cloud",
        "N8N_API_KEY": "n8n_api_your_api_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@n8n/mcp-server"],
      "env": {
        "N8N_HOST": "http://localhost:5678",
        "N8N_API_KEY": "n8n_api_your_api_key_here"
      }
    }
  }
}

# Start Claude Code
claude

# In the Claude Code session, verify MCP tools are available
/mcp

# You should see n8n tools listed:
# - create_workflow
# - update_workflow
# - get_workflow
# - list_workflows
# - execute_workflow
# - etc.

User: Create an n8n workflow that monitors a webhook endpoint, 
      validates the payload, and sends a notification to Slack 
      if the data contains an error flag.

Claude: I'll create that webhook monitoring workflow for you. Let me build 
        it with proper validation and Slack notification.

[Claude uses n8n-mcp create_workflow tool]

Claude: ✅ Created workflow "Webhook Monitor with Slack Alerts" (ID: 1234)

   The workflow includes:
   • Webhook trigger node listening on /webhook/monitor
   • IF node validating payload structure
   • Slack message node for error notifications
   • Error handling with automatic retries
   
   Webhook URL: https://your-instance.n8n.cloud/webhook/monitor
   
   Would you like me to:
   1. Activate the workflow now?
   2. Add additional validation rules?
   3. Configure different notification channels?

User: Activate it and show me how to test it.

Claude: [Uses activate_workflow and explains testing process]

# Ask Claude to analyze an existing workflow
claude

User: Analyze workflow ID 5678 and suggest optimizations for error handling.

Claude: [Uses get_workflow to read the JSON, analyzes it, suggests improvements]

Claude: I found several areas for improvement:
   • No error handling on HTTP Request node (line 45)
   • Missing retry logic for external API calls
   • No notification on workflow failure
   
   Would you like me to refactor the workflow with these improvements?

User: Yes, implement all those improvements.

Claude: [Uses update_workflow to apply changes]

# Create multiple related workflows
User: Create three workflows for my data pipeline:
   1. Extract data from PostgreSQL hourly
   2. Transform and validate the data
   3. Load into data warehouse
   
   They should be connected so workflow 2 triggers after 1 completes.

Claude: [Creates all three workflows with proper connections and error handling]

Cursor Menu → Preferences → Cursor Settings → MCP

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@n8n/mcp-server"],
      "env": {
        "N8N_HOST": "https://your-n8n-instance.n8n.cloud",
        "N8N_API_KEY": "n8n_api_your_api_key_here"
      }
    }
  }
}

{
  "servers": [
    {
      "name": "n8n",
      "command": "npx -y @n8n/mcp-server",
      "env": {
        "N8N_HOST": "${N8N_HOST}",
        "N8N_API_KEY": "${N8N_API_KEY}"
      }
    }
  ]
}

N8N_HOST=https://your-n8n-instance.n8n.cloud
N8N_API_KEY=n8n_api_your_api_key_here

You: @n8n Create a workflow that connects to my GitHub repository, 
      watches for new issues, and creates a task in my Notion database 
      with the issue details.

Cursor: I'll create a GitHub-to-Notion integration workflow for you.

[Cursor invokes n8n-mcp tools through the chat interface]

Cursor: ✅ Created "GitHub Issues to Notion" workflow

   Components:
   • GitHub Trigger: Polls for new issues every 5 minutes
   • Set Node: Formats issue data for Notion
   • Notion Node: Creates database entry
   • Error Handling: Notifies on failure
   
   Required credentials:
   • GitHub OAuth (not configured)
   • Notion Integration Token (not configured)
   
   Would you like me to help set up these credentials?

You: @n8n Build me a complete e-commerce order processing workflow that:
   1. Receives webhook from Shopify on new orders
   2. Validates inventory in PostgreSQL
   3. Calculates shipping via ShipEngine API
   4. Creates invoice in QuickBooks
   5. Sends confirmation email via SendGrid
   6. Handles errors at each step with Slack notifications

Cursor Agent: [Works autonomously for 2-3 minutes]
   • Creating webhook endpoint
   • Setting up database query nodes
   • Configuring API integrations
   • Adding error handling branches
   • Testing connectivity

Cursor: ✅ Complete e-commerce workflow created with 12 nodes!
   
   📊 Workflow Summary:
   • 1 Webhook trigger
   • 2 Database operations
   • 3 API integrations
   • 4 Email templates
   • 2 Error handling branches
   
   All nodes configured with proper credentials.
   Ready to activate when you are.

You: @n8n Show me workflow ID 7890

Cursor: [Displays workflow JSON inline]

   Here's the webhook monitoring workflow:
   
   ```json
   {
     "name": "Monitor Webhook",
     "nodes": [
       {
         "type": "n8n-nodes-base.webhook",
         "name": "Webhook",
         ...
       }
     ]
   }

**Context-Aware Workflow Generation:**

If you're working on a project with existing code, Cursor can generate workflows that match your patterns:

---

## Windsurf Integration

Windsurf is the newest AI-powered IDE with deep agentic capabilities, designed for autonomous software development. Its Cascade feature enables multi-step workflow construction with n8n-mcp.

### Configuration

**Step 1: Open Windsurf Settings**

**Step 2: Configure n8n-mcp**

Add to your Windsurf MCP configuration:

```json
{
  "mcpServers": {
    "n8n": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@n8n/mcp-server"],
      "env": {
        "N8N_HOST": "https://your-n8n-instance.n8n.cloud",
        "N8N_API_KEY": "n8n_api_your_api_key_here"
      }
    }
  }
}

You: @n8n Create a comprehensive marketing automation workflow that:
   1. Monitors Google Sheets for new lead entries
   2. Enriches leads with Clearbit data
   3. Scores leads based on firmographic criteria
   4. Routes hot leads to Salesforce
   5. Adds warm leads to Mailchimp nurture sequence
   6. Logs everything to Airtable for reporting

Windsurf Cascade: 
   🔄 Step 1/6: Creating Google Sheets trigger...
   ✅ Google Sheets trigger configured
   
   🔄 Step 2/6: Setting up Clearbit enrichment...
   ✅ Clearbit API integration added
   
   🔄 Step 3/6: Building lead scoring logic...
   ✅ IF nodes for scoring criteria configured
   
   🔄 Step 4/6: Configuring Salesforce routing...
   ✅ Salesforce node with field mapping
   
   🔄 Step 5/6: Setting up Mailchimp sequence...
   ✅ Mailchimp automation trigger configured
   
   🔄 Step 6/6: Adding Airtable logging...
   ✅ Airtable logging with error handling
   
✅ Complete marketing automation workflow created!

   📈 Workflow Statistics:
   • 8 nodes total
   • 3 external APIs integrated
   • 2 conditional branches
   • 100% error coverage
   
   Estimated time savings: 15 hours/week

You: @n8n Here's a spec for my data sync workflow:

   SPEC: Customer Data Synchronization
   
   Trigger: Every hour via Cron
   Source: PostgreSQL customers table (last_modified > ${lastRun})
   Transform:
     - Normalize phone numbers
     - Validate email format
     - Split full_name into first_name, last_name
   Destination: HubSpot Contacts API
   Error Handling: 
     - Retry 3 times with exponential backoff
     - Alert Slack #data-ops on failure
     - Log all errors to error tracking table
   
   Build this exactly to spec.

Windsurf: [Follows spec precisely, asks clarifying questions where needed,
           implements complete workflow matching requirements]

You: @n8n Update the workflow we built yesterday to add 
      Zendesk integration for support tickets.

Windsurf: [Remembers previous workflow context, retrieves it,
           adds Zendesk node with proper field mapping]

# Edit Claude Desktop configuration
nano ~/Library/Application\ Support/Claude/config.json

# Edit config at
%APPDATA%\Claude\config.json

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@n8n/mcp-server"],
      "env": {
        "N8N_HOST": "https://your-n8n-instance.n8n.cloud",
        "N8N_API_KEY": "n8n_api_your_api_key_here"
      }
    }
  }
}

Create a support ticket automation workflow that:
1. Receives webhooks from Zendesk on new tickets
2. Uses AI to classify urgency (Critical/High/Medium/Low)
3. Looks up customer plan in database (Free/Pro/Enterprise)
4. Routes Critical + Enterprise to senior support Slack
5. Routes High + Pro/Enterprise to standard support
6. Creates Jira issue for bugs, feature request in Productboard
7. Sends auto-response email via SendGrid
8. Logs everything with execution metadata

{
  "name": "Intelligent Support Ticket Routing",
  "nodes": [
    {
      "parameters": {
        "httpMethod": "POST",
        "path": "zendesk-ticket-webhook",
        "responseMode": "responseNode"
      },
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 1,
      "position": [250, 300],
      "webhookId": "zendesk-incoming",
      "name": "Zendesk Webhook"
    },
    {
      "parameters": {
        "jsCode": "// AI Classification Logic\nconst ticket = $json.body.ticket;\nconst subject = ticket.subject.toLowerCase();\nconst description = ticket.description.toLowerCase();\n\nlet urgency = 'Low';\nconst criticalKeywords = ['outage', 'down', 'crash', 'security', 'breach', 'urgent'];\nconst highKeywords = ['broken', 'error', 'not working', 'bug', 'issue'];\n\nif (criticalKeywords.some(k => subject.includes(k) || description.includes(k))) {\n  urgency = 'Critical';\n} else if (highKeywords.some(k => subject.includes(k) || description.includes(k))) {\n  urgency = 'High';\n} else if (ticket.priority === 'urgent') {\n  urgency = 'Critical';\n}\n\nreturn [{\n  json: {\n    ...$json,\n    urgency,\n    customer_id: ticket.requester.external_id,\n    ticket_id: ticket.id,\n    subject: ticket.subject\n  }\n}];"
      },
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [450, 300],
      "name": "AI Urgency Classifier"
    },
    {
      "parameters": {
        "operation": "executeQuery",
        "query": "SELECT plan_type, account_manager FROM customers WHERE id = $1",
        "parameters": ["={{ $json.customer_id }}"]
      },
      "type": "n8n-nodes-base.postgres",
      "typeVersion": 2,
      "position": [650, 300],
      "name": "Lookup Customer Plan",
      "credentials": {
        "postgres": {
          "id": "cred-postgres-prod",
          "name": "Production DB"
        }
      }
    },
    {
      "parameters": {
        "conditions": {
          "options": {
            "caseSensitive": true,
            "leftValue": "",
            "typeValidation": "strict"
          },
          "conditions": [
            {
              "id": "critical-enterprise",
              "leftValue": "={{ $json.urgency + '-' + $json.plan_type }}",
              "rightValue": "Critical-Enterprise",
              "operator": {
                "type": "string",
                "operation": "equals"
              }
            },
            {
              "id": "high-tier",
              "leftValue": "={{ $json.urgency }}",
              "rightValue": "High",
              "operator": {
                "type": "string",
                "operation": "equals"
              }
            },
            {
              "id": "enterprise-any",
              "leftValue": "={{ $json.plan_type }}",
              "rightValue": "Enterprise",
              "operator": {
                "type": "string",
                "operation": "equals"
              }
            }
          ],
          "combinator": "or"
        }
      },
      "type": "n8n-nodes-base.if",
      "typeVersion": 2,
      "position": [850, 300],
      "name": "Priority Router"
    },
    {
      "parameters": {
        "channel": "#support-senior",
        "text": "🚨 *Critical Enterprise Ticket*\n*Customer:* {{ $json.customer_id }}\n*Plan:* {{ $json.plan_type }}\n*Urgency:* {{ $json.urgency }}\n*Subject:* {{ $json.subject }}\n*Ticket:* https://company.zendesk.com/agent/tickets/{{ $json.ticket_id }}",
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "🚨 *Critical Enterprise Ticket Requires Immediate Attention*"
            }
          },
          {
            "type": "section",
            "fields": [
              {
                "type": "mrkdwn",
                "text": "*Customer:*\n{{ $json.customer_id }}"
              },
              {
                "type": "mrkdwn",
                "text": "*Plan:*\n{{ $json.plan_type }}"
              },
              {
                "type": "mrkdwn",
                "text": "*Urgency:*\n{{ $json.urgency }}"
              },
              {
                "type": "mrkdwn",
                "text": "*Account Manager:*\n{{ $json.account_manager }}"
              }
            ]
          },
          {
            "type": "actions",
            "elements": [
              {
                "type": "button",
                "text": {
                  "type": "plain_text",
                  "text": "View Ticket"
                },
                "url": "https://company.zendesk.com/agent/tickets/{{ $json.ticket_id }}"
              }
            ]
          }
        ]
      },
      "type": "n8n-nodes-base.slack",
      "typeVersion": 2,
      "position": [1050, 200],
      "name": "Senior Support Alert"
    },
    {
      "parameters": {
        "channel": "#support-standard",
        "text": "📋 New {{ $json.urgency }} Priority Ticket\n*Subject:* {{ $json.subject }}\n*Plan:* {{ $json.plan_type }}"
      },
      "type": "n8n-nodes-base.slack",
      "typeVersion": 2,
      "position": [1050, 350],
      "name": "Standard Support Alert"
    },
    {
      "parameters": {
        "resource": "issue",
        "operation": "create",
        "project": "SUP",
        "summary": "={{ $json.subject }}",
        "description": "={{ $json.body.ticket.description }}",
        "issuetype": "Bug",
        "fields": {
          "priority": "={{ $json.urgency === 'Critical' ? 'Highest' : $json.urgency === 'High' ? 'High' : 'Medium' }}",
          "labels": ["zendesk-auto", "{{ $json.plan_type }}"]
        }
      },
      "type": "n8n-nodes-base.jira",
      "typeVersion": 1,
      "position": [1250, 250],
      "name": "Create Jira Bug"
    },
    {
      "parameters": {
        "from": "[email protected]",
        "to": "={{ $json.body.ticket.requester.email }}",
        "subject": "Re: {{ $json.subject }} - We've received your request",
        "text": "Hi there,\n\nThank you for contacting support. We've received your ticket and classified it as {{ $json.urgency }} priority.\n\nExpected response time: {{ $json.plan_type === 'Enterprise' ? '1 hour' : $json.plan_type === 'Pro' ? '4 hours' : '24 hours' }}\n\nTicket reference: #{{ $json.ticket_id }}\n\nBest regards,\nSupport Team",
        "options": {
          "categories": ["Support"]
        }
      },
      "type": "n8n-nodes-base.sendGrid",
      "typeVersion": 1,
      "position": [1450, 300],
      "name": "Auto-Response Email"
    },
    {
      "parameters": {
        "operation": "insert",
        "table": "support_automation_log",
        "columns": {
          "ticket_id": "={{ $json.ticket_id }}",
          "customer_id": "={{ $json.customer_id }}",
          "urgency": "={{ $json.urgency }}",
          "plan_type": "={{ $json.plan_type }}",
          "routed_to": "={{ $json.urgency === 'Critical' && $json.plan_type === 'Enterprise' ? 'senior' : 'standard' }}",
          "jira_issue": "={{ $('Create Jira Bug').item.json.key }}",
          "email_sent": "={{ $('Auto-Response Email').item.json.success }}",
          "created_at": "={{ $now }}"
        }
      },
      "type": "n8n-nodes-base.postgres",
      "typeVersion": 2,
      "position": [1650, 300],
      "name": "Log Execution"
    }
  ],
  "connections": {
    "Zendesk Webhook": {
      "main": [[{"node": "AI Urgency Classifier", "type": "main", "index": 0}]]
    },
    "AI Urgency Classifier": {
      "main": [[{"node": "Lookup Customer Plan", "type": "main", "index": 0}]]
    },
    "Lookup Customer Plan": {
      "main": [[{"node": "Priority Router", "type": "main", "index": 0}]]
    },
    "Priority Router": {
      "main": [
        [{"node": "Senior Support Alert", "type": "main", "index": 0}],
        [{"node": "Standard Support Alert", "type": "main", "index": 0}]
      ]
    },
    "Senior Support Alert": {
      "main": [[{"node": "Create Jira Bug", "type": "main", "index": 0}]]
    },
    "Standard Support Alert": {
      "main": [[{"node": "Create Jira Bug", "type": "main", "index": 0}]]
    },
    "Create Jira Bug": {
      "main": [[{"node": "Auto-Response Email", "type": "main", "index": 0}]]
    },
    "Auto-Response Email": {
      "main": [[{"node": "Log Execution", "type": "main", "index": 0}]]
    }
  },
  "settings": {
    "executionOrder": "v1",
    "errorWorkflow": "error-handler-workflow-id"
  }
}

Build an ELT pipeline workflow that:
1. Runs daily at 2 AM UTC via Cron
2. Extracts transactions from PostgreSQL (last 24 hours)
3. Extracts user events from MongoDB (last 24 hours)
4. Extracts exchange rates from external API
5. Transforms data: normalize currency, calculate fees, enrich with user data
6. Validates: check for nulls, duplicates, outliers
7. Loads to Snowflake data warehouse
8. On validation failure: quarantine bad records, alert data team
9. On success: notify analytics Slack, update Airflow DAG status
10. Keep full audit log of all operations

{
  "name": "Daily ELT Data Pipeline",
  "trigger": {
    "type": "n8n-nodes-base.cron",
    "cronExpression": "0 2 * * *",
    "timezone": "UTC"
  },
  "nodes": [
    {
      "name": "Pipeline Orchestrator",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "jsCode": "// Calculate time window for extraction\nconst now = new Date();\nconst yesterday = new Date(now - 24 * 60 * 60 * 1000);\nconst timeWindow = {\n  start: yesterday.toISOString(),\n  end: now.toISOString(),\n  date_only: yesterday.toISOString().split('T')[0]\n};\n\nreturn [{\n  json: {\n    pipeline_id: $execution.id,\n    run_date: timeWindow.date_only,\n    extraction_window: timeWindow,\n    status: 'started',\n    started_at: now.toISOString()\n  }\n}];"
      }
    },
    {
      "name": "Extract Transactions",
      "type": "n8n-nodes-base.postgres",
      "parameters": {
        "operation": "executeQuery",
        "query": "SELECT t.*, u.email, u.tier FROM transactions t JOIN users u ON t.user_id = u.id WHERE t.created_at >= $1 AND t.created_at < $2 AND t.status = 'completed'",
        "parameters": ["={{ $json.extraction_window.start }}", "={{ $json.extraction_window.end }}"]
      }
    },
    {
      "name": "Extract Events",
      "type": "n8n-nodes-base.mongoDb",
      "parameters": {
        "operation": "find",
        "collection": "user_events",
        "options": "{ \"timestamp\": { $gte: new Date('{{ $json.extraction_window.start }}'), $lt: new Date('{{ $json.extraction_window.end }}') } }"
      }
    },
    {
      "name": "Fetch Exchange Rates",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "https://api.exchangerate.host/latest",
        "query": {
          "base": "USD",
          "symbols": "EUR,GBP,JPY,CAD,AUD"
        },
        "options": {
          "timeout": 30000
        }
      }
    },
    {
      "name": "Transform & Enrich",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "jsCode": "// Data transformation logic\nconst transactions = $('Extract Transactions').all()[0].json;\nconst events = $('Extract Events').all()[0].json;\nconst rates = $('Fetch Exchange Rates').all()[0].json.rates;\n\nconst enriched = transactions.map(t => {\n  const rate = rates[t.currency] || 1;\n  const usdAmount = t.amount / rate;\n  const fee = calculateFee(usdAmount, t.tier);\n  \n  return {\n    ...t,\n    usd_amount: usdAmount,\n    exchange_rate: rate,\n    fee_usd: fee,\n    net_amount: usdAmount - fee,\n    event_count: events.filter(e => e.user_id === t.user_id).length,\n    _validation_status: 'pending'\n  };\n});\n\nfunction calculateFee(amount, tier) {\n  const rates = { free: 0.029, pro: 0.019, enterprise: 0.009 };\n  return amount * (rates[tier] || rates.free);\n}\n\nreturn enriched.map(e => ({ json: e }));"
      }
    },
    {
      "name": "Data Validator",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "jsCode": "// Validation rules\nconst records = $input.all();\nconst valid = [];\nconst invalid = [];\n\nfor (const record of records) {\n  const errors = [];\n  const r = record.json;\n  \n  // Rule 1: No null critical fields\n  if (!r.user_id || !r.amount || !r.currency) {\n    errors.push('MISSING_CRITICAL_FIELDS');\n  }\n  \n  // Rule 2: Amount range check\n  if (r.amount < 0 || r.amount > 1000000) {\n    errors.push('AMOUNT_OUT_OF_RANGE');\n  }\n  \n  // Rule 3: Duplicate check\n  const isDuplicate = valid.some(v => v.json.transaction_id === r.transaction_id);\n  if (isDuplicate) {\n    errors.push('DUPLICATE_TRANSACTION');\n  }\n  \n  // Rule 4: Outlier detection (amount > 5 std dev from mean)\n  const amounts = records.map(rec => rec.json.usd_amount);\n  const mean = amounts.reduce((a, b) => a + b, 0) / amounts.length;\n  const std = Math.sqrt(amounts.reduce((sq, n) => sq + Math.pow(n - mean, 2), 0) / amounts.length);\n  if (r.usd_amount > mean + 5 * std) {\n    errors.push('STATISTICAL_OUTLIER');\n  }\n  \n  if (errors.length > 0) {\n    invalid.push({\n      json: { ...r, _validation_errors: errors, _quarantine_reason: errors.join(', ') }\n    });\n  } else {\n    valid.push(record);\n  }\n}\n\nreturn [valid, invalid];",
        "mode": "runOnceForEachItem"
      }
    },
    {
      "name": "Load to Snowflake",
      "type": "n8n-nodes-base.snowflake",
      "parameters": {
        "operation": "insert",
        "table": "TRANSACTIONS_DAILY",
        "columns": "={{ Object.keys($json).join(', ') }}",
        "data": "={{ $json }}"
      }
    },
    {
      "name": "Quarantine Bad Records",
      "type": "n8n-nodes-base.postgres",
      "parameters": {
        "operation": "insert",
        "table": "data_quality_quarantine",
        "columns": {
          "pipeline_id": "={{ $json.pipeline_id }}",
          "record_data": "={{ JSON.stringify($json) }}",
          "validation_errors": "={{ $json._validation_errors.join(', ') }}",
          "quarantine_date": "={{ $now }}"
        }
      }
    },
    {
      "name": "Data Quality Alert",
      "type": "n8n-nodes-base.slack",
      "parameters": {
        "channel": "#data-quality",
        "blocks": [
          {
            "type": "header",
            "text": {
              "type": "plain_text",
              "text": "⚠️ Data Quality Alert"
            }
          },
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "Records failed validation and were quarantined."
            }
          }
        ]
      }
    },
    {
      "name": "Pipeline Complete",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "jsCode": "// Final status and metrics\nconst validCount = $('Load to Snowflake').all().length;\nconst invalidCount = $('Quarantine Bad Records').all().length;\nconst total = validCount + invalidCount;\n\nreturn [{\n  json: {\n    pipeline_id: $json.pipeline_id,\n    status: 'completed',\n    run_date: $json.run_date,\n    metrics: {\n      total_records: total,\n      valid_records: validCount,\n      invalid_records: invalidCount,\n      success_rate: ((validCount / total) * 100).toFixed(2) + '%'\n    },\n    completed_at: new Date().toISOString()\n  }\n}];"
      }
    },
    {
      "name": "Notify Analytics Team",
      "type": "n8n-nodes-base.slack",
      "parameters": {
        "channel": "#analytics",
        "text": "✅ Daily ELT Complete\nDate: {{ $json.run_date }}\nRecords: {{ $json.metrics.total_records }}\nSuccess Rate: {{ $json.metrics.success_rate }}"
      }
    },
    {
      "name": "Audit Log",
      "type": "n8n-nodes-base.postgres",
      "parameters": {
        "operation": "insert",
        "table": "pipeline_audit_log",
        "columns": {
          "pipeline_id": "={{ $json.pipeline_id }}",
          "run_date": "={{ $json.run_date }}",
          "status": "={{ $json.status }}",
          "metrics": "={{ JSON.stringify($json.metrics) }}",
          "created_at": "={{ $now }}"
        }
      }
    }
  ]
}

Create a sophisticated marketing automation workflow that:
1. Triggers when a customer abandons their cart (via Shopify webhook)
2. Checks customer lifetime value (CLV) and engagement score
3. For high-value customers: immediate personal outreach via SMS
4. For medium-value: email sequence (immediate + 24h + 72h)
5. For low-value: single email with discount code
6. Includes dynamic product recommendations based on cart + purchase history
7. Tracks conversions and attributes to correct campaign
8. Stops sequence if customer completes purchase
9. A/B tests subject lines for email variants
10. Reports daily metrics to marketing dashboard

{
  "name": "Abandoned Cart Recovery - Personalized",
  "nodes": [
    {
      "name": "Shopify Cart Abandoned",
      "type": "n8n-nodes-base.webhook",
      "parameters": {
        "httpMethod": "POST",
        "path": "cart-abandoned",
        "responseMode": "responseNode"
      }
    },
    {
      "name": "Enrich Customer Data",
      "type": "n8n-nodes-base.postgres",
      "parameters": {
        "operation": "executeQuery",
        "query": "SELECT c.*, COUNT(o.id) as total_orders, COALESCE(SUM(o.total), 0) as lifetime_value, MAX(o.created_at) as last_order_date FROM customers c LEFT JOIN orders o ON o.customer_id = c.id WHERE c.id = $1 GROUP BY c.id",
        "parameters": ["={{ $json.customer_id }}"]
      }
    },
    {
      "name": "Calculate Engagement Score",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "jsCode": "const customer = $json;\nconst daysSinceLastOrder = Math.floor((new Date() - new Date(customer.last_order_date)) / (1000 * 60 * 60 * 24));\nconst orderFrequency = customer.total_orders / Math.max(1, Math.floor(daysSinceLastOrder / 30));\n\nlet engagementScore = 0;\nengagementScore += Math.min(customer.lifetime_value / 100, 50); // Max 50 points\nengagementScore += Math.min(customer.total_orders * 5, 30); // Max 30 points\nengagementScore += orderFrequency > 1 ? 20 : orderFrequency * 10; // Max 20 points\n\nlet segment = 'low';\nif (engagementScore >= 70) segment = 'high';\nelse if (engagementScore >= 40) segment = 'medium';\n\nreturn [{\n  json: {\n    ...customer,\n    engagement_score: Math.round(engagementScore),\n    segment,\n    days_since_order: daysSinceLastOrder\n  }\n}];"
      }
    },
    {
      "name": "Segment Router",
      "type": "n8n-nodes-base.switch",
      "parameters": {
        "rules": {
          "rules": [
            { "value": "high", "output": 0 },
            { "value": "medium", "output": 1 },
            { "value": "low", "output": 2 }
          ]
        }
      }
    },
    {
      "name": "High-Value: Send SMS",
      "type": "n8n-nodes-base.twilio",
      "parameters": {
        "operation": "send",
        "to": "={{ $json.phone }}",
        "from": "+1234567890",
        "body": "Hi {{ $json.first_name }}, you left items in your cart! Complete your order now: https://shop.com/cart/{{ $json.cart_id }}?discount=VIP10"
      }
    },
    {
      "name": "High-Value: Mark VIP",
      "type": "n8n-nodes-base.postgres",
      "parameters": {
        "operation": "update",
        "table": "customers",
        "columns": {
          "priority": "vip_abandoned_cart",
          "last_touch": "={{ $now }}"
        },
        "where": "id = {{ $json.id }}"
      }
    },
    {
      "name": "Medium-Value: A/B Test",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "jsCode": "// 50/50 A/B test\nconst variant = Math.random() < 0.5 ? 'A' : 'B';\nconst subjects = {\n  A: "Don't miss out on your cart, {{ $json.first_name }}!",\n  B: "Your items are waiting (and selling fast)"\n};\n\nreturn [{\n  json: {\n    ...$json,\n    ab_variant: variant,\n    subject_line: subjects[variant]\n  }\n}];"
      }
    },
    {
      "name": "Medium: Send Email 1",
      "type": "n8n-nodes-base.sendGrid",
      "parameters": {
        "from": "[email protected]",
        "to": "={{ $json.email }}",
        "subject": "={{ $json.subject_line }}",
        "html": "<html><body><h1>Hi {{ $json.first_name }}</h1><p>You left items in your cart. <a href='https://shop.com/cart/{{ $json.cart_id }}'>Complete your order</a></p></body></html>"
      }
    },
    {
      "name": "Medium: Wait 24h",
      "type": "n8n-nodes-base.wait",
      "parameters": {
        "amount": 24,
        "unit": "hours"
      }
    },
    {
      "name": "Check Purchase Status",
      "type": "n8n-nodes-base.postgres",
      "parameters": {
        "operation": "executeQuery",
        "query": "SELECT COUNT(*) as purchased FROM orders WHERE customer_id = $1 AND created_at > $2",
        "parameters": ["={{ $json.id }}", "={{ $json.last_touch }}"]
      }
    },
    {
      "name": "Still Abandoned?",
      "type": "n8n-nodes-base.if",
      "parameters": {
        "conditions": {
          "number": [
            { "value1": "={{ $json.purchased }}", "value2": 0 }
          ]
        }
      }
    },
    {
      "name": "Medium: Send Email 2",
      "type": "n8n-nodes-base.sendGrid",
      "parameters": {
        "from": "[email protected]",
        "to": "={{ $json.email }}",
        "subject": "Still thinking it over? Here's 10% off",
        "html": "<html><body><h1>Your cart misses you</h1><p>Use code COMEBACK10 for 10% off your order: <a href='https://shop.com/cart/{{ $json.cart_id }}?discount=COMEBACK10'>Complete Purchase</a></p></body></html>"
      }
    },
    {
      "name": "Low-Value: Discount Email",
      "type": "n8n-nodes-base.sendGrid",
      "parameters": {
        "from": "[email protected]",
        "to": "={{ $json.email }}",
        "subject": "Complete your order with 15% off",
        "html": "<html><body><h1>Special offer for you</h1><p>Use code SAVE15 for 15% off: <a href='https://shop.com/cart/{{ $json.cart_id }}?discount=SAVE15'>Shop Now</a></p></body></html>"
      }
    },
    {
      "name": "Track Campaign Touch",
      "type": "n8n-nodes-base.postgres",
      "parameters": {
        "operation": "insert",
        "table": "marketing_touches",
        "columns": {
          "customer_id": "={{ $json.id }}",
          "campaign": "abandoned_cart_recovery",
          "segment": "={{ $json.segment }}",
          "channel": "email",
          "sent_at": "={{ $now }}"
        }
      }
    },
    {
      "name": "Daily Report",
      "type": "n8n-nodes-base.slack",
      "parameters": {
        "channel": "#marketing-metrics",
        "text": "📊 Daily Cart Recovery Summary\nHigh-value SMS sent: X\nMedium-value emails: Y\nLow-value emails: Z\nConversions attributed: W"
      }
    }
  ]
}

┌─────────────────────────────────────────────────────────────────────────────────┐
│                    n8n-mcp Security Architecture                                │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   Layer 1: AI Tool Authentication                                             │
│   ┌─────────────────────────────────────────────────────────────────────────┐  │
│   │  • Use dedicated API keys per AI tool instance                          │  │
│   │  • Rotate keys every 90 days                                            │  │
│   │  • Store keys in environment variables, never in config files          │  │
│   │  • Use separate n8n instances for dev/staging/production                │  │
│   └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
│   Layer 2: MCP Server Security                                                │
│   ┌─────────────────────────────────────────────────────────────────────────┐  │
│   │  • Run n8n-mcp in isolated container                                    │  │
│   │  • Limit network access to n8n instance only                           │  │
│   │  • Enable request logging and monitoring                                │  │
│   │  • Implement rate limiting (100 req/min recommended)                  │  │
│   └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
│   Layer 3: n8n API Security                                                     │
│   ┌─────────────────────────────────────────────────────────────────────────┐  │
│   │  • Use API keys with minimal permissions (read-only where possible)    │  │
│   │  • Enable IP allowlisting                                               │  │
│   │  • Implement workflow-level access controls                             │  │
│   │  • Audit all API calls                                                  │  │
│   └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
│   Layer 4: Workflow Security                                                    │
│   ┌─────────────────────────────────────────────────────────────────────────┐  │
│   │  • Review AI-generated workflows before activation                      │  │
│   │  • Implement credential vaulting (never hardcode secrets)               │  │
│   │  • Add error handling to prevent data leakage                           │  │
│   │  • Use separate credentials for dev/production                        │  │
│   └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

# Use environment variables for credentials
export N8N_API_KEY="n8n_api_$(cat /secure/path/to/key)"
export N8N_HOST="https://your-instance.n8n.cloud"

# Start Claude Code with restricted permissions
claude --allow-read ./project --allow-write ./project

# Review all MCP tool calls before execution
# Claude Code will prompt for confirmation on destructive operations

// .cursor/settings.json
{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@n8n/mcp-server"],
      "env": {
        "N8N_HOST": "${N8N_HOST}",
        "N8N_API_KEY": "${N8N_API_KEY}"
      }
    }
  },
  // Enable confirmation prompts
  "mcp.confirmDestructiveOperations": true,
  "mcp.showToolCallsInChat": true
}

// .windsurf/settings.json
{
  "mcpServers": {
    "n8n": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@n8n/mcp-server"],
      "env": {
        "N8N_HOST": "${N8N_HOST}",
        "N8N_API_KEY": "${N8N_API_KEY}"
      }
    }
  },
  // Security settings
  "mcp.requireConfirmation": true,
  "mcp.auditLogPath": "./logs/mcp-audit.json"
}

☐ No hardcoded credentials in workflow JSON
☐ No PII in test data or expressions
☐ Error handling prevents data leakage
☐ API keys use least-privilege access
☐ Webhook endpoints use authentication
☐ Workflow reviewed by human before activation
☐ Rollback plan documented
☐ Monitoring and alerting configured

Goals:
• Validate n8n-mcp with 2-3 power users
• Build 5-10 sample workflows
• Document internal best practices
• Identify security requirements

Deliverables:
• Pilot report with metrics
• Security review completion
• Initial training materials
• Go/no-go decision for Phase 2

Goals:
• Expand to full automation team
• Build workflow library (20+ templates)
• Implement governance framework
• Train team leads

Deliverables:
• Workflow catalog with documentation
• Governance policy document
• Training completion for 20+ users
• Support process established

Goals:
• Multi-department deployment
• 100+ AI-assisted workflows
• Automated testing and deployment
• Full monitoring and observability

Deliverables:
• Enterprise workflow standards
• Automated CI/CD for workflows
• Analytics dashboard
• ROI measurement

┌─────────────────────────────────────────────────────────────────────────────────┐
│                    AI-Generated Workflow Governance                            │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   Developer creates workflow via AI                                            │
│          │                                                                      │
│          ▼                                                                      │
│   ┌─────────────────────┐                                                    │
│   │ Automated Scanning  │                                                    │
│   │ • Security check    │                                                    │
│   │ • Credential scan   │                                                    │
│   │ • Policy compliance │                                                    │
│   └──────────┬──────────┘                                                    │
│              │                                                                  │
│     ┌────────┴────────┐                                                       │
│     ▼                 ▼                                                       │
│  Pass            Fail                                                         │
│     │                 │                                                       │
│     ▼                 ▼                                                       │
│ Review            Return with                                                 │
│ Queue             fixes required                                              │
│     │                                                                       │
│     ▼                                                                       │
│ Technical                                                                     │
│ Review                                                                        │
│ (Senior Dev)                                                                  │
│     │                                                                       │
│     ▼                                                                       │
│   ┌─────────────────────┐                                                    │
│   │ Production Deploy   │                                                    │
│   │ • Version control   │                                                    │
│   │ • Monitoring        │                                                    │
│   │ • Rollback plan     │                                                    │
│   └─────────────────────┘                                                    │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────────┐
│                    Multi-Agent Workflow Development                            │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   Architect Agent (Claude Code)                                               │
│   • Designs workflow structure                                                │
│   • Defines node requirements                                                 │
│   • Creates documentation                                                     │
│          │                                                                      │
│          ▼                                                                      │
│   Implementation Agent (Cursor)                                                 │
│   • Generates workflow JSON                                                   │
│   • Configures nodes and expressions                                          │
│   • Adds error handling                                                         │
│          │                                                                      │
│          ▼                                                                      │
│   Review Agent (Windsurf)                                                     │
│   • Validates against best practices                                            │
│   • Suggests optimizations                                                      │
│   • Checks security compliance                                                  │
│          │                                                                      │
│          ▼                                                                      │
│   Testing Agent (Claude Code)                                                 │
│   • Creates test scenarios                                                      │
│   • Runs validation                                                             │
│   • Reports issues                                                              │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

# Workflow repository structure
n8n-workflows/
├── workflows/
│   ├── support-automation.json
│   ├── data-pipeline.json
│   └── marketing-campaigns/
│       ├── abandoned-cart.json
│       └── welcome-series.json
├── docs/
│   ├── support-automation.md  # AI-generated documentation
│   └── data-pipeline.md
├── tests/
│   └── workflow-validator.js
└── .cursor/
    └── mcp.json

# Workflow: Support Ticket Automation

## Overview
Automatically routes support tickets based on urgency and customer tier.

## Trigger
- Webhook: `/webhook/support-incoming`
- Source: Zendesk

## Flow
1. Receive ticket webhook
2. Classify urgency via AI analysis
3. Look up customer plan
4. Route to appropriate team
5. Create Jira issue
6. Send confirmation email

## Nodes
| Node | Type | Purpose |
|------|------|---------|
| Webhook | Webhook | Entry point |
| AI Classifier | Code | Urgency detection |
| Customer Lookup | Postgres | Plan retrieval |
| Router | IF | Priority routing |

## Error Handling
- Retry: 3 attempts
- Fallback: Slack notification
- Logging: PostgreSQL

## Maintenance
- Last updated: 2026-05-19
- Owner: [email protected]

// AI-generated test suite for n8n workflow

describe('Support Ticket Automation', () => {
  test('Critical + Enterprise routes to senior support', async () => {
    const result = await executeWorkflow({
      ticket: {
        subject: 'URGENT: System outage',
        priority: 'urgent',
        requester: { external_id: 'ENT-123' }
      }
    });
    
    expect(result.routing).toBe('senior');
    expect(result.slack_channel).toBe('#support-senior');
  });
  
  test('Low priority + Free tier routes to standard', async () => {
    const result = await executeWorkflow({
      ticket: {
        subject: 'Feature question',
        priority: 'low',
        requester: { external_id: 'FREE-456' }
      }
    });
    
    expect(result.routing).toBe('standard');
  });
  
  test('Missing customer ID handles gracefully', async () => {
    const result = await executeWorkflow({
      ticket: {
        subject: 'Help needed',
        requester: { external_id: null }
      }
    });
    
    expect(result.error).toBeDefined();
    expect(result.error_handled).toBe(true);
  });
});

# 1. Verify n8n-mcp is installed
npm list -g @n8n/mcp-server

# 2. Test MCP server manually
npx @n8n/mcp-server

# 3. Check environment variables
echo $N8N_HOST
echo $N8N_API_KEY

# 4. Verify n8n API accessibility
curl -H "X-N8N-API-KEY: $N8N_API_KEY" \
     "$N8N_HOST/api/v1/workflows"

# 5. Check AI tool logs for errors
# Claude Code: ~/.claude/logs/
# Cursor: View → Output → MCP

// Common causes and fixes:

// 1. Invalid node type
// Fix: Use correct node type from n8n documentation
"type": "n8n-nodes-base.httpRequest" // Correct
"type": "http-request" // Incorrect

// 2. Missing required parameters
// Fix: Check node schema for required fields
{
  "parameters": {
    "url": "={{ $json.endpoint }}", // Required
    "method": "POST", // Required
    // "headers" is optional
  }
}

// 3. Invalid JSON in expressions
// Fix: Use proper JSON syntax
"query": "={{ JSON.stringify($json.params) }}"

// 4. Credential reference errors
// Fix: Verify credential ID exists
"credentials": {
  "slackApi": {
    "id": "valid-credential-id-here"
  }
}

# 1. Verify credentials exist in n8n
n8n credential:list

# 2. Check credential permissions
# Ensure API keys have required scopes

# 3. Test credential in n8n UI first
# Manual test before AI-generated workflow

# 4. Update credential reference in workflow
# AI may need explicit credential ID

User: "Add a delay between the email and SMS nodes, 
        and change the delay from 1 hour to 30 minutes."

AI: [Locates workflow, identifies nodes, updates delay configuration,
     maintains all other settings, commits change]

AI: "I notice this HTTP node doesn't have error handling. 
     Based on the API documentation, it has a 2% failure rate. 
     Should I add automatic retry logic?"

AI: "I've analyzed your 47 workflows. I found 12 that query 
     the same database table. I can combine these into a 
     single optimized data pipeline that reduces API calls 
     by 65%. Would you like to see the proposal?"

User: [Voice] "Create a workflow that monitors our API health 
               every five minutes and pages the team if 
               response time exceeds two seconds."

AI: [Transcribes, interprets, generates complete workflow]

┌─────────────────────────────────────────────────────────────────────────────────┐
│                    MCP Protocol Message Flow                                   │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   Phase 1: Server Discovery and Initialization                                  │
│   ┌─────────────────────────────────────────────────────────────────────────┐  │
│   │                                                                         │  │
│   │  Host ────────────► Server                                               │  │
│   │        initialize                                                       │  │
│   │        {                                                                │  │
│   │          "jsonrpc": "2.0",                                              │  │
│   │          "method": "initialize",                                        │  │
│   │          "params": {                                                    │  │
│   │            "protocolVersion": "2025-11-25",                             │  │
│   │            "capabilities": {                                            │  │
│   │              "tools": { "listChanged": true },                          │  │
│   │              "resources": { "subscribe": true }                         │  │
│   │            }                                                            │  │
│   │          }                                                              │  │
│   │        }                                                                │  │
│   │                                                                         │  │
│   │  Host ◄─────────── Server                                               │  │
│   │        {                                                                │  │
│   │          "jsonrpc": "2.0",                                              │  │
│   │          "result": {                                                    │  │
│   │            "protocolVersion": "2025-11-25",                             │  │
│   │            "serverInfo": {                                              │  │
│   │              "name": "n8n-mcp",                                         │  │
│   │              "version": "1.0.0"                                         │  │
│   │            },                                                           │  │
│   │            "capabilities": {                                            │  │
│   │              "tools": {                                                   │  │
│   │                "create_workflow": { ... },                            │  │
│   │                "execute_workflow": { ... }                              │  │
│   │              },                                                           │  │
│   │              "resources": {                                             │  │
│   │                "workflow://{id}": { ... }                             │  │
│   │              }                                                          │  │
│   │            }                                                            │  │
│   │          }                                                              │  │
│   │        }                                                                │  │
│   │                                                                         │  │
│   └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
│   Phase 2: Tool Invocation                                                      │
│   ┌─────────────────────────────────────────────────────────────────────────┐  │
│   │                                                                         │  │
│   │  Host ────────────► Server                                               │  │
│   │        tools/call                                                         │  │
│   │        {                                                                │  │
│   │          "jsonrpc": "2.0",                                              │  │
│   │          "method": "tools/call",                                        │  │
│   │          "params": {                                                    │  │
│   │            "name": "create_workflow",                                   │  │
│   │            "arguments": {                                               │  │
│   │              "name": "Webhook Monitor",                                 │  │
│   │              "nodes": [...],                                              │  │
│   │              "connections": {...}                                       │  │
│   │            }                                                            │  │
│   │          },                                                             │  │
│   │          "id": 1                                                        │  │
│   │        }                                                                │  │
│   │                                                                         │  │
│   │  Host ◄─────────── Server                                               │  │
│   │        {                                                                │  │
│   │          "jsonrpc": "2.0",                                              │  │
│   │          "result": {                                                    │  │
│   │            "content": [                                                   │  │
│   │              {                                                          │  │
│   │                "type": "text",                                          │  │
│   │                "text": "Workflow created successfully. ID: 12345"       │  │
│   │              }                                                          │  │
│   │            ],                                                           │  │
│   │            "isError": false                                             │  │
│   │          },                                                             │  │
│   │          "id": 1                                                        │  │
│   │        }                                                                │  │
│   │                                                                         │  │
│   └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
│   Phase 3: Resource Access                                                        │
│   ┌─────────────────────────────────────────────────────────────────────────┐  │
│   │                                                                         │  │
│   │  Host ────────────► Server                                               │  │
│   │        resources/read                                                     │  │
│   │        {                                                                │  │
│   │          "jsonrpc": "2.0",                                              │  │
│   │          "method": "resources/read",                                    │  │
│   │          "params": {                                                    │  │
│   │            "uri": "workflow://12345"                                    │  │
│   │          },                                                             │  │
│   │          "id": 2                                                        │  │
│   │        }                                                                │  │
│   │                                                                         │  │
│   │  Host ◄─────────── Server                                               │  │
│   │        {                                                                │  │
│   │          "jsonrpc": "2.0",                                              │  │
│   │          "result": {                                                    │  │
│   │            "contents": [{                                                │  │
│   │              "uri": "workflow://12345",                                 │  │
│   │              "mimeType": "application/json",                            │  │
│   │              "text": "{...full workflow JSON...}"                     │  │
│   │            }]                                                           │  │
│   │          },                                                             │  │
│   │          "id": 2                                                        │  │
│   │        }                                                                │  │
│   │                                                                         │  │
│   └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

// stdio transport characteristics:
// - Lowest latency
// - Process isolation
// - Automatic cleanup on parent exit
// - No network exposure

// Example stdio configuration:
{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@n8n/mcp-server"],
      "transport": "stdio"  // Explicit, though default
    }
  }
}

// SSE transport characteristics:
// - Network-accessible
// - Supports multiple concurrent clients
// - Requires authentication
// - Enables centralized logging

// Example SSE configuration:
{
  "mcpServers": {
    "n8n-enterprise": {
      "url": "https://mcp-gateway.company.com/n8n",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}

// Error handling wrapper for n8n-mcp calls
async function callN8nMcpWithRetry(toolName, args, maxRetries = 3) {
  const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
  
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const result = await callMcpTool('n8n', toolName, args);
      
      // Check for MCP-level errors
      if (result.isError) {
        throw new MCPError(result.content[0].text, result.errorCode);
      }
      
      return result;
      
    } catch (error) {
      const isRetryable = [
        '-32603',  // Internal error (might be transient)
        '1003',    // Rate limited
        'ECONNRESET',
        'ETIMEDOUT'
      ].includes(error.code);
      
      if (!isRetryable || attempt === maxRetries) {
        throw error;
      }
      
      // Exponential backoff
      const waitTime = Math.pow(2, attempt) * 1000;
      console.log(`Attempt ${attempt} failed, retrying in ${waitTime}ms...`);
      await delay(waitTime);
    }
  }
}

// Instead of building from scratch, use pre-validated templates
const workflowTemplates = {
  'webhook-processing': {
    nodes: ['webhook', 'code', 'if', 'slack'],
    defaultConfig: { ... }
  },
  'scheduled-etl': {
    nodes: ['cron', 'postgres', 'transform', 'snowflake'],
    defaultConfig: { ... }
  }
};

// AI fills in specifics while maintaining proven structure
function generateFromTemplate(templateName, customizations) {
  const base = workflowTemplates[templateName];
  return merge(base, customizations);
}

Instead of: "Create a 50-node workflow"

Use: "Create the trigger node"
     → "Add the data extraction nodes"
     → "Add transformation logic"
     → "Add output nodes"
     → "Connect everything"

Result: Faster generation, easier debugging

// Generate independent branches in parallel
const [branchA, branchB, branchC] = await Promise.all([
  generateBranch('validation'),
  generateBranch('processing'),
  generateBranch('notification')
]);

// Merge into single workflow
return mergeWorkflows([branchA, branchB, branchC]);

// Before: Sequential execution
const results = [];
for (const item of items) {
  const result = await processItem(item);
  results.push(result);
}

// After: Batch processing
const batches = chunk(items, 100);
const results = await Promise.all(
  batches.map(batch => processBatch(batch))
);

// Before: N+1 queries
const users = await getAllUsers();
for (const user of users) {
  const orders = await getUserOrders(user.id);  // N queries
}

// After: Single JOIN query
const usersWithOrders = await query(`
  SELECT u.*, json_agg(o.*) as orders
  FROM users u
  LEFT JOIN orders o ON o.user_id = u.id
  WHERE u.id IN (${userIds.join(',')})
  GROUP BY u.id
`);

{
  "name": "SOX Compliance Data Change Tracking",
  "trigger": {
    "type": "n8n-nodes-base.postgresTrigger",
    "event": [
      "INSERT",
      "UPDATE",
      "DELETE"
    ],
    "schema": "public",
    "table": "financial_records"
  },
  "nodes": [
    {
      "name": "Capture Change",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "jsCode": "const change = $json;\nconst changeType = change.__operation === 'INSERT' ? 'CREATE' : change.__operation === 'UPDATE' ? 'MODIFY' : 'DELETE';\n\nreturn [{\n  json: {\n    change_id: generateUUID(),\n    table: change.__table,\n    record_id: change.id,\n    change_type: changeType,\n    old_values: changeType === 'CREATE' ? null : change.__old,\n    new_values: changeType === 'DELETE' ? null : change.__new,\n    changed_by: change.__user,\n    changed_at: change.__timestamp,\n    requires_approval: changeType === 'DELETE' || (changeType === 'MODIFY' && change.amount !== change.__old.amount)\n  }\n}];"
      }
    },
    {
      "name": "Risk Assessment",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "jsCode": "const change = $json;\nlet riskLevel = 'LOW';\n\n// High-risk indicators\nif (change.change_type === 'DELETE') riskLevel = 'CRITICAL';\nelse if (Math.abs(change.new_values.amount - (change.old_values?.amount || 0)) > 10000) riskLevel = 'HIGH';\nelse if (change.changed_at.getHours() < 6 || change.changed_at.getHours() > 22) riskLevel = 'MEDIUM';\n\nreturn [{\n  json: {\n    ...change,\n    risk_level: riskLevel,\n    auto_approved: riskLevel === 'LOW' && change.change_type !== 'DELETE'\n  }\n}];"
      }
    },
    {
      "name": "Route by Risk",
      "type": "n8n-nodes-base.switch",
      "parameters": {
        "rules": {
          "rules": [
            { "value": "CRITICAL", "output": 0 },
            { "value": "HIGH", "output": 1 },
            { "value": "MEDIUM", "output": 2 },
            { "value": "LOW", "output": 3 }
          ]
        }
      }
    },
    {
      "name": "Critical Alert",
      "type": "n8n-nodes-base.pagerduty",
      "parameters": {
        "operation": "create",
        "incident": {
          "title": "CRITICAL: Financial Record Deleted",
          "service": "compliance",
          "urgency": "high"
        }
      }
    },
    {
      "name": "Require Approval",
      "type": "n8n-nodes-base.slack",
      "parameters": {
        "channel": "#compliance-approvals",
        "blocks": [
          {
            "type": "section",
            "text": { "type": "mrkdwn", "text": "Approval Required" }
          }
        ]
      }
    },
    {
      "name": "Auto-Log",
      "type": "n8n-nodes-base.postgres",
      "parameters": {
        "operation": "insert",
        "table": "sox_audit_log",
        "columns": { /* ... */ }
      }
    }
  ]
}

{
  "name": "IoT Predictive Maintenance",
  "trigger": {
    "type": "n8n-nodes-base.mqtt",
    "topics": ["sensors/+/telemetry"],
    "qos": 1
  },
  "nodes": [
    {
      "name": "Parse Telemetry",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "jsCode": "const payload = JSON.parse($json.payload);\nconst sensorId = $json.topic.split('/')[1];\n\nreturn [{\n  json: {\n    sensor_id: sensorId,\n    temperature: payload.temp,\n    vibration: payload.vib,\n    pressure: payload.pressure,\n    timestamp: payload.ts,\n    facility: payload.facility_id,\n    equipment_type: payload.equipment_type\n  }\n}];"
      }
    },
    {
      "name": "Anomaly Detection",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "https://ml-api.company.com/predict",
        "method": "POST",
        "body": {
          "sensor_data": "={{ $json }}"
        }
      }
    },
    {
      "name": "Check Thresholds",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "jsCode": "const reading = $json;\nconst thresholds = {\n  temperature: { warn: 80, critical: 95 },\n  vibration: { warn: 5, critical: 10 },\n  pressure: { warn: 150, critical: 200 }\n};\n\nconst alerts = [];\nfor (const [metric, value] of Object.entries(reading)) {\n  if (thresholds[metric]) {\n    if (value >= thresholds[metric].critical) {\n      alerts.push({ metric, level: 'CRITICAL', value });\n    } else if (value >= thresholds[metric].warn) {\n      alerts.push({ metric, level: 'WARNING', value });\n    }\n  }\n}\n\nreturn [{\n  json: {\n    ...reading,\n    alerts,\n    requires_action: alerts.some(a => a.level === 'CRITICAL')\n  }\n}];"
      }
    },
    {
      "name": "Maintenance Prediction",
      "type": "n8n-nodes-base.postgres",
      "parameters": {
        "operation": "executeQuery",
        "query": "SELECT AVG(days_to_failure) as avg_days FROM maintenance_history WHERE equipment_type = $1 AND sensor_readings \u003c@ $2::jsonb",
        "parameters": ["={{ $json.equipment_type }}", "={{ JSON.stringify({temp: $json.temperature, vib: $json.vibration}) }}"]
      }
    },
    {
      "name": "Create Work Order",
      "type": "n8n-nodes-base.httpRequest",
      "parameters": {
        "url": "https://cmms.company.com/api/workorders",
        "method": "POST",
        "body": {
          "equipment_id": "={{ $json.sensor_id }}",
          "priority": "={{ $json.alerts[0].level }}",
          "predicted_failure": "={{ $json.avg_days }} days",
          "description": "AI-predicted maintenance required"
        }
      }
    }
  ]
}

┌─────────────────────────────────────────────────────────────────────────────────┐
│                    Workflow Migration Assessment                                │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   Step 1: Inventory                                                            │
│   • Export all existing workflows                                                │
│   • Document trigger types and frequencies                                     │
│   • Catalog all integrations and credentials                                   │
│   • Identify error rates and reliability issues                                │
│                                                                                 │
│   Step 2: Prioritization                                                        │
│   ┌─────────────────────────────────────────────────────────────────────────┐  │
│   │  Score each workflow on:                                                │  │
│   │  • Complexity (1-10) — Higher = better for AI                           │  │
│   │  • Business impact (1-10) — Start with high impact                     │  │
│   │  • Change frequency (1-10) — Frequent changes benefit most             │  │
│   │  • Error rate (1-10) — Broken workflows need attention first            │  │
│   │                                                                          │  │
│   │  Priority Score = Complexity × 0.3 + Impact × 0.4 +                    │  │
│   │                   ChangeFreq × 0.2 + ErrorRate × 0.1                    │  │
│   └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
│   Step 3: Migration Waves                                                       │
│   • Wave 1: Simple, low-risk (1-2 weeks)                                      │
│   • Wave 2: Medium complexity (3-4 weeks)                                     │
│   • Wave 3: Complex, critical (6-8 weeks)                                     │
│                                                                                 │
│   Step 4: Validation                                                            │
│   • Parallel running (old + new)                                              │
│   • Output comparison                                                           │
│   • Stakeholder sign-off                                                        │
│   • Gradual traffic shifting                                                    │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

{
  "name": "Customer Onboarding (Legacy)",
  "nodes": [
    { "type": "webhook", "name": "Webhook" },
    { "type": "postgres", "name": "CreateUser" },
    { "type": "httpRequest", "name": "SendWelcomeEmail" },
    { "type": "slack", "name": "NotifySales" },
    // ... 8 more nodes
  ]
}