N8n Mcp Tools Expert

n8n MCP Tools Expert

Master guide for using n8n-mcp MCP server tools to build workflows.

---

Tool Categories

n8n-mcp provides 40+ tools organized into categories:

1. Node Discovery → SEARCH_GUIDE.md 2. Configuration Validation → VALIDATION_GUIDE.md 3. Workflow Management → WORKFLOW_GUIDE.md 4. Template Library - Search and access 2,653 real workflows 5. Documentation - Get tool and node documentation

---

Quick Reference

Most Used Tools (by success rate)

---

Tool Selection Guide

Finding the Right Node

Workflow:

1. search_nodes({query: "keyword"})
2. get_node_essentials({nodeType: "nodes-base.name"})
3. [Optional] get_node_documentation({nodeType: "nodes-base.name"})

Example:

// Step 1: Search
search_nodes({query: "slack"})
// Returns: nodes-base.slack

// Step 2: Get details (18s avg between steps)
get_node_essentials({nodeType: "nodes-base.slack"})
// Returns: operations, properties, examples

Common pattern: search → essentials (18s average)

Validating Configuration

Workflow:

1. validate_node_minimal({nodeType, config: {}}) - Check required fields
2. validate_node_operation({nodeType, config, profile: "runtime"}) - Full validation
3. [Repeat] Fix errors, validate again

Common pattern: validate → fix → validate (23s thinking, 58s fixing per cycle)

Managing Workflows

Workflow:

1. n8n_create_workflow({name, nodes, connections})
2. n8n_validate_workflow({id})
3. n8n_update_partial_workflow({id, operations: [...]})
4. n8n_validate_workflow({id}) again

Common pattern: iterative updates (56s average between edits)

---

Critical: nodeType Formats

Two different formats for different tools!

Format 1: Search/Validate Tools

// Use SHORT prefix
"nodes-base.slack"
"nodes-base.httpRequest"
"nodes-base.webhook"
"nodes-langchain.agent"

Tools that use this:

• search_nodes (returns this format)
• get_node_essentials
• get_node_info
• validate_node_minimal
• validate_node_operation
• get_property_dependencies

Format 2: Workflow Tools

// Use FULL prefix
"n8n-nodes-base.slack"
"n8n-nodes-base.httpRequest"
"n8n-nodes-base.webhook"
"@n8n/n8n-nodes-langchain.agent"

Tools that use this:

• n8n_create_workflow
• n8n_update_partial_workflow
• list_node_templates

Conversion

// search_nodes returns BOTH formats
{
  "nodeType": "nodes-base.slack",          // For search/validate tools
  "workflowNodeType": "n8n-nodes-base.slack"  // For workflow tools
}

---

Common Mistakes

❌ Mistake 1: Wrong nodeType Format

Problem: "Node not found" error

❌ get_node_essentials({nodeType: "slack"})  // Missing prefix
❌ get_node_essentials({nodeType: "n8n-nodes-base.slack"})  // Wrong prefix

✅ get_node_essentials({nodeType: "nodes-base.slack"})  // Correct!

❌ Mistake 2: Using get_node_info Instead of get_node_essentials

Problem: 20% failure rate, slow response, huge payload

❌ get_node_info({nodeType: "nodes-base.slack"})
// Returns: 100KB+ data, 20% chance of failure

✅ get_node_essentials({nodeType: "nodes-base.slack"})
// Returns: 5KB focused data, 91.7% success, <10ms

When to use get_node_info:

• Debugging complex configuration issues
• Need complete property schema
• Exploring advanced features

Better alternatives: 1. get_node_essentials - for operations list 2. get_node_documentation - for readable docs 3. search_node_properties - for specific property

❌ Mistake 3: Not Using Validation Profiles

Problem: Too many false positives OR missing real errors

Profiles:

• minimal - Only required fields (fast, permissive)
• runtime - Values + types (recommended for pre-deployment)
• ai-friendly - Reduce false positives (for AI configuration)
• strict - Maximum validation (for production)

❌ validate_node_operation({nodeType, config})  // Uses default

✅ validate_node_operation({nodeType, config, profile: "runtime"})  // Explicit

❌ Mistake 4: Ignoring Auto-Sanitization

What happens: ALL nodes sanitized on ANY workflow update

Auto-fixes:

