n8n-mcp-tools-expert - Agent Skills

n8n MCP Tools Expert

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

When to Use This Skill

Use this skill when:

Searching for n8n nodes

Validating n8n configurations

Accessing n8n templates

Managing n8n workflows

Using any n8n-mcp tool

Need guidance on tool selection or parameter formats

Tool Categories

n8n-mcp provides tools organized into categories:

Node Discovery → SEARCH_GUIDE.md

Configuration Validation → VALIDATION_GUIDE.md

Workflow Management → WORKFLOW_GUIDE.md

Template Library - Search and deploy 2,700+ real workflows

Documentation & Guides - Tool docs, AI agent guide, Code node guides

Quick Reference

Most Used Tools (by success rate)

Tool	Use When	Speed
`search_nodes`	Finding nodes by keyword	<20ms
`get_node`	Understanding node operations (detail="standard")	<10ms
`validate_node`	Checking configurations (mode="full")	<100ms
`n8n_create_workflow`	Creating workflows	100-500ms
`n8n_update_partial_workflow`	Editing workflows (MOST USED!)	50-200ms
`validate_workflow`	Checking complete workflow	100-500ms
`n8n_deploy_template`	Deploy template to n8n instance	200-500ms

Tool Selection Guide

Finding the Right Node

Workflow:

1. search_nodes({query: "keyword"})
get_node({nodeType: "nodes-base.name"})

[Optional] get_node({nodeType: "nodes-base.name", mode: "docs"})

Example:

// Step 1: Search
search_nodes({query: "slack"})
// Returns: nodes-base.slack
// Step 2: Get details
get_node({nodeType: "nodes-base.slack"})
// Returns: operations, properties, examples (standard detail)// Step 3: Get readable documentation
get_node({nodeType: "nodes-base.slack", mode: "docs"})
// Returns: markdown documentation

Common pattern: search → get_node (18s average)

Validating Configuration

Workflow:

1. validate_node({nodeType, config: {}, mode: "minimal"}) - Check required fields
validate_node({nodeType, config, profile: "runtime"}) - Full validation

[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})
n8n_validate_workflow({id})

n8n_update_partial_workflow({id, operations: [...]})

n8n_validate_workflow({id}) again

n8n_update_partial_workflow({id, operations: [{type: "activateWorkflow"}]})

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

validate_node

validate_workflow

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

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

// WRONG
get_node({nodeType: "slack"})  // Missing prefix
get_node({nodeType: "n8n-nodes-base.slack"})  // Wrong prefix// CORRECT
get_node({nodeType: "nodes-base.slack"})

Mistake 2: Using detail="full" by Default

Problem: Huge payload, slower response, token waste

// WRONG - Returns 3-8K tokens, use sparingly
get_node({nodeType: "nodes-base.slack", detail: "full"})// CORRECT - Returns 1-2K tokens, covers 95% of use cases
get_node({nodeType: "nodes-base.slack"})  // detail="standard" is default
get_node({nodeType: "nodes-base.slack", detail: "standard"})

When to use detail="full":

Debugging complex configuration issues

Need complete property schema with all nested options

Exploring advanced features

Better alternatives:

get_node({detail: "standard"}) - for operations list (default)

get_node({mode: "docs"}) - for readable documentation

get_node({mode: "search_properties", propertyQuery: "auth"}) - 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)

// WRONG - Uses default profile
validate_node({nodeType, config})// CORRECT - Explicit profile
validate_node({nodeType, config, profile: "runtime"})

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 }

Mistake 6: Not Using intent Parameter

Problem: Less helpful tool responses

