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 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. Workflow Generation - Natural-language → workflow with proposal review (n8n_generate_workflow, hosted-only) 6. Data Tables - Manage n8n data tables and rows (n8n_manage_datatable) 7. Credential Management - Full credential CRUD + schema discovery (n8n_manage_credentials) 8. Security & Audit - Instance security auditing with custom deep scan (n8n_audit_instance) 9. Documentation & Guides - Tool docs, AI agent guide, Code node guides

---

Quick Reference

Most Used Tools (by success rate)

---

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 7: Wrong Parameter Name for updateNode

Problem: Using parameters instead of updates

// WRONG
n8n_update_partial_workflow({
  id: "wf-123",
  operations: [{
    type: "updateNode",
    nodeName: "HTTP Request",
    parameters: {url: "..."}  // ❌ Wrong key
  }]
})

// CORRECT
n8n_update_partial_workflow({
  id: "wf-123",
  operations: [{
    type: "updateNode",
    nodeName: "HTTP Request",
    updates: {url: "..."}  // ✅ Correct key
  }]
})

Mistake 8: Wrong Credential Attachment Format

Problem: Credentials not attaching to nodes

// WRONG - credentials as flat object
updates: {credentials: "myApiKey"}

// CORRECT - credentials nested by type with id and name
updates: {
  credentials: {
    httpHeaderAuth: {
      id: "abc123",
      name: "My API Key"
    }
  }
}

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 (19 operation types including patchNodeField!)
• Smart parameters (branch, case)
• AI connection types (8 types)
• Workflow activation (activateWorkflow/deactivateWorkflow)
• n8n_deploy_template
• n8n_workflow_versions
• n8n_manage_credentials (credential CRUD + schema discovery)
• n8n_audit_instance (security auditing)

---

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

---

Workflow Generation

n8n_generate_workflow

Generates an n8n workflow from a natural-language description via a multi-step flow with a review checkpoint. Hosted-only — self-hosted instances receive a redirect message rather than a workflow.

Two paths:

Path A — pick a proposal (default; cheapest, recommended):

// Step 1: Get up to 5 proposals (NOT deployed)
n8n_generate_workflow({
  description: "Send a Slack message every morning at 9am with a daily standup reminder"
})
// → { status: "proposals", proposals: [{id, name, description, flow_summary, credentials_needed}, ...] }

// Step 2: Deploy the proposal you want
n8n_generate_workflow({
  description: "Send a Slack message every morning at 9am with a daily standup reminder",
  deploy_id: "uuid-from-proposals"
})
// → { status: "deployed", workflow_id, workflow_name, workflow_url, node_count, node_summary }

Path B — fresh generation (when no proposal fits):

// Step 1: Skip the proposal cache, get a preview (NOT deployed)
n8n_generate_workflow({
  description: "Webhook → transform JSON → POST to REST API",
  skip_cache: true
})
// → { status: "preview", ... }

// Step 2: Deploy the preview
n8n_generate_workflow({
  description: "Webhook → transform JSON → POST to REST API",
  confirm_deploy: true
})
// → { status: "deployed", ... }

Description tips (more specific = better results):

• Trigger type: webhook, schedule (with cadence), manual, form, chat
• Services to integrate: name them (Slack, Gmail, Postgres, etc.)
• Logic/flow: what transforms, branches, or aggregations are needed

Caveats:

• Hosted-only — on self-hosted, the response is {hosted_only: true, ...} with a redirect message
• Generated workflows are deployed in inactive state — credentials must be configured in the n8n UI before activation
• Proposals/preview live in per-MCP-session state; switching sessions loses pending state
• Always run n8n_validate_workflow({id}) after deployment to catch any issues
• For self-hosted instances, fall back to n8n_deploy_template (curated templates) or n8n_create_workflow (full control)

When to use which:

---

Data Table Management

n8n_manage_datatable

Unified tool for managing n8n data tables and rows. Supports CRUD operations on tables and rows with filtering, pagination, and dry-run support.

Table Actions: createTable, listTables, getTable, updateTable, deleteTable Row Actions: getRows, insertRows, updateRows, upsertRows, deleteRows

// Create a data table
n8n_manage_datatable({
  action: "createTable",
  name: "Contacts",
  columns: [
    {name: "email", type: "string"},
    {name: "score", type: "number"}
  ]
})

// Get rows with filter
n8n_manage_datatable({
  action: "getRows",
  tableId: "dt-123",
  filter: {
    filters: [{columnName: "status", condition: "eq", value: "active"}]
  },
  limit: 50
})

// Insert rows
n8n_manage_datatable({
  action: "insertRows",
  tableId: "dt-123",
  data: [{email: "a@b.com", score: 10}],
  returnType: "all"
})

// Update with dry run (preview changes)
n8n_manage_datatable({
  action: "updateRows",
  tableId: "dt-123",
  filter: {filters: [{columnName: "score", condition: "lt", value: 5}]},
  data: {status: "inactive"},
  dryRun: true
})

// Upsert (update or insert)
n8n_manage_datatable({
  action: "upsertRows",
  tableId: "dt-123",
  filter: {filters: [{columnName: "email", condition: "eq", value: "a@b.com"}]},
  data: {score: 15},
  returnData: true
})