• Binary operators (equals, contains) → removes singleValue
• Unary operators (isEmpty, isNotEmpty) → adds singleValue: true
• IF/Switch nodes → adds missing metadata

Cannot fix:

• Broken connections
• Branch count mismatches
• Paradoxical corrupt states

// After ANY update, auto-sanitization runs on ALL nodes
n8n_update_partial_workflow({id, operations: [...]})
// → Automatically fixes operator structures

❌ Mistake 5: Not Using Smart Parameters

Problem: Complex sourceIndex calculations for multi-output nodes

Old way (manual):

// IF node connection
{
  type: "addConnection",
  source: "IF",
  target: "Handler",
  sourceIndex: 0  // Which output? Hard to remember!
}

New way (smart parameters):

// IF node - semantic branch names
{
  type: "addConnection",
  source: "IF",
  target: "True Handler",
  branch: "true"  // Clear and readable!
}

{
  type: "addConnection",
  source: "IF",
  target: "False Handler",
  branch: "false"
}

// Switch node - semantic case numbers
{
  type: "addConnection",
  source: "Switch",
  target: "Handler A",
  case: 0
}

---

Tool Usage Patterns

Pattern 1: Node Discovery (Most Common)

Common workflow: 18s average between steps

// Step 1: Search (fast!)
const results = await search_nodes({
  query: "slack",
  mode: "OR",  // Default: any word matches
  limit: 20
});
// → Returns: nodes-base.slack, nodes-base.slackTrigger

// Step 2: Get details (~18s later, user reviewing results)
const details = await get_node_essentials({
  nodeType: "nodes-base.slack",
  includeExamples: true  // Get real template configs
});
// → Returns: operations, properties, metadata

Pattern 2: Validation Loop

Typical cycle: 23s thinking, 58s fixing

// Step 1: Validate
const result = await validate_node_operation({
  nodeType: "nodes-base.slack",
  config: {
    resource: "channel",
    operation: "create"
  },
  profile: "runtime"
});

// Step 2: Check errors (~23s thinking)
if (!result.valid) {
  console.log(result.errors);  // "Missing required field: name"
}

// Step 3: Fix config (~58s fixing)
config.name = "general";

// Step 4: Validate again
await validate_node_operation({...});  // Repeat until clean

Pattern 3: Workflow Editing

Most used update tool: 99.0% success rate, 56s average between edits

// Iterative workflow building (NOT one-shot!)
// Edit 1
await n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [{type: "addNode", node: {...}}]
});

// ~56s later...

// Edit 2
await n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [{type: "addConnection", source: "...", target: "..."}]
});

// ~56s later...

// Edit 3 (validation)
await n8n_validate_workflow({id: "workflow-id"});

---

Detailed Guides

Node Discovery Tools

See SEARCH_GUIDE.md for:

• search_nodes (99.9% success)
• get_node_essentials vs get_node_info
• list_nodes by category
• search_node_properties for specific fields

Validation Tools

See VALIDATION_GUIDE.md for:

• Validation profiles explained
• validate_node_minimal vs validate_node_operation
• validate_workflow complete structure
• Auto-sanitization system
• Handling validation errors

Workflow Management

See WORKFLOW_GUIDE.md for:

• n8n_create_workflow
• n8n_update_partial_workflow (15 operation types!)
• Smart parameters (branch, case)
• AI connection types (8 types)
• cleanStaleConnections recovery

---

Template Usage

Search Templates

// Search by keyword
search_templates({
  query: "webhook slack",
  limit: 20
});
// → Returns: 1,085 templates with metadata

// Get template details
get_template({
  templateId: 2947,  // Weather to Slack
  mode: "structure"  // or "full" for complete JSON
});

Template Metadata

Templates include:

• Complexity (simple, medium, complex)
• Setup time estimate
• Required services
• Categories and use cases
• View counts (popularity)

---

Self-Help Tools

Get Tool Documentation

// List all tools
tools_documentation()

// Specific tool details
tools_documentation({
  topic: "search_nodes",
  depth: "full"
})

Health Check

// Verify MCP server connectivity
n8n_health_check()
// → Returns: status, features, API availability, version

Database Statistics

get_database_statistics()
// → Returns: 537 nodes, 270 AI tools, 2,653 templates

---

Tool Availability

Always Available (no n8n API needed):

