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:

• Node Discovery → SEARCH_GUIDE.md

• Configuration Validation → VALIDATION_GUIDE.md

• Workflow Management → WORKFLOW_GUIDE.md

• Template Library - Search and access 2,653 real workflows

• Documentation - Get tool and node documentation

Quick Reference

Most Used Tools (by success rate)

Tool Use When Success Rate Speed

search_nodes

Finding nodes by keyword 99.9% <20ms

get_node_essentials

Understanding node operations 91.7% <10ms

validate_node_operation

Checking configurations Varies <100ms

n8n_create_workflow

Creating workflows 96.8% 100-500ms

n8n_update_partial_workflow

Editing workflows (MOST USED!) 99.0% 50-200ms

validate_workflow

Checking complete workflow 95.5% 100-500ms

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:

• get_node_essentials - for operations list

• get_node_documentation - for readable docs

• 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

Tool Response Time Payload Size Reliability

search_nodes <20ms Small 99.9%

list_nodes <20ms Small 99.6%

get_node_essentials <10ms ~5KB 91.7%

get_node_info Varies 100KB+ 80% ⚠️

validate_node_minimal <100ms Small 97.4%

validate_node_operation <100ms Medium Varies

validate_workflow 100-500ms Medium 95.5%

n8n_create_workflow 100-500ms Medium 96.8%

n8n_update_partial_workflow 50-200ms Small 99.0%

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:

• Use get_node_essentials, not get_node_info (5KB vs 100KB, 91.7% vs 80%)

• nodeType formats differ: nodes-base.* (search) vs n8n-nodes-base.* (workflows)

• Specify validation profiles (runtime recommended)

• Use smart parameters (branch="true", case=0)

• Auto-sanitization runs on ALL nodes during updates

• Workflows are built iteratively (56s avg between edits)

Common Workflow:

• search_nodes → find node

• get_node_essentials → understand config

• validate_node_operation → check config

• n8n_create_workflow → build

• n8n_validate_workflow → verify

• 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