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: Node JSON Hygiene When Creating Workflows

Three structural mistakes in generated node JSON break the n8n UI even when the workflow validates:

1. Never emit a `credentials` block with a placeholder ID. A fake ID like "id": "REPLACE_ME" renders the credential selector permanently disabled and non-clickable in the n8n UI ("No credentials yet") — the user has to recreate the node from scratch. If you don't know the real credential ID, omit the `credentials` block entirely; an absent block shows a normal empty dropdown the user can click. Use n8n_manage_credentials({action: "list"}) to discover real credential IDs first.

// ❌ Breaks the credential selector
"credentials": {"httpHeaderAuth": {"id": "REPLACE_ME", "name": "My API Key"}}

// ✅ Unknown ID → omit credentials block; user picks in UI
// ✅ Known ID (from n8n_manage_credentials list) → use the real ID

2. Generate UUID v4 values for node `id` — not human-readable strings like "http-list-node". n8n's frontend uses node IDs for form binding and credential component initialization; non-UUID IDs cause subtle UI breakage.

3. Use the current `typeVersion` for each node — check get_node rather than hardcoding remembered versions (e.g. httpRequest is at 4.4+, not 4.2).

---

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

Eight recurring mistakes. Two are worth showing in full because they silently corrupt structure:

// nodeType prefix (search/validate tools want the SHORT form)
get_node({nodeType: "slack"})              // ❌ missing prefix → "Node not found"
get_node({nodeType: "n8n-nodes-base.slack"}) // ❌ FULL prefix is for workflow tools
get_node({nodeType: "nodes-base.slack"})     // ✅

// credentials must be nested by type with {id, name} — not a flat string
updates: {credentials: "myApiKey"}                              // ❌
updates: {credentials: {httpHeaderAuth: {id: "abc123", name: "My API Key"}}}  // ✅

Full WRONG/CORRECT examples for each: see VALIDATION_GUIDE.md → Common Mistakes.

---

Tool Usage Patterns

Three patterns dominate real usage. Worked, step-by-step examples for each live in the reference guides.

• Pattern 1 — Node Discovery (18s avg between steps): search_nodes({query}) → get_node({nodeType, includeExamples: true}). See SEARCH_GUIDE.md.
• Pattern 2 — Validation Loop (23s thinking, 58s fixing): validate_node({profile: "runtime"}) → read errors → fix config → validate again until clean. See VALIDATION_GUIDE.md.
• Pattern 3 — Workflow Editing (99.0% success, 56s avg between edits): iterate n8n_update_partial_workflow (with intent) → n8n_validate_workflow → finally activateWorkflow. Build iteratively, NOT one-shot. See WORKFLOW_GUIDE.md.

---

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_generate_workflow
• n8n_workflow_versions
• n8n_manage_credentials (credential CRUD + schema discovery)
• n8n_audit_instance (security auditing)

Templates, Data Tables & Self-Help

See OPERATIONS_GUIDE.md for:

• search_templates / get_template / n8n_deploy_template examples
• n8n_manage_datatable (full actions, filter conditions, examples)
• tools_documentation, ai_agents_guide, n8n_health_check

---

Template Usage

The 2,700+ template library has three tools: search_templates (modes query/by_nodes/by_task/by_metadata), get_template (modes structure/full), and n8n_deploy_template (deploys to your instance with autoFix/autoUpgradeVersions, returns workflow ID + required credentials + fixes applied).

See OPERATIONS_GUIDE.md for full search/get/deploy examples.

---

Workflow Generation

n8n_generate_workflow turns a natural-language description into a workflow via a review checkpoint. Hosted-only — self-hosted gets {hosted_only: true} with a redirect (fall back to n8n_deploy_template or n8n_create_workflow). Two paths: Path A (default) returns up to 5 proposals, then deploy one with deploy_id; Path B uses skip_cache: true for a fresh preview, then confirm_deploy: true. Deployed workflows are inactive (configure credentials in UI first); always n8n_validate_workflow after. More specific descriptions (trigger type, named services, logic/flow) yield better results.

When to use which: n8n_deploy_template (curated library) · n8n_generate_workflow (plain English, hosted only) · n8n_create_workflow (node-by-node control).

See WORKFLOW_GUIDE.md for both paths, parameters, and pitfalls in full.

---

Data Table Management

n8n_manage_datatable is the MCP tool for managing data tables and rows from outside a workflow (table actions createTable/listTables/getTable/updateTable/deleteTable; row actions getRows/insertRows/updateRows/upsertRows/deleteRows, with filtering, pagination, and dryRun). Don't confuse it with the in-workflow nodes-base.dataTable node, which reads/writes rows during execution (see n8n-node-configuration → OPERATION_PATTERNS.md). Rule of thumb: MCP tool to set up a table once, workflow node to read/write on every execution. deleteRows requires a filter; use dryRun: true before bulk changes.

See OPERATIONS_GUIDE.md for all actions, filter conditions, and examples.

---

Credential Management

n8n_manage_credentials is the unified credential tool: actions list, get, create, update, delete, getSchema. It never returns secrets — get/create/update strip the data field. Use getSchema before create to discover required fields. The optional includeUsage: true flag (on list/get) reverse-scans workflows and attaches usedIn: [{id, name, active}] + usageCount — use it before deleting or rotating a credential to see what breaks (it triggers a full client-side scan, caps at 5000 workflows, excludes archived, and degrades to a usageScanError field on failure).

See WORKFLOW_GUIDE.md for all actions, the includeUsage shape, security notes, and the safe delete/rotate workflow.

---

Security & Audit