• search_nodes, list_nodes, get_node_essentials ✅
• validate_node_minimal, validate_node_operation ✅
• validate_workflow, get_property_dependencies ✅
• search_templates, get_template, list_tasks ✅
• tools_documentation, get_database_statistics ✅

Requires n8n API (N8N_API_URL + N8N_API_KEY):

• n8n_create_workflow ⚠️
• n8n_update_partial_workflow ⚠️
• n8n_validate_workflow (by ID) ⚠️
• n8n_list_workflows, n8n_get_workflow ⚠️
• n8n_trigger_webhook_workflow ⚠️

If API tools unavailable, use templates and validation-only workflows.

---

Performance Characteristics

---

Best Practices

✅ Do

• Use get_node_essentials over get_node_info (91.7% vs 80%)
• Specify validation profile explicitly
• Use smart parameters (branch, case) for clarity
• Follow search → essentials → validate workflow
• Iterate workflows (avg 56s between edits)
• Validate after every significant change
• Use includeExamples: true for real configs

❌ Don't

• Use get_node_info unless necessary (20% failure rate!)
• Forget nodeType prefix (nodes-base.*)
• Skip validation profiles (use "runtime")
• Try to build workflows in one shot (iterate!)
• Ignore auto-sanitization behavior
• Use full prefix (n8n-nodes-base.*) with search tools

---

Summary

Most Important: 1. Use get_node_essentials, not get_node_info (5KB vs 100KB, 91.7% vs 80%) 2. nodeType formats differ: nodes-base.* (search) vs n8n-nodes-base.* (workflows) 3. Specify validation profiles (runtime recommended) 4. Use smart parameters (branch="true", case=0) 5. Auto-sanitization runs on ALL nodes during updates 6. Workflows are built iteratively (56s avg between edits)

Common Workflow: 1. search_nodes → find node 2. get_node_essentials → understand config 3. validate_node_operation → check config 4. n8n_create_workflow → build 5. n8n_validate_workflow → verify 6. n8n_update_partial_workflow → iterate

For details, see:

• SEARCH_GUIDE.md - Node discovery
• VALIDATION_GUIDE.md - Configuration validation
• WORKFLOW_GUIDE.md - Workflow management

---

Related Skills:

• n8n Expression Syntax - Write expressions in workflow fields
• n8n Workflow Patterns - Architectural patterns from templates
• n8n Validation Expert - Interpret validation errors
• n8n Node Configuration - Operation-specific requirements

n8n MCP Tools Expert

Expert guide for using n8n-mcp MCP tools effectively.

---

Purpose

Teaches how to use n8n-mcp MCP server tools correctly for efficient workflow building.

Activates On

• search nodes
• find node
• validate
• MCP tools
• template
• workflow
• n8n-mcp
• tool selection

File Count

5 files, ~1,150 lines total

Priority

HIGHEST - Essential for correct MCP tool usage

Dependencies

n8n-mcp tools: All of them! (40+ tools)

Related skills:

• n8n Expression Syntax (write expressions for workflows)
• n8n Workflow Patterns (use tools to build patterns)
• n8n Validation Expert (interpret validation results)
• n8n Node Configuration (configure nodes found with tools)

Coverage

Core Topics

• Tool selection guide (which tool for which task)
• nodeType format differences (nodes-base. vs n8n-nodes-base.)
• Validation profiles (minimal/runtime/ai-friendly/strict)
• Smart parameters (branch, case for multi-output nodes)
• Auto-sanitization system
• Workflow management (15 operation types)
• AI connection types (8 types)

Tool Categories

• Node Discovery (search, list, essentials, info)
• Configuration Validation (minimal, operation, workflow)
• Workflow Management (create, update, validate)
• Template Library (search, get)
• Documentation (tools, database stats)

Evaluations

5 scenarios (100% coverage expected): 1. eval-001: Tool selection (search_nodes) 2. eval-002: nodeType format (nodes-base. prefix) 3. eval-003: Validation workflow (profiles) 4. eval-004: essentials vs info (5KB vs 100KB) 5. eval-005*: Smart parameters (branch, case)

Key Features

✅ Tool Selection Guide: Which tool to use for each task ✅ Common Patterns: Most effective tool usage sequences ✅ Format Guidance: nodeType format differences explained ✅ Smart Parameters: Semantic branch/case routing for multi-output nodes ✅ Auto-Sanitization: Explains automatic validation fixes ✅ Comprehensive: Covers all 40+ MCP tools