Filter conditions: eq, neq, like, ilike, gt, gte, lt, lte

Best practices:

• Use dryRun: true before bulk updates/deletes to verify filter correctness
• Define column types upfront (string, number, boolean, date)
• Use returnType: "count" (default) for insertRows to minimize response size
• deleteRows requires a filter - cannot delete all rows without one

---

Credential Management

n8n_manage_credentials

Unified tool for managing n8n credentials. Supports full CRUD operations, schema discovery, and reverse-lookup of which workflows use each credential.

Actions: list, get, create, update, delete, getSchema

Optional flag: includeUsage (boolean, default false) — on list and get, attaches a usedIn: [{id, name, active}] array and usageCount to every credential by reverse-scanning workflows. Default behavior is unchanged when omitted.

// List all credentials
n8n_manage_credentials({action: "list"})
// → Returns: id, name, type, createdAt, updatedAt (never exposes secrets)

// Get credential by ID
n8n_manage_credentials({action: "get", id: "123"})
// → Returns: credential metadata (data field stripped for security)

// Discover required fields for a credential type
n8n_manage_credentials({action: "getSchema", type: "httpHeaderAuth"})
// → Returns: required fields, types, descriptions

// Create credential
n8n_manage_credentials({
  action: "create",
  name: "My Slack Token",
  type: "slackApi",
  data: {accessToken: "xoxb-..."}
})

// Update credential
n8n_manage_credentials({
  action: "update",
  id: "123",
  name: "Updated Name",
  data: {accessToken: "xoxb-new-..."},
  type: "slackApi"  // Optional, needed by some n8n versions
})

// Delete credential
n8n_manage_credentials({action: "delete", id: "123"})

// List credentials WITH the workflows that reference each one
n8n_manage_credentials({action: "list", includeUsage: true})
// → Each credential gains: usedIn: [{id, name, active}], usageCount: N
//   Response may include usageScanError if the workflow scan failed
//   (base credential list still returned in that case)

// Get one credential and the workflows that reference it
n8n_manage_credentials({action: "get", id: "123", includeUsage: true})
// → Adds usedIn and usageCount; on scan failure, response sets
//   usageScanError and omits usedIn/usageCount

When to use `includeUsage`:

• Pre-deletion safety check: confirm a credential isn't referenced before delete
• Credential rotation impact analysis: list affected workflows before updating secrets
• Remediating findings from n8n_audit_instance (e.g., shared/over-privileged credentials)

`includeUsage` caveats:

• Triggers a full workflow scan client-side (n8n's API has no native lookup) — slower on large instances, especially when scanning hundreds of workflows
• Capped at 5000 workflows (same ceiling as n8n_audit_instance); archived workflows are excluded by n8n
• A "no usages" result does not guarantee the credential is unused — verify before destructive actions
• On scan failure the response degrades gracefully: base credentials are returned with a usageScanError field rather than failing the whole call

Security:

• get, create, and update responses strip the data field (defense-in-depth)
• get action falls back to list+filter if direct GET returns 403/405 (not all n8n versions expose this endpoint)
• Credential request bodies are redacted from debug logs

Best practices:

• Use getSchema before create to discover required fields for a credential type
• The data field contains the actual secret values — provide it only on create/update
• Always verify credential creation by listing afterward
• Before delete, run get with includeUsage: true to see what breaks

---

Security & Audit

n8n_audit_instance

Security audit tool that combines n8n's built-in audit with custom deep scanning of all workflows.

// Full audit (default — runs both built-in + custom scan)
n8n_audit_instance()

// Built-in audit only (specific categories)
n8n_audit_instance({
  categories: ["credentials", "nodes"],
  includeCustomScan: false
})

// Custom scan only (specific checks)
n8n_audit_instance({
  customChecks: ["hardcoded_secrets", "unauthenticated_webhooks"]
})

Built-in audit categories: credentials, database, nodes, instance, filesystem

Custom deep scan checks:

• hardcoded_secrets — Detects 50+ patterns for API keys, tokens, passwords (OpenAI, AWS, Stripe, GitHub, Slack, etc.) plus PII (email, phone, credit card). Secrets are masked in output (first 6 + last 4 chars).
• unauthenticated_webhooks — Flags webhook/form triggers without authentication
• error_handling — Flags workflows with 3+ nodes and no error handling
• data_retention — Flags workflows saving all execution data (success + failure)

Parameters (all optional):

• categories — Array of built-in audit categories
• includeCustomScan — Boolean (default: true)
• customChecks — Array subset of the 4 custom checks
• daysAbandonedWorkflow — Days threshold for abandoned workflow detection

Output: Actionable markdown report with:

• Summary table (critical/high/medium/low finding counts)
• Findings grouped by workflow
• Remediation Playbook with three sections:
• Auto-fixable — Items you can fix with tool chains (e.g., add auth to webhooks)
• Requires review — Items needing human judgment (e.g., PII detection)
• Requires user action — Items needing manual intervention (e.g., rotate exposed keys)

---

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

// Or via tools_documentation
tools_documentation({topic: "ai_agents_guide", depth: "full"})

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_update_full_workflow
• n8n_validate_workflow (by ID)
• n8n_list_workflows, n8n_get_workflow, n8n_delete_workflow
• n8n_test_workflow
• n8n_executions
• n8n_deploy_template
• n8n_workflow_versions
• n8n_autofix_workflow
• n8n_manage_datatable
• n8n_manage_credentials
• n8n_audit_instance

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

---

Best Practices

Do

• For simple workflows (<=5 nodes), use MCP tools directly — don't over-engineer the investigation
• Use patchNodeField for surgical edits to Code node content instead of replacing the entire node
• 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: 1. Use get_node with detail: "standard" (default) - covers 95% of use cases 2. nodeType formats differ: nodes-base.* (search/validate) vs n8n-nodes-base.* (workflows) 3. Specify validation profiles (runtime recommended) 4. Use smart parameters (branch="true", case=0) 5. Include intent parameter in workflow updates 6. Auto-sanitization runs on ALL nodes during updates 7. Workflows can be activated via API (activateWorkflow operation) 8. Workflows are built iteratively (56s avg between edits) 9. Data tables managed with n8n_manage_datatable (CRUD + filtering) 10. Credentials managed with n8n_manage_credentials (CRUD + schema discovery) 11. Security audits via n8n_audit_instance (built-in + custom deep scan) 12. AI agent guide available via ai_agents_guide() tool

Common Workflow: 1. search_nodes → find node 2. get_node → understand config 3. validate_node → check config 4. n8n_create_workflow → build 5. n8n_validate_workflow → verify 6. n8n_update_partial_workflow → iterate 7. 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

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 (18 operation types)
• AI connection types (8 types)

Tool Categories

• Node Discovery (search_nodes, get_node with detail levels and modes)
• 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: standard vs full detail (1-2KB vs 3-8KB) 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 vs get_node({detail: "full"})
• 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!)

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)
  source: "all",       // Optional: all, core, community, verified
  includeExamples: false  // Optional: include template configs
})

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)
• Use source: "core" for only built-in nodes
• Use includeExamples: true for real-world configs