// WRONG - No context for response
n8n_update_partial_workflow({
  id: "abc",
  operations: [{type: "addNode", node: {...}}]
})// CORRECT - Better AI responses
n8n_update_partial_workflow({
  id: "abc",
  intent: "Add error handling for API failures",
  operations: [{type: "addNode", node: {...}}]
})

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({
  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({
  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({...});  // 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",
  intent: "Add webhook trigger",
  operations: [{type: "addNode", node: {...}}]
});
// ~56s later...
// Edit 2
await n8n_update_partial_workflow({
  id: "workflow-id",
  intent: "Connect webhook to processor",
  operations: [{type: "addConnection", source: "...", target: "..."}]
});
// ~56s later...
// Edit 3 (validation)
await n8n_validate_workflow({id: "workflow-id"});// Ready? Activate!
await n8n_update_partial_workflow({
  id: "workflow-id",
  intent: "Activate workflow for production",
  operations: [{type: "activateWorkflow"}]
});

Detailed Guides

Node Discovery Tools

See SEARCH_GUIDE.md for:

search_nodes

get_node with detail levels (minimal, standard, full)

get_node modes (info, docs, search_properties, versions)

Validation Tools

See VALIDATION_GUIDE.md for:

Validation profiles explained

validate_node with modes (minimal, full)

validate_workflow complete structure

Auto-sanitization system

Handling validation errors

Workflow Management

See WORKFLOW_GUIDE.md for:

n8n_create_workflow

n8n_update_partial_workflow (17 operation types!)

Smart parameters (branch, case)

AI connection types (8 types)

Workflow activation (activateWorkflow/deactivateWorkflow)

n8n_deploy_template

n8n_workflow_versions

Template Usage

Search Templates

// Search by keyword (default mode)
search_templates({
  query: "webhook slack",
  limit: 20
});
// Search by node types
search_templates({
  searchMode: "by_nodes",
  nodeTypes: ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"]
});
// Search by task type
search_templates({
  searchMode: "by_task",
  task: "webhook_processing"
});// Search by metadata (complexity, setup time)
search_templates({
  searchMode: "by_metadata",
  complexity: "simple",
  maxSetupMinutes: 15
});

Get Template Details

get_template({
  templateId: 2947,
  mode: "structure"  // nodes+connections only
});get_template({
  templateId: 2947,
  mode: "full"  // complete workflow JSON
});

Deploy Template Directly

// Deploy template to your n8n instance
n8n_deploy_template({
  templateId: 2947,
  name: "My Weather to Slack",  // Custom name (optional)
  autoFix: true,  // Auto-fix common issues (default)
  autoUpgradeVersions: true  // Upgrade node versions (default)
});
// Returns: workflow ID, required credentials, fixes applied

Self-Help Tools

Get Tool Documentation

// Overview of all tools
tools_documentation()
// Specific tool details
tools_documentation({
  topic: "search_nodes",
  depth: "full"
})// Code node guides
tools_documentation({topic: "javascript_code_node_guide", depth: "full"})
tools_documentation({topic: "python_code_node_guide", depth: "full"})

AI Agent Guide

// Comprehensive AI workflow guide
ai_agents_guide()
// Returns: Architecture, connections, tools, validation, best practices

Health Check

// Quick health check
n8n_health_check()// Detailed diagnostics
n8n_health_check({mode: "diagnostic"})
// → Returns: status, env vars, tool status, API connectivity

Tool Availability

Always Available (no n8n API needed):

search_nodes, get_node

validate_node, validate_workflow

search_templates, get_template

tools_documentation, ai_agents_guide

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_test_workflow

n8n_executions

n8n_deploy_template

n8n_workflow_versions

n8n_autofix_workflow

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

Unified Tool Reference

get_node (Unified Node Information)

Detail Levels (mode="info", default):

minimal (~200 tokens) - Basic metadata only

standard (~1-2K tokens) - Essential properties + operations (RECOMMENDED)

full (~3-8K tokens) - Complete schema (use sparingly)

Operation Modes:

info (default) - Node schema with detail level

docs - Readable markdown documentation

search_properties - Find specific properties (use with propertyQuery)

versions - List all versions with breaking changes

compare - Compare two versions

breaking - Show only breaking changes

migrations - Show auto-migratable changes

// Standard (recommended)
get_node({nodeType: "nodes-base.httpRequest"})
// Get documentation
get_node({nodeType: "nodes-base.webhook", mode: "docs"})
// Search for properties
get_node({nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth"})// Check versions
get_node({nodeType: "nodes-base.executeWorkflow", mode: "versions"})

validate_node (Unified Validation)

Modes:

full (default) - Comprehensive validation with errors/warnings/suggestions

minimal - Quick required fields check only

Profiles (for mode="full"):

minimal - Very lenient

runtime - Standard (default, recommended)

ai-friendly - Balanced for AI workflows

strict - Most thorough (production)

// Full validation with runtime profile
validate_node({nodeType: "nodes-base.slack", config: {...}, profile: "runtime"})// Quick required fields check
validate_node({nodeType: "nodes-base.webhook", config: {}, mode: "minimal"})

Performance Characteristics

Tool	Response Time	Payload Size
search_nodes	<20ms	Small
get_node (standard)	<10ms	~1-2KB
get_node (full)	<100ms	3-8KB
validate_node (minimal)	<50ms	Small
validate_node (full)	<100ms	Medium
validate_workflow	100-500ms	Medium
n8n_create_workflow	100-500ms	Medium
n8n_update_partial_workflow	50-200ms	Small
n8n_deploy_template	200-500ms	Medium

Best Practices

Do

Use get_node({detail: "standard"}) for most use cases

Specify validation profile explicitly (profile: "runtime")

Use smart parameters (branch, case) for clarity

Include intent parameter in workflow updates

Follow search → get_node → validate workflow

Iterate workflows (avg 56s between edits)

Validate after every significant change

Use includeExamples: true for real configs

Use n8n_deploy_template for quick starts

Don't

Use detail: "full" unless necessary (wastes tokens)

Forget nodeType prefix (nodes-base.)

Skip validation profiles

Try to build workflows in one shot (iterate!)

Ignore auto-sanitization behavior

Use full prefix (n8n-nodes-base.) with search/validate tools

Forget to activate workflows after building

Summary

Most Important:

Use get_node with detail: "standard" (default) - covers 95% of use cases

nodeType formats differ: nodes-base. (search/validate) vs n8n-nodes-base. (workflows)

Specify validation profiles (runtime recommended)

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

Include intent parameter in workflow updates

Auto-sanitization runs on ALL nodes during updates

Workflows can be activated via API (activateWorkflow operation)

Workflows are built iteratively (56s avg between edits)

Common Workflow:

search_nodes → find node

get_node → understand config

validate_node → check config

n8n_create_workflow → build

n8n_validate_workflow → verify

n8n_update_partial_workflow → iterate

activateWorkflow → go live!

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 Code JavaScript - Write JavaScript in Code nodes

n8n Code Python - Write Python in Code nodes