Files

• SKILL.md (480 lines) - Core tool usage guide
• SEARCH_GUIDE.md (220 lines) - Node discovery tools
• VALIDATION_GUIDE.md (250 lines) - Validation tools and profiles
• WORKFLOW_GUIDE.md (200 lines) - Workflow management
• README.md (this file) - Skill metadata

What You'll Learn

• Correct nodeType formats (nodes-base.* for search tools)
• When to use get_node_essentials vs get_node_info
• How to use validation profiles effectively
• Smart parameters for multi-output nodes (IF/Switch)
• Common tool usage patterns and workflows

Last Updated

2025-10-20

---

Part of: n8n-skills repository Conceived by: Romuald Członkowski - www.aiadvisors.pl/en

Node Discovery Tools Guide

Complete guide for finding and understanding n8n nodes.

---

search_nodes (START HERE!)

Success Rate: 99.9% | Speed: <20ms

Use when: You know what you're looking for (keyword, service, use case)

Syntax:

search_nodes({
  query: "slack",      // Required: search keywords
  mode: "OR",          // Optional: OR (default), AND, FUZZY
  limit: 20           // Optional: max results (default 20, max 100)
})

Returns:

{
  "query": "slack",
  "results": [
    {
      "nodeType": "nodes-base.slack",                    // For search/validate tools
      "workflowNodeType": "n8n-nodes-base.slack",       // For workflow tools
      "displayName": "Slack",
      "description": "Consume Slack API",
      "category": "output",
      "relevance": "high"
    }
  ]
}

Tips:

• Common searches: webhook, http, database, email, slack, google, ai
• OR mode (default): matches any word
• AND mode: requires all words
• FUZZY mode: typo-tolerant (finds "slak" → Slack)

---

get_node_essentials (RECOMMENDED!)

Success Rate: 91.7% | Speed: <10ms | Size: ~5KB

Use when: You've found the node and need configuration details

Syntax:

get_node_essentials({
  nodeType: "nodes-base.slack",      // Required: SHORT prefix format
  includeExamples: true              // Optional: get real template configs
})

Returns:

• Available operations and resources
• Essential properties (10-20 most common)
• Metadata (isAITool, isTrigger, hasCredentials)
• Real examples from templates (if includeExamples: true)

Why use this:

• 5KB vs 100KB+ (get_node_info)
• 91.7% success vs 80%
• <10ms vs slower
• Focused data (no information overload)

---

get_node_info (USE SPARINGLY!)

Success Rate: 80% ⚠️ | Size: 100KB+

Use when:

• Debugging complex configuration
• Need complete property schema
• Exploring advanced features

Syntax:

get_node_info({
  nodeType: "nodes-base.httpRequest"
})

Warning: 20% failure rate! Use get_node_essentials instead for most cases.

Better alternatives: 1. get_node_essentials - operations list 2. get_node_documentation - readable docs 3. search_node_properties - specific property

---

list_nodes (BROWSE BY CATEGORY)

Success Rate: 99.6% | Speed: <20ms

Use when: Exploring by category or listing all nodes

Syntax:

list_nodes({
  category: "trigger",        // Optional: filter by category
  package: "n8n-nodes-base", // Optional: filter by package
  limit: 200                 // Optional: default 50
})

Categories:

• trigger - Webhook, Schedule, Manual, etc. (108 total)
• transform - Code, Set, Function, etc.
• output - HTTP Request, Email, Slack, etc.
• input - Read data sources
• AI - AI-capable nodes (270 total)

Packages:

• n8n-nodes-base - Core nodes (437 total)
• @n8n/n8n-nodes-langchain - AI nodes (100 total)

---

search_node_properties (FIND SPECIFIC FIELDS)

Use when: Looking for specific property in a node

Syntax:

search_node_properties({
  nodeType: "nodes-base.httpRequest",
  query: "auth"               // Find authentication properties
})

Returns: Property paths and descriptions matching query

Common searches: auth, header, body, json, url, method

---

get_node_documentation (READABLE DOCS)

Coverage: 88% of nodes (470/537)

Use when: Need human-readable documentation with examples

Syntax:

get_node_documentation({
  nodeType: "nodes-base.slack"
})