---

get_node (UNIFIED NODE INFORMATION)

The get_node tool provides all node information with different detail levels and modes.

Detail Levels (mode="info")

Standard Detail (RECOMMENDED)

Speed: <10ms | Size: ~1-2K tokens

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

get_node({
  nodeType: "nodes-base.slack",      // Required: SHORT prefix format
  includeExamples: true              // Optional: get real template configs
})
// detail="standard" is the default

Returns:

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

Minimal Detail

Speed: <5ms | Size: ~200 tokens

Use when: Just need basic metadata

get_node({
  nodeType: "nodes-base.slack",
  detail: "minimal"
})

Returns: nodeType, displayName, description, category

Full Detail (USE SPARINGLY)

Speed: <100ms | Size: ~3-8K tokens

Use when: Debugging complex configuration, need complete schema

get_node({
  nodeType: "nodes-base.httpRequest",
  detail: "full"
})

Warning: Large payload! Use standard for most cases.

---

get_node Modes

mode="docs" (READABLE DOCUMENTATION)

Use when: Need human-readable documentation with examples

get_node({
  nodeType: "nodes-base.slack",
  mode: "docs"
})

Returns: Formatted markdown with:

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

Better than raw schema for learning!

mode="search_properties" (FIND SPECIFIC FIELDS)

Use when: Looking for specific property in a node

get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "search_properties",
  propertyQuery: "auth",           // Required for this mode
  maxPropertyResults: 20           // Optional: default 20
})

Returns: Property paths and descriptions matching query

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

mode="versions" (VERSION HISTORY)

Use when: Need to check node version history

get_node({
  nodeType: "nodes-base.executeWorkflow",
  mode: "versions"
})

Returns: Version history with breaking changes flags

mode="compare" (COMPARE VERSIONS)

Use when: Need to see differences between versions

get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "compare",
  fromVersion: "3.0",
  toVersion: "4.1"       // Optional: defaults to latest
})

Returns: Property-level changes between versions

mode="breaking" (BREAKING CHANGES ONLY)

Use when: Checking for breaking changes before upgrades

get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "breaking",
  fromVersion: "3.0"
})

Returns: Only breaking changes (not all changes)

mode="migrations" (AUTO-MIGRATABLE)

Use when: Checking what can be auto-migrated

get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "migrations",
  fromVersion: "3.0"
})

Returns: Changes that can be automatically migrated

---

Additional Parameters

includeTypeInfo

Add type structure metadata (validation rules, JS types)

get_node({
  nodeType: "nodes-base.if",
  includeTypeInfo: true   // Adds ~80-120 tokens per property
})

Use for complex nodes like filter, resourceMapper

includeExamples

Include real-world configuration examples from templates

get_node({
  nodeType: "nodes-base.slack",
  includeExamples: true   // Adds ~200-400 tokens per example
})

Only works with mode: "info" and detail: "standard"

---

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({
  nodeType: "nodes-base.slack",
  includeExamples: true
})
→ Returns: operations list + example configs

