n8n-mcp-tools-expert

n8n MCP Tools Expert

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

When to Use

• You are using the n8n-mcp toolset to discover nodes, validate configs, or manage workflows.
• The task involves choosing the right MCP tool or understanding its expected parameters and usage pattern.
• You need guidance on workflow creation or editing through n8n MCP rather than through the n8n UI alone.

Tool Categories

n8n-mcp provides 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 deploy 2,700+ real workflows
5. 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"})
2. get_node({nodeType: "nodes-base.name"})
3. [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
2. validate_node({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
5. 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:

1. get_node({detail: "standard"}) - for operations list (default)
2. get_node({mode: "docs"}) - for readable documentation
3. 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 Editin