Returns: Formatted docs with:

• Usage examples
• Authentication guide
• Common patterns
• Best practices

Note: Better than raw schema for learning!

---

Common Workflow: Finding & Configuring

Step 1: Search
search_nodes({query: "slack"})
→ Returns: nodes-base.slack

Step 2: Get Operations (18s avg thinking time)
get_node_essentials({
  nodeType: "nodes-base.slack",
  includeExamples: true
})
→ Returns: operations list + example configs

Step 3: Validate Config
validate_node_operation({
  nodeType: "nodes-base.slack",
  config: {resource: "channel", operation: "create"},
  profile: "runtime"
})
→ Returns: validation result

Step 4: Use in Workflow
(Configuration ready!)

Most common pattern: search → essentials (18s average)

---

Quick Comparison

Best Practice: search → essentials → validate

---

nodeType Format (CRITICAL!)

Search/Validate Tools (SHORT prefix):

"nodes-base.slack"
"nodes-base.httpRequest"
"nodes-langchain.agent"

Workflow Tools (FULL prefix):

"n8n-nodes-base.slack"
"n8n-nodes-base.httpRequest"
"@n8n/n8n-nodes-langchain.agent"

Conversion: search_nodes returns BOTH formats:

{
  "nodeType": "nodes-base.slack",          // Use with essentials
  "workflowNodeType": "n8n-nodes-base.slack"  // Use with create_workflow
}

---

Related

• VALIDATION_GUIDE.md - Validate node configs
• WORKFLOW_GUIDE.md - Use nodes in workflows

Configuration Validation Tools Guide

Complete guide for validating node configurations and workflows.

---

Validation Philosophy

Validate early, validate often

Validation is typically iterative with validate → fix cycles

---

validate_node_minimal (QUICK CHECK)

Success Rate: 97.4% | Speed: <100ms

Use when: Checking what fields are required

Syntax:

validate_node_minimal({
  nodeType: "nodes-base.slack",
  config: {}  // Empty to see all required fields
})

Returns:

{
  "valid": true,           // Usually true (most nodes have no strict requirements)
  "missingRequiredFields": []
}

When to use: Planning configuration, seeing basic requirements

---

validate_node_operation (FULL VALIDATION)

Success Rate: Varies | Speed: <100ms

Use when: Validating actual configuration before deployment

Syntax:

validate_node_operation({
  nodeType: "nodes-base.slack",
  config: {
    resource: "channel",
    operation: "create",
    channel: "general"
  },
  profile: "runtime"  // Recommended!
})

Validation Profiles

Choose based on your stage:

minimal - Only required fields

• Fastest
• Most permissive
• Use: Quick checks during editing

runtime - Values + types (RECOMMENDED)

• Balanced validation
• Catches real errors
• Use: Pre-deployment validation

ai-friendly - Reduce false positives

• For AI-generated configs
• Tolerates minor issues
• Use: When AI configures nodes

strict - Maximum validation

• Strictest rules
• May have false positives
• Use: Production deployment

Returns

{
  "valid": false,
  "errors": [
    {
      "type": "missing_required",
      "property": "name",
      "message": "Channel name is required",
      "fix": "Provide a channel name (lowercase, no spaces, 1-80 characters)"
    }
  ],
  "warnings": [
    {
      "type": "best_practice",
      "property": "errorHandling",
      "message": "Slack API can have rate limits",
      "suggestion": "Add onError: 'continueRegularOutput' with retryOnFail"
    }
  ],
  "suggestions": [],
  "summary": {
    "hasErrors": true,
    "errorCount": 1,
    "warningCount": 1
  }
}

Error Types

• missing_required - Must fix
• invalid_value - Must fix
• type_mismatch - Must fix
• best_practice - Should fix (warning)
• suggestion - Optional improvement

---

validate_workflow (STRUCTURE VALIDATION)

Success Rate: 95.5% | Speed: 100-500ms

Use when: Checking complete workflow before execution

Syntax:

validate_workflow({
  workflow: {
    nodes: [...],        // Array of nodes
    connections: {...}   // Connections object
  },
  options: {
    validateNodes: true,       // Default: true
    validateConnections: true, // Default: true
    validateExpressions: true, // Default: true
    profile: "runtime"         // For node validation
  }
})

Validates:

• Node configurations
• Connection validity (no broken references)
• Expression syntax ({{ }} patterns)
• Workflow structure (triggers, flow)
• AI connections (8 types)

Returns: Comprehensive validation report with errors, warnings, suggestions

---

Validation Loop Pattern

Typical cycle: 23s thinking, 58s fixing

1. Configure node
   ↓
2. validate_node_operation (23s thinking about errors)
   ↓
3. Fix errors
   ↓
4. validate_node_operation again (58s fixing)
   ↓
5. Repeat until valid

Example:

// Iteration 1
let config = {
  resource: "channel",
  operation: "create"
};

const result1 = validate_node_operation({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → Error: Missing "name"

// Iteration 2 (~58s later)
config.name = "general";

const result2 = validate_node_operation({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → Valid!

---

Auto-Sanitization System

When it runs: On ANY workflow update (create or update_partial)

What it fixes (automatically on ALL nodes): 1. Binary operators (equals, contains, greaterThan) → removes singleValue 2. Unary operators (isEmpty, isNotEmpty, true, false) → adds singleValue: true 3. Invalid operator structures → corrects to proper format 4. IF v2.2+ nodes → adds complete conditions.options metadata 5. Switch v3.2+ nodes → adds complete conditions.options for all rules

What it CANNOT fix:

• Broken connections (references to non-existent nodes)
• Branch count mismatches (3 Switch rules but only 2 outputs)
• Paradoxical corrupt states (API returns corrupt, rejects updates)

Example:

// Before auto-sanitization
{
  "type": "boolean",
  "operation": "equals",
  "singleValue": true  // ❌ Binary operators shouldn't have this
}

// After auto-sanitization (automatic!)
{
  "type": "boolean",
  "operation": "equals"
  // singleValue removed automatically
}

Recovery tools:

• cleanStaleConnections operation - removes broken connections
• n8n_autofix_workflow - preview/apply fixes

---

Binary vs Unary Operators

Binary operators (compare two values):

• equals, notEquals, contains, notContains
• greaterThan, lessThan, startsWith, endsWith
• Must NOT have singleValue: true

Unary operators (check single value):

• isEmpty, isNotEmpty, true, false
• Must have singleValue: true

Auto-sanitization fixes these automatically!

---

Handling Validation Errors

Process

1. Read error message carefully
2. Check if it's a known false positive
3. Fix real errors
4. Validate again
5. Iterate until clean

Common Errors

"Required field missing" → Add the field with appropriate value

"Invalid value" → Check allowed values in essentials/documentation

"Type mismatch" → Convert to correct type (string/number/boolean)

"Cannot have singleValue" → Auto-sanitization will fix on next update

"Missing operator metadata" → Auto-sanitization will fix on next update

False Positives

Some validation warnings may be acceptable:

• Optional best practices
• Node-specific edge cases
• Profile-dependent issues

Use ai-friendly profile to reduce false positives.

---

Best Practices

✅ Do

• Use runtime profile for pre-deployment
• Validate after every configuration change
• Fix errors immediately (avg 58s)
• Iterate validation loop
• Trust auto-sanitization for operator issues
• Use minimal profile for quick checks
• Complete workflow activation manually in n8n UI (API/MCP cannot activate workflows)

❌ Don't

• Skip validation before deployment
• Ignore error messages
• Use strict profile during development (too many warnings)
• Assume validation passed (check result)
• Try to manually fix auto-sanitization issues

---

Example: Complete Validation Workflow

// Step 1: Get node requirements
validate_node_minimal({
  nodeType: "nodes-base.slack",
  config: {}
});
// → Know what's required

// Step 2: Configure node
const config = {
  resource: "message",
  operation: "post",
  channel: "#general",
  text: "Hello!"
};

// Step 3: Validate configuration
const result = validate_node_operation({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});

// Step 4: Check result
if (result.valid) {
  console.log("✅ Configuration valid!");
} else {
  console.log("❌ Errors:", result.errors);
  // Fix and validate again
}

// Step 5: Validate in workflow context
validate_workflow({
  workflow: {
    nodes: [{...config as node...}],
    connections: {...}
  }
});

---

Summary

Key Points: 1. Use runtime profile (balanced validation) 2. Validation loop: validate → fix (58s) → validate again 3. Auto-sanitization fixes operator structures automatically 4. Binary operators ≠ singleValue, Unary operators = singleValue: true 5. Iterate until validation passes

Tool Selection:

• validate_node_minimal: Quick check
• validate_node_operation: Full config validation (use this!)
• validate_workflow: Complete workflow check

Related:

• SEARCH_GUIDE.md - Find nodes
• WORKFLOW_GUIDE.md - Build workflows

Workflow Management Tools Guide

Complete guide for creating, updating, and managing n8n workflows.

---

Tool Availability

⚠️ Requires n8n API: All tools in this guide need N8N_API_URL and N8N_API_KEY configured.

If unavailable, use template examples and validation-only workflows.

---

n8n_create_workflow

Success Rate: 96.8% | Speed: 100-500ms

Use when: Creating new workflows from scratch

Syntax:

n8n_create_workflow({
  name: "Webhook to Slack",  // Required
  nodes: [...],              // Required: array of nodes
  connections: {...},        // Required: connections object
  settings: {...}            // Optional: workflow settings
})

Returns: Created workflow with ID

Example:

n8n_create_workflow({
  name: "Webhook to Slack",
  nodes: [
    {
      id: "webhook-1",
      name: "Webhook",
      type: "n8n-nodes-base.webhook",  // Full prefix!
      typeVersion: 1,
      position: [250, 300],
      parameters: {
        path: "slack-notify",
        httpMethod: "POST"
      }
    },
    {
      id: "slack-1",
      name: "Slack",
      type: "n8n-nodes-base.slack",
      typeVersion: 1,
      position: [450, 300],
      parameters: {
        resource: "message",
        operation: "post",
        channel: "#general",
        text: "={{$json.body.message}}"
      }
    }
  ],
  connections: {
    "Webhook": {
      "main": [[{node: "Slack", type: "main", index: 0}]]
    }
  }
})

Notes:

• Workflows created inactive (must activate separately)
• Auto-sanitization runs on creation
• Validate before creating for best results

---

n8n_update_partial_workflow (MOST USED!)

Success Rate: 99.0% | Speed: 50-200ms | Uses: 38,287 (most used tool!)

Use when: Making incremental changes to workflows

Common pattern: 56s average between edits (iterative building!)

15 Operation Types

Node Operations (6 types): 1. addNode - Add new node 2. removeNode - Remove node by ID or name 3. updateNode - Update node properties 4. moveNode - Change position 5. enableNode - Enable disabled node 6. disableNode - Disable active node

Connection Operations (5 types): 7. addConnection - Connect nodes 8. removeConnection - Remove connection 9. rewireConnection - Change target 10. cleanStaleConnections - Auto-remove broken connections 11. replaceConnections - Replace entire connections object

Metadata Operations (4 types): 12. updateSettings - Workflow settings 13. updateName - Rename workflow 14. addTag - Add tag 15. removeTag - Remove tag

Smart Parameters (NEW!)

IF nodes - Use semantic branch names:

{
  type: "addConnection",
  source: "IF",
  target: "True Handler",
  branch: "true"  // Instead of sourceIndex: 0
}

{
  type: "addConnection",
  source: "IF",
  target: "False Handler",
  branch: "false"  // Instead of sourceIndex: 1
}

Switch nodes - Use semantic case numbers:

{
  type: "addConnection",
  source: "Switch",
  target: "Handler A",
  case: 0
}

{
  type: "addConnection",
  source: "Switch",
  target: "Handler B",
  case: 1
}

AI Connection Types (8 types)

Full support for AI workflows:

// Language Model
{
  type: "addConnection",
  source: "OpenAI Chat Model",
  target: "AI Agent",
  sourceOutput: "ai_languageModel"
}

// Tool
{
  type: "addConnection",
  source: "HTTP Request Tool",
  target: "AI Agent",
  sourceOutput: "ai_tool"
}

// Memory
{
  type: "addConnection",
  source: "Window Buffer Memory",
  target: "AI Agent",
  sourceOutput: "ai_memory"
}

// All 8 types:
// - ai_languageModel
// - ai_tool
// - ai_memory
// - ai_outputParser
// - ai_embedding
// - ai_vectorStore
// - ai_document
// - ai_textSplitter

Example Usage

n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [
    // Add node
    {
      type: "addNode",
      node: {
        name: "Transform",
        type: "n8n-nodes-base.set",
        position: [400, 300],
        parameters: {}
      }
    },
    // Connect it (smart parameter)
    {
      type: "addConnection",
      source: "IF",
      target: "Transform",
      branch: "true"  // Clear and semantic!
    }
  ]
})

Cleanup & Recovery

cleanStaleConnections - Remove broken connections:

{
  type: "cleanStaleConnections"
}

Best-effort mode - Apply what works:

n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [...],
  continueOnError: true  // Don't fail if some operations fail
})