Step 3: Validate Config
validate_node({
  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 → get_node (18s average)

---

Quick Comparison

Best Practice: search → get_node(standard) → 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 get_node, validate_node
  "workflowNodeType": "n8n-nodes-base.slack"  // Use with n8n_create_workflow
}

---

Examples

Find and Configure HTTP Request

// Step 1: Search
search_nodes({query: "http request"})

// Step 2: Get standard info
get_node({nodeType: "nodes-base.httpRequest"})

// Step 3: Find auth options
get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "search_properties",
  propertyQuery: "authentication"
})

// Step 4: Validate config
validate_node({
  nodeType: "nodes-base.httpRequest",
  config: {method: "POST", url: "https://api.example.com"},
  profile: "runtime"
})

Explore AI Nodes

// Find all AI-related nodes
search_nodes({query: "ai agent", source: "all"})

// Get AI Agent documentation
get_node({nodeType: "nodes-langchain.agent", mode: "docs"})

// Get configuration details with examples
get_node({
  nodeType: "nodes-langchain.agent",
  includeExamples: true
})

Check Version Compatibility

// See all versions
get_node({nodeType: "nodes-base.executeWorkflow", mode: "versions"})

// Check breaking changes from v1 to v2
get_node({
  nodeType: "nodes-base.executeWorkflow",
  mode: "breaking",
  fromVersion: "1.0"
})

---

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 (UNIFIED VALIDATION)

The validate_node tool provides all validation capabilities with different modes.

Quick Check (mode="minimal")

Speed: <50ms

Use when: Checking what fields are required

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

Returns:

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

When to use: Planning configuration, seeing basic requirements

Full Validation (mode="full", DEFAULT)

Speed: <100ms

Use when: Validating actual configuration before deployment

validate_node({
  nodeType: "nodes-base.slack",
  config: {
    resource: "channel",
    operation: "create",
    channel: "general"
  },
  profile: "runtime"  // Recommended!
})
// mode="full" is the default

---

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

---

Validation Response

{
  "nodeType": "nodes-base.slack",
  "workflowNodeType": "n8n-nodes-base.slack",
  "displayName": "Slack",
  "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,
    "suggestionCount": 0
  }
}

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)

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

Validate by Workflow ID

// Validate workflow already in n8n
n8n_validate_workflow({
  id: "workflow-id",
  options: {
    validateNodes: true,
    validateConnections: true,
    validateExpressions: true,
    profile: "runtime"
  }
})

---

Validation Loop Pattern

Typical cycle: 23s thinking, 58s fixing

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

Example:

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

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

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

const result2 = validate_node({
  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({id}) - preview/apply fixes

---

n8n_autofix_workflow (AUTO-FIX TOOL)

Use when: Validation errors need automatic fixes

// Preview fixes (default - doesn't apply)
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: false,  // Preview mode
  confidenceThreshold: "medium"  // high, medium, low
})

// Apply fixes
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: true
})

Fix Types:

• expression-format - Fix missing = prefix in expressions
• typeversion-correction - Downgrade unsupported typeVersions
• error-output-config - Remove conflicting onError settings
• node-type-correction - Fix unknown node types via similarity matching (90%+ confidence)
• webhook-missing-path - Generate UUIDs for webhook nodes missing paths
• typeversion-upgrade - Smart upgrade nodes to latest versions with auto-migration
• version-migration - Guidance for complex breaking changes (manual steps)

Confidence Threshold: high (90%+), medium (70-89%, default), low (any)

Post-update guidance: Check postUpdateGuidance in the response for version upgrade migration steps.

---

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 get_node output

"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 mode: "minimal" for quick checks
• Use n8n_autofix_workflow for bulk fixes
• Activate workflows via API when ready (activateWorkflow operation)

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 (quick check)
validate_node({
  nodeType: "nodes-base.slack",
  config: {},
  mode: "minimal"
});
// → Know what's required

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

// Step 3: Validate configuration (full validation)
const result = validate_node({
  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: {...}
  }
});

// Step 6: Apply auto-fixes if needed
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: true
});

---

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 6. Use n8n_autofix_workflow for automatic fixes

Tool Selection:

• validate_node({mode: "minimal"}): Quick required fields check
• validate_node({profile: "runtime"}): Full config validation (use this!)
• validate_workflow: Complete workflow check
• n8n_validate_workflow({id}): Validate existing workflow
• n8n_autofix_workflow({id}): Auto-fix common issues

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

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: 2,
      position: [250, 300],
      parameters: {
        path: "slack-notify",
        httpMethod: "POST"
      }
    },
    {
      id: "slack-1",
      name: "Slack",
      type: "n8n-nodes-base.slack",
      typeVersion: 2,
      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 (activate with activateWorkflow operation)
• Auto-sanitization runs on creation
• Validate before creating for best results

---

n8n_update_partial_workflow (MOST USED!)

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

Use when: Making incremental changes to workflows

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

19 Operation Types

Node Operations (7 types): 1. addNode - Add new node 2. removeNode - Remove node by ID or name 3. updateNode - Update node properties (use dot notation) 4. patchNodeField - Surgical string edits via strict find/replace (see below) 5. moveNode - Change position 6. enableNode - Enable disabled node 7. disableNode - Disable active node

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

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

Activation Operations (2 types): 17. activateWorkflow - Activate workflow for automatic execution 18. deactivateWorkflow - Deactivate workflow

Project Management Operations (1 type): 19. transferWorkflow - Transfer workflow to a different project (enterprise/cloud)

Intent Parameter (IMPORTANT!)

Always include intent for better responses:

n8n_update_partial_workflow({
  id: "workflow-id",
  intent: "Add error handling for API failures",  // Describe what you're doing
  operations: [...]
})

Smart Parameters

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

Property Removal with null

Remove properties by setting them to null:

// Remove a property
{
  type: "updateNode",
  nodeName: "HTTP Request",
  updates: { onError: null }
}

// Migrate from deprecated property
{
  type: "updateNode",
  nodeName: "HTTP Request",
  updates: {
    continueOnFail: null,  // Remove old
    onError: "continueErrorOutput"  // Add new
  }
}

patchNodeField (Surgical String Edits)

Use patchNodeField for strict find/replace edits on string fields — code, HTML, email templates, JSON bodies. Unlike updateNode with __patch_find_replace (which silently warns on misses), patchNodeField is strict: it errors if the find string is not found, and errors if multiple matches are found (preventing ambiguous replacements).

When to use which:

• patchNodeField — preferred for most string edits. Strict error handling catches mistakes early.
• updateNode with __patch_find_replace — legacy approach. Tolerant (warns but continues on miss). Use only when you want lenient behavior.

Syntax:

{
  type: "patchNodeField",
  nodeName: "Code",           // or nodeId
  fieldPath: "parameters.jsCode",  // Dot-notation path to the string field
  patches: [
    {
      find: "const limit = 10;",
      replace: "const limit = 50;",
      replaceAll: false,       // Default: false. Set true to replace all occurrences
      regex: false             // Default: false. Set true to treat find as regex
    }
  ]
}

Examples:

// Basic strict find/replace in code
n8n_update_partial_workflow({
  id: "wf-123",
  intent: "Update API limit",
  operations: [{
    type: "patchNodeField",
    nodeName: "Code",
    fieldPath: "parameters.jsCode",
    patches: [{find: "const limit = 10;", replace: "const limit = 50;"}]
  }]
})

// Replace all occurrences of a URL
n8n_update_partial_workflow({
  id: "wf-123",
  intent: "Migrate API domain",
  operations: [{
    type: "patchNodeField",
    nodeName: "Code",
    fieldPath: "parameters.jsCode",
    patches: [{find: "api.old.com", replace: "api.new.com", replaceAll: true}]
  }]
})

// Regex-based replacement (whitespace-insensitive)
n8n_update_partial_workflow({
  id: "wf-123",
  intent: "Update limit with regex",
  operations: [{
    type: "patchNodeField",
    nodeName: "Code",
    fieldPath: "parameters.jsCode",
    patches: [{find: "const\\s+limit\\s*=\\s*\\d+", replace: "const limit = 100", regex: true}]
  }]
})

// Multiple sequential patches on an email template
n8n_update_partial_workflow({
  id: "wf-123",
  intent: "Update email footer",
  operations: [{
    type: "patchNodeField",
    nodeName: "Set Email",
    fieldPath: "parameters.assignments.assignments.6.value",
    patches: [
      {find: "© 2025", replace: "© 2026"},
      {find: "<p>Unsubscribe</p>", replace: ""}
    ]
  }]
})

Error behavior (this is what makes it strict):

• Find string not found → operation fails with error (not a silent warning)
• Multiple matches without `replaceAll` → operation fails (ambiguity detected)
• Patches are applied sequentially — order matters

Security limits:

• Max 50 patches per operation
• Regex patterns capped at 500 characters
• Regex only on fields under 512KB
• ReDoS-safe: rejects nested quantifiers like (a+)+ and overlapping alternations like (\w|\d)+
• Prototype pollution protection on field paths

Activation Operations

// Activate workflow
n8n_update_partial_workflow({
  id: "workflow-id",
  intent: "Activate workflow for production",
  operations: [{type: "activateWorkflow"}]
})

// Deactivate workflow
n8n_update_partial_workflow({
  id: "workflow-id",
  intent: "Deactivate workflow for maintenance",
  operations: [{type: "deactivateWorkflow"}]
})

Example Usage

n8n_update_partial_workflow({
  id: "workflow-id",
  intent: "Add transform node after IF condition",
  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"}

rewireConnection - Change target atomically:

{
  type: "rewireConnection",
  source: "Webhook",
  from: "Old Handler",
  to: "New Handler"
}

Best-effort mode - Apply what works:

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

Validate before applying:

n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [...],
  validateOnly: true  // Preview without applying
})

---

n8n_deploy_template (QUICK START!)

Speed: 200-500ms

Use when: Deploying a template directly to n8n instance

n8n_deploy_template({
  templateId: 2947,  // Required: from n8n.io
  name: "My Weather to Slack",  // Optional: custom name
  autoFix: true,  // Default: auto-fix common issues
  autoUpgradeVersions: true,  // Default: upgrade node versions
  stripCredentials: true  // Default: remove credential refs
})

Returns:

• Workflow ID
• Required credentials
• Fixes applied

Example:

// Deploy a webhook to Slack template
const result = n8n_deploy_template({
  templateId: 2947,
  name: "Production Slack Notifier"
});

// Result includes:
// - id: "new-workflow-id"
// - requiredCredentials: ["slack"]
// - fixesApplied: ["typeVersion upgraded", "expression format fixed"]

---

n8n_generate_workflow (NATURAL LANGUAGE → WORKFLOW)

Speed: Proposals ~2s, fresh generation 5–15s, deploy ~3s

Use when: User describes the workflow in plain English and wants the system to draft (and optionally deploy) it.

⚠️ Hosted-only feature. On self-hosted instances the tool returns {hosted_only: true} with a redirect message rather than a workflow. For self-hosted, use n8n_deploy_template (templates) or n8n_create_workflow (manual).

How It Works

It's a multi-step flow with a review checkpoint — proposals/preview are returned first, deployment requires a second call. This avoids deploying low-quality drafts.

Path A: Proposals → Deploy (default, recommended)

// Step 1: Generate proposals (NOT deployed, returns up to 5 candidates)
n8n_generate_workflow({
  description: "Slack daily standup reminder at 9am every weekday"
})
// → {
//     status: "proposals",
//     proposals: [
//       {
//         id: "uuid-1",
//         name: "Daily Standup Reminder",
//         description: "...",
//         flow_summary: "Schedule trigger → Slack message",
//         credentials_needed: ["slackApi"]
//       },
//       ...
//     ]
//   }

// Step 2: Deploy the proposal you picked
n8n_generate_workflow({
  description: "Slack daily standup reminder at 9am every weekday",
  deploy_id: "uuid-1"
})
// → { status: "deployed", workflow_id, workflow_name, workflow_url,
//     node_count, node_summary }

Path B: Skip Cache → Preview → Confirm

Use when none of the proposals match what you want.

// Step 1: Bypass proposals; get a fresh preview (NOT deployed)
n8n_generate_workflow({
  description: "Webhook receives JSON, transforms it, POSTs to a REST API",
  skip_cache: true
})
// → { status: "preview", ... }

// Step 2: Deploy the preview
n8n_generate_workflow({
  description: "Webhook receives JSON, transforms it, POSTs to a REST API",
  confirm_deploy: true
})
// → { status: "deployed", ... }

Writing a Good Description

The quality of the generated workflow is bound by the clarity of the description. Always include:

• Trigger type: webhook, schedule (with cadence — "every 15 min", "weekdays at 9am"), manual, form, chat
• Services involved: name them explicitly (Slack, Gmail, HubSpot, Postgres, etc.) — generic terms ("a chat tool") yield generic results
• Logic / flow: branches, transforms, aggregation, deduplication, retry behavior

Bad: "Send a notification when something happens"

Good: "When a new row is added to the 'leads' Postgres table, enrich it with Clearbit, then post a summary to the #sales Slack channel. Skip rows where 'company' is empty."

Parameters

Common Pitfalls

• Hosted-only — on self-hosted, no workflow is generated; fall back to n8n_deploy_template or n8n_create_workflow
• Proposals are NOT deployed — until you call again with deploy_id or confirm_deploy, nothing exists in n8n
• Inactive on deploy — generated workflows are created in inactive state; credentials must be configured in the n8n UI before activation
• Per-session state — pending proposals/preview live in MCP-session state; reconnecting loses them, and you'll need to re-issue the description

Recommended Follow-Up

Always validate after deploying:

n8n_generate_workflow({description: "...", deploy_id: "uuid-1"})
// → workflow_id: "abc"

n8n_validate_workflow({id: "abc"})
// → catches any node-version or connection issues the generator missed

// If issues found, n8n_autofix_workflow can resolve common ones
n8n_autofix_workflow({id: "abc", applyFixes: true})

---

n8n_workflow_versions (VERSION CONTROL)

Use when: Managing workflow history, rollback, cleanup

List Versions

n8n_workflow_versions({
  mode: "list",
  workflowId: "workflow-id",
  limit: 10
})

Get Specific Version

n8n_workflow_versions({
  mode: "get",
  versionId: 123
})

Rollback to Previous Version

n8n_workflow_versions({
  mode: "rollback",
  workflowId: "workflow-id",
  versionId: 123,  // Optional: specific version
  validateBefore: true  // Default: validate before rollback
})

Delete Versions

// Delete specific version
n8n_workflow_versions({
  mode: "delete",
  workflowId: "workflow-id",
  versionId: 123
})

// Delete all versions for workflow
n8n_workflow_versions({
  mode: "delete",
  workflowId: "workflow-id",
  deleteAll: true
})

Prune Old Versions

n8n_workflow_versions({
  mode: "prune",
  workflowId: "workflow-id",
  maxVersions: 10  // Keep 10 most recent
})

---

n8n_test_workflow (TRIGGER EXECUTION)

Use when: Testing workflow execution

Auto-detects trigger type (webhook, form, chat)

// Test webhook workflow
n8n_test_workflow({
  workflowId: "workflow-id",
  triggerType: "webhook",  // Optional: auto-detected
  httpMethod: "POST",
  data: {message: "Hello!"},
  waitForResponse: true,
  timeout: 120000
})

// Test chat workflow
n8n_test_workflow({
  workflowId: "workflow-id",
  triggerType: "chat",
  message: "Hello, AI agent!",
  sessionId: "session-123"  // For conversation continuity
})

---

n8n_manage_credentials (CREDENTIAL MANAGEMENT)

Speed: 50-500ms

Use when: Creating, updating, listing, or deleting credentials; discovering credential schemas

6 Actions

1. list - List all credentials (id, name, type, timestamps) 2. get - Get credential by ID (data field stripped) 3. create - Create credential (requires name, type, data) 4. update - Update credential by ID (name, data, and/or type) 5. delete - Permanently delete credential by ID 6. getSchema - Discover required fields for a credential type

list and get also accept an optional includeUsage: true flag that attaches workflow-usage info to each credential (see "Find Which Workflows Use a Credential" below).

List Credentials

n8n_manage_credentials({action: "list"})
// → [{id, name, type, createdAt, updatedAt}, ...]

Get Credential

n8n_manage_credentials({action: "get", id: "123"})
// → {id, name, type, ...} (data field stripped for security)
// Falls back to list+filter if GET returns 403/405

Find Which Workflows Use a Credential

n8n's public API has no native "which workflows use credential X" endpoint, so n8n-mcp builds the reverse index for you by scanning workflows client-side. Pass includeUsage: true to either list or get.

// Every credential, with the workflows that reference it
n8n_manage_credentials({action: "list", includeUsage: true})
// → {
//     credentials: [
//       {
//         id: "123",
//         name: "Production Slack",
//         type: "slackApi",
//         createdAt: "...", updatedAt: "...",
//         usedIn: [
//           {id: "wf_abc", name: "Daily digest",  active: true},
//           {id: "wf_xyz", name: "Alert fan-out", active: false}
//         ],
//         usageCount: 2
//       },
//       ...
//     ],
//     count: N,
//     // usageScanError: "..."  // present only if the workflow scan failed
//   }

// One credential, with its workflow references
n8n_manage_credentials({action: "get", id: "123", includeUsage: true})
// → Same shape as `get` plus usedIn and usageCount.
//   On scan failure: response sets usageScanError and omits usedIn/usageCount.

When to use it:

• Before delete: confirm nothing references the credential
• Before rotating a secret with update: see exactly which workflows you'll affect
• After n8n_audit_instance flags a credential: locate the workflows that need remediation

Behavior and limits:

• The reverse index is built client-side, deduplicated per workflow, and capped at 5000 workflows (same ceiling as n8n_audit_instance)
• Archived workflows are excluded by n8n's API — a "no usages" result does not prove a credential is unused; verify before destructive actions
• Triggers one full workflow scan per call. On large instances expect slower responses than the base ~50–500ms — budget accordingly when calling repeatedly
• If the scan fails, the response degrades to base credentials with a usageScanError field rather than failing the whole call
• Default behavior unchanged: omit the flag and no extra API calls happen

Discover Schema

n8n_manage_credentials({
  action: "getSchema",
  type: "httpHeaderAuth"
})
// → Required fields, types, descriptions for this credential type

Create Credential

n8n_manage_credentials({
  action: "create",
  name: "My Slack Token",
  type: "slackApi",
  data: {accessToken: "xoxb-your-token"}
})
// → Created credential (data field stripped from response)

Update Credential

n8n_manage_credentials({
  action: "update",
  id: "123",
  name: "Updated Slack Token",
  data: {accessToken: "xoxb-new-token"},
  type: "slackApi"  // Optional, some n8n versions require it
})
// → Updated credential (data field stripped from response)

Delete Credential

n8n_manage_credentials({action: "delete", id: "123"})

Typical Workflow: Set Up Credentials for a New Integration

// 1. Discover what fields are needed
n8n_manage_credentials({
  action: "getSchema",
  type: "slackApi"
})

// 2. Create the credential
n8n_manage_credentials({
  action: "create",
  name: "Production Slack",
  type: "slackApi",
  data: {accessToken: "xoxb-..."}
})

// 3. Verify it was created
n8n_manage_credentials({action: "list"})

Typical Workflow: Safely Delete or Rotate a Credential

// 1. Check what would break
n8n_manage_credentials({action: "get", id: "123", includeUsage: true})
// → Inspect usedIn — the {id, name, active} of every workflow that references it

// 2a. If nothing depends on it, delete
n8n_manage_credentials({action: "delete", id: "123"})

// 2b. If something does, rotate the secret instead and notify owners
n8n_manage_credentials({
  action: "update",
  id: "123",
  data: {accessToken: "xoxb-new-..."}
})

Security Notes

• Response stripping: get, create, and update all strip the data field from responses (defense-in-depth — secrets are never returned)
• Log redaction: Credential request bodies are redacted from debug logs
• Fallback resilience: get falls back to list+filter when GET /credentials/:id returns 403/405 (endpoint not in all n8n versions)
• Usage scan resilience: when includeUsage: true triggers a workflow scan that fails, the response includes usageScanError and still returns the base credentials rather than erroring out

---

n8n_audit_instance (SECURITY AUDIT)

Speed: 500-5000ms (scans all workflows)

Use when: Auditing instance security, finding hardcoded secrets, checking for unauthenticated webhooks, verifying error handling

Two Scanning Approaches

1. Built-in Audit (via n8n's POST /audit API):

• 5 risk categories: credentials, database, nodes, instance, filesystem
• Wraps n8n's native audit endpoint; gracefully degrades if unavailable

2. Custom Deep Scan (workflow analysis):

• hardcoded_secrets — 50+ regex patterns for API keys/tokens/passwords plus PII detection
• unauthenticated_webhooks — Webhook/form triggers without authentication
• error_handling — Workflows with 3+ nodes and no error handling
• data_retention — Workflows saving all execution data

Examples

// Full audit (default)
n8n_audit_instance()

// Built-in audit only
n8n_audit_instance({
  categories: ["credentials", "nodes", "instance"],
  includeCustomScan: false
})

// Custom scan only — specific checks
n8n_audit_instance({
  customChecks: ["hardcoded_secrets", "unauthenticated_webhooks"]
})

// Custom abandoned workflow threshold
n8n_audit_instance({
  daysAbandonedWorkflow: 90
})

Output

Returns an actionable markdown report with:

• Summary table: Critical/high/medium/low finding counts
• Findings by workflow: Per-workflow tables of issues
• Built-in audit results: n8n's native audit findings
• Remediation Playbook:
• Auto-fixable items (with tool chains to apply)
• Items requiring review (human judgment needed)
• Items requiring user action (e.g., key rotation)

Secret Masking

Detected secrets are masked in output — shows first 6 + last 4 characters only. Raw values are never stored or returned.

Remediation Types

• auto_fixable — Can be fixed with MCP tools (e.g., add webhook auth)
• review_recommended — Needs human judgment (e.g., PII detection)
• user_input_needed — Requires user decision (e.g., choose auth method)
• user_action_needed — Manual action required (e.g., rotate exposed API key)

---

n8n_validate_workflow (by ID)

Use when: Validating workflow stored in n8n

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

---

n8n_get_workflow

Use when: Retrieving workflow details

Modes:

• full (default) - Complete workflow JSON
• details - Full + execution stats
• structure - Nodes + connections only
• minimal - ID, name, active, tags

// Full workflow
n8n_get_workflow({id: "workflow-id"})

// Just structure
n8n_get_workflow({id: "workflow-id", mode: "structure"})

// Minimal metadata
n8n_get_workflow({id: "workflow-id", mode: "minimal"})

---

n8n_executions (EXECUTION MANAGEMENT)

Use when: Managing workflow executions

Get Execution Details

n8n_executions({
  action: "get",
  id: "execution-id",
  mode: "summary"  // preview, summary, filtered, full, error
})

// Error mode for debugging
n8n_executions({
  action: "get",
  id: "execution-id",
  mode: "error",
  includeStackTrace: true
})

List Executions

n8n_executions({
  action: "list",
  workflowId: "workflow-id",
  status: "error",  // success, error, waiting
  limit: 100
})

Delete Execution

n8n_executions({
  action: "delete",
  id: "execution-id"
})

---

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, intent: "...", operations: [...]})
   → Make changes

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