n8n_audit_instance combines n8n's built-in audit (categories credentials/database/nodes/instance/filesystem) with a custom deep scan (hardcoded_secrets, unauthenticated_webhooks, error_handling, data_retention). All parameters optional: categories, includeCustomScan (default true), customChecks, daysAbandonedWorkflow. Detected secrets are masked (first 6 + last 4 chars). Output is an actionable markdown report — summary table, findings by workflow, and a Remediation Playbook split into auto-fixable / requires-review / requires-user-action.

See WORKFLOW_GUIDE.md for the two scanning approaches, examples, and remediation types in full.

---

Self-Help Tools

• tools_documentation() — overview of all tools; tools_documentation({topic, depth: "full"}) for a specific tool. Code node guides via topics javascript_code_node_guide / python_code_node_guide.
• AI agent guide — tools_documentation({topic: "ai_agents_guide", depth: "full"}) (no standalone tool); returns architecture, connections, tools, validation, best practices.
• n8n_health_check() — quick check; n8n_health_check({mode: "diagnostic"}) returns status, env vars, tool status, API connectivity.

See OPERATIONS_GUIDE.md for examples.

---

Tool Availability

Always Available (no n8n API needed):

• search_nodes, get_node
• validate_node, validate_workflow
• search_templates, get_template
• tools_documentation (includes the ai_agents_guide topic)

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` — detail levels (minimal ~200 tok / standard ~1-2K, RECOMMENDED / full ~3-8K, sparingly) and modes (info default, docs, search_properties + propertyQuery, versions, compare, breaking, migrations). Deep dive in SEARCH_GUIDE.md.
• `validate_node` — modes full (default, errors/warnings/suggestions) and minimal (required-fields check); profiles minimal/runtime (default, recommended)/ai-friendly/strict. Deep dive in VALIDATION_GUIDE.md.

---

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 tools_documentation({topic: "ai_agents_guide", depth: "full"})

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 + common mistakes
• WORKFLOW_GUIDE.md - Workflow management
• OPERATIONS_GUIDE.md - Templates, data tables, self-help tools

---

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

Templates, Data Tables & Self-Help Tools Guide

Reference depth for template search/deploy, data table management, and the self-help/diagnostic tools.

---

Template Library

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

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

get_template({
  templateId: 2947,
  mode: "full"  // complete workflow JSON
});

n8n_deploy_template (Deploy 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

(Full deploy parameters and a worked example also appear in WORKFLOW_GUIDE.md.)

---

Data Table Management

Two surfaces, don't confuse them:

- `n8n_manage_datatable` (below) — MCP tool for managing tables and rows from outside a workflow (e.g. creating tables during workflow scaffolding, seeding data, or inspecting state from Claude). Covered here.

- `nodes-base.dataTable` node — the in-workflow node you drop into a workflow to read/write rows during execution. For its parameter shapes, operation values, filter syntax, and gotchas (e.g. the deleteRows reserved-word workaround, the id isNotEmpty trick for "all rows"), see n8n-node-configuration → OPERATION_PATTERNS.md → Storage Nodes → Data Table.

>

Rule of thumb: use the MCP tool to set up a table once and the workflow node to read/write rows on every execution.

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

---

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 — accessed via tools_documentation
// (there is no standalone ai_agents_guide tool)
tools_documentation({topic: "ai_agents_guide", depth: "full"})
// 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

---

Related

• SEARCH_GUIDE.md - Node discovery
• VALIDATION_GUIDE.md - Configuration validation
• WORKFLOW_GUIDE.md - Workflow management (incl. credentials, audit, generation)

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

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 - Core tool usage guide
• SEARCH_GUIDE.md - Node discovery tools
• VALIDATION_GUIDE.md - Validation tools and profiles
• WORKFLOW_GUIDE.md - 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

---

Common Mistakes (Full Deep-Dive)

The eight most common tool-usage mistakes, with WRONG vs CORRECT examples.

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: {...}}]
})

---

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

n8n has a draft/publish model: the workflow body holds the draft (your latest edits), while mode: "active" returns the published graph that's actually running. Pick the mode by how much you need and how big the workflow is.

Modes:

• full (default) - Draft workflow JSON + metadata
• details - Full + execution stats (success/error counts, last run)
• active - The published (running) graph; returns code: "NO_ACTIVE_VERSION" if the workflow was never activated
• structure - Nodes + connections only (topology, no parameters)
• filtered - Full config of only the nodes named in nodeNames (matched by node name or node id), plus light metadata. Use it to read one heavy node — e.g. a Code node with long jsCode/pythonCode — on a large workflow that would otherwise get truncated client-side when fetched whole
• minimal - ID, name, active, tags (fastest)

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

// Just the topology (cheap; strips parameters)
n8n_get_workflow({id: "workflow-id", mode: "structure"})

// Read one heavy node without the whole workflow (avoids client-side truncation)
n8n_get_workflow({id: "workflow-id", mode: "filtered", nodeNames: ["Process Data"]})

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

Recommended flow for big workflows: mode: "structure" to discover node names cheaply → mode: "filtered" with those names to pull the specific heavy node's full config. This is the fix for the case where full/active returns a payload large enough that the client truncates it and you can't read the Code-node source at all.

`filtered` mode returns: { id, name, active, isArchived, nodes[] (full config of matched nodes only), nodeCount (total in workflow), returnedCount, notFound? }. It omits connections and the rest of the graph by design, so the response stays small.

`filtered` pitfalls:

• Requires a non-empty nodeNames array. Entries that match nothing come back in a notFound list rather than erroring, so a partial request stays transparent — check notFound before assuming a node is missing.
• nodeNames matches each entry against node name OR id in one namespace, so returnedCount can exceed nodeNames.length when a name collides with another node's id, or when the workflow has duplicate node names. Disambiguate by the id on each returned node.

---

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