---

n8n_validate_workflow (by ID)

Success Rate: 99.7% | Speed: Network-dependent

Use when: Validating workflow stored in n8n

Syntax:

n8n_validate_workflow({
  id: "workflow-id",
  options: {
    validateNodes: true,
    validateConnections: true,
    validateExpressions: true,
    profile: "runtime"
  }
})

Returns: Same as validate_workflow (from validation guide)

---

Workflow Lifecycle

Standard pattern:

1. CREATE
   n8n_create_workflow({...})
   → Returns workflow ID

2. VALIDATE
   n8n_validate_workflow({id})
   → Check for errors

3. EDIT (iterative! 56s avg between edits)
   n8n_update_partial_workflow({id, operations: [...]})
   → Make changes

4. VALIDATE AGAIN
   n8n_validate_workflow({id})
   → Verify changes

5. ACTIVATE (when ready)
   ⚠️ **IMPORTANT LIMITATION**: Workflow activation is NOT supported via API or MCP.
   Users must activate workflows manually in the n8n UI.

   The following operation will NOT activate the workflow:
   n8n_update_partial_workflow({id, operations: [{
     type: "updateSettings",
     settings: {active: true}
   }]})

   **Manual activation required**: Navigate to workflow in n8n UI and toggle activation.

6. MONITOR
   n8n_list_executions({workflowId: id})
   n8n_get_execution({id: execution_id})