5. ACTIVATE
   n8n_update_partial_workflow({
     id,
     intent: "Activate workflow",
     operations: [{type: "activateWorkflow"}]
   })
   → Workflow now runs on triggers!

6. MONITOR
   n8n_executions({action: "list", workflowId: id})
   n8n_executions({action: "get", id: execution_id})

---

Common Patterns from Telemetry

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

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

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

n8n_validate_workflow({id})
// ↓ 58s (fixing errors)
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!

---

Best Practices

Do

• Build workflows iteratively (avg 56s between edits)
• Include intent parameter for better responses
• 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
• Use n8n_deploy_template for quick starts
• Activate workflows via API when ready

Don't

• Try to build workflows in one shot
• Skip the intent parameter
• 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, 19 operation types) 2. Include intent parameter for better responses 3. Workflows built iteratively (56s avg between edits) 4. Use smart parameters (branch="true", case=0) for clarity 5. patchNodeField for surgical string edits (strict find/replace with regex support) 6. AI connections supported (8 types with sourceOutput) 7. Workflow activation supported via API (activateWorkflow operation) 8. Auto-sanitization runs on all operations 9. Use n8n_deploy_template for quick starts

Additional Tools:

• n8n_deploy_template - Deploy templates directly
• n8n_workflow_versions - Version control & rollback
• n8n_test_workflow - Trigger execution
• n8n_executions - Manage executions
• n8n_manage_datatable - Data table and row management
• n8n_manage_credentials - Credential CRUD + schema discovery
• n8n_audit_instance - Security audit (built-in + custom scan)
• n8n_delete_workflow - Permanently delete workflows
• n8n_list_workflows - List workflows with filtering
• n8n_update_full_workflow - Full workflow replacement

Related:

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