Deployment Note: After creating and validating workflows via MCP, inform users they must: 1. Open the workflow in n8n UI (provide workflow ID) 2. Review the workflow configuration 3. Manually activate the workflow using the activation toggle

---

Common Patterns from Telemetry

Pattern 1: Edit → Validate (7,841 occurrences)

// Edit
n8n_update_partial_workflow({...})
// ↓ 23s (thinking about what to validate)
// Validate
n8n_validate_workflow({id})

Pattern 2: Validate → Fix (7,266 occurrences)

// Validate
n8n_validate_workflow({id})
// ↓ 58s (fixing errors)
// Fix
n8n_update_partial_workflow({...})

Pattern 3: Iterative Building (31,464 occurrences)

update → update → update → ... (56s avg between edits)

This shows: Workflows are built iteratively, not in one shot!

---

Retrieval Tools

n8n_get_workflow

n8n_get_workflow({id: "workflow-id"})
// Returns: Complete workflow JSON

n8n_get_workflow_structure

n8n_get_workflow_structure({id: "workflow-id"})
// Returns: Nodes + connections only (no parameters)

n8n_get_workflow_minimal

n8n_get_workflow_minimal({id: "workflow-id"})
// Returns: ID, name, active, tags only (fast!)

n8n_list_workflows

n8n_list_workflows({
  active: true,  // Optional: filter by status
  limit: 100,    // Optional: max results
  tags: ["production"]  // Optional: filter by tags
})

---

Best Practices

✅ Do

• Build workflows iteratively (avg 56s between edits)
• Use smart parameters (branch, case) for clarity
• Validate after significant changes
• Use atomic mode (default) for critical updates
• Specify sourceOutput for AI connections
• Clean stale connections after node renames/deletions

❌ Don't

• Try to build workflows in one shot
• Use sourceIndex when branch/case available
• Skip validation before activation
• Forget to test workflows after creation
• Ignore auto-sanitization behavior

---

Summary

Most Important: 1. n8n_update_partial_workflow is most-used tool (38,287 uses, 99.0% success) 2. Workflows built iteratively (56s avg between edits) 3. Use smart parameters (branch="true", case=0) for clarity 4. AI connections supported (8 types with sourceOutput) 5. Auto-sanitization runs on all operations 6. Validate frequently (7,841 edit → validate patterns)

Related:

• SEARCH_GUIDE.md - Find nodes to add
• VALIDATION_GUIDE.md - Validate workflows