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 → [SEARCHGUIDE.md](SEARCHGUIDE.md)
2. Configuration Validation → [VALIDATIONGUIDE.md](VALIDATIONGUIDE.md)
3. Workflow Management → [WORKFLOWGUIDE.md](WORKFLOWGUIDE.md)
4. Template Library - Search and deploy 2,700+ real workflows
5. Data Tables - Manage n8n data tables, rows and columns (n8nmanagedatatable)
6. Workflow Folders - Folder CRUD + workflow placement (n8nmanagefolders)
7. Credential Management - Full credential CRUD + schema discovery (n8nmanagecredentials)
8. Security & Audit - Instance security auditing with custom deep scan (n8nauditinstance)
9. Documentation & Guides - Tool docs, AI agent guide, Code node guides
10. Agents - Create, configure, validate, run and publish persisted n8n Agents (n8nmanageagents, requires N8NMCPACCESS_TOKEN)
11. Node Resource Resolution - Resolve live dropdown/resource-locator values with a real credential (n8nexplorenoderesources, requires N8NMCPACCESSTOKEN)
12. Instance Catalog - List projects and tags (n8nlistcatalog)

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": "REPLACEME" 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 n8nmanage_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

1. 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.

1. 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:

• n8ncreateworkflow
• n8nupdatepartial_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 [VALIDATIONGUIDE.md → Common Mistakes](VALIDATIONGUIDE.md).

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): searchnodes({query}) → getnode({nodeType, includeExamples: true}). See [SEARCHGUIDE.md](SEARCHGUIDE.md).
• Pattern 2 — Validation Loop (23s thinking, 58s fixing): validatenode({profile: "runtime"}) → read errors → fix config → validate again until clean. See [VALIDATIONGUIDE.md](VALIDATION_GUIDE.md).
• Pattern 3 — Workflow Editing (99.0% success, 56s avg between edits): iterate n8nupdatepartialworkflow (with intent) → n8nvalidateworkflow → finally activateWorkflow. Build iteratively, NOT one-shot. See [WORKFLOWGUIDE.md](WORKFLOW_GUIDE.md).

Detailed Guides

Node Discovery Tools

See [SEARCHGUIDE.md](SEARCHGUIDE.md) for:

• search_nodes
• get_node with detail levels (minimal, standard, full)
• getnode modes (info, docs, searchproperties, versions)

Validation Tools

See [VALIDATIONGUIDE.md](VALIDATIONGUIDE.md) for:

• Validation profiles explained
• validate_node with modes (minimal, full)
• validate_workflow complete structure
• Auto-sanitization system
• Handling validation errors

Workflow Management

See [WORKFLOWGUIDE.md](WORKFLOWGUIDE.md) for:

• n8ncreateworkflow
• n8nupdatepartial_workflow (21 operation types including patchNodeField, setNodeGroups, and moveToFolder!)
• Smart parameters (branch, case)
• AI connection types (8 types)
• Workflow activation (activateWorkflow/deactivateWorkflow)
• n8ndeploytemplate
• n8nworkflowversions
• n8nmanagefolders (folder CRUD + workflow placement)
• n8nmanagecredentials (credential CRUD + schema discovery)
• n8nauditinstance (security auditing)

Templates, Data Tables & Self-Help

See [OPERATIONSGUIDE.md](OPERATIONSGUIDE.md) for:

• searchtemplates / gettemplate / n8ndeploytemplate examples
• n8nmanagedatatable (full actions, filter conditions, examples)
• toolsdocumentation, aiagentsguide, n8nhealth_check

Template Usage

The 2,700+ template library has three tools: searchtemplates (modes query/bynodes/bytask/bymetadata), gettemplate (modes structure/full), and n8ndeploy_template (deploys to your instance with autoFix/autoUpgradeVersions, returns workflow ID + required credentials + fixes applied).

See [OPERATIONSGUIDE.md](OPERATIONSGUIDE.md) for full search/get/deploy examples.

Running Workflows

n8ntestworkflow has one required parameter (workflowId) and a method that picks the path:

• The last three need N8NMCPACCESS_TOKEN (n8n 2.34+) and the workflow's "Available in MCP" setting.
• pinData is keyed by node name, and every value is an array of items wrapped as {"json": {...}} — {"Webhook": [{"json": {"id": "123"}}]}, never a flat object. It must be non-empty.
• triggerNodeName picks the trigger node to start from (defaults to the detected one; n8n requires it whenever inputs are given).
• Both run methods execute the workflow's nodes for real. direct runs every node; pinned pins only trigger nodes, nodes with credentials and HTTP Request nodes, so Code, Set, If and credential-free I/O (Execute Command, file read/write) still run. Confirm with the user before running a workflow that writes anywhere.
• executionMode applies to direct: manual (default) or production. It changes the execution context, not whether the run has side effects — a production run goes through the production execution path and is recorded as one. Only pass it when the user asked for one.
• timeoutMs is the client deadline for the official call (5000-600000; default 30000 for prepare, 300000 for pinned/direct).
• direct returns as soon as the run starts, so it reports success with an executionId regardless of how the run ends — poll n8nexecutions({action: "get", id: executionId}) for the outcome. A dispatch n8n refuses outright comes back as OFFICIALMCPERROR, not EXECUTIONFAILED.
• A workflow whose "Available in MCP" setting is off answers WORKFLOWNOTEXPOSED; exposeToMcp: true turns the setting on and retries once. That is a visible, persistent change — ask the user first, and note that enabling it is itself a workflow update, so it can overwrite a concurrent UI edit.

Successful and routed responses state method and backend (public-api or official-mcp); an envelope rejected on argument validation may carry neither.

See [WORKFLOWGUIDE.md](WORKFLOWGUIDE.md#n8ntestworkflow-running-workflows) for runnable examples of each method.

Version History

n8nworkflowversions reads two independent histories, selected with source:

• source: "local" (default) — the snapshots n8n-mcp takes before it changes a workflow. Any n8n version, no token, ids are numbers. Blind to edits made in the n8n UI. The only source that supports delete and prune.
• source: "native" — n8n's own workflow history, the same list the UI shows, including edits made by people. Needs N8NMCPACCESSTOKEN (n8n 2.34+; the native diff needs 2.36, where getworkflowversionsdiff shipped) and the workflow's "Available in MCP" setting; ids are opaque strings; list is capped at 50 with an offset; delete and prune are refused with MODENOTSUPPORTEDFORSOURCE (n8n owns that retention). Native rollback is not pre-validated — validateBefore is accepted and ignored.

mode: "diff" compares two versions (versionId + toVersionId, both from the same source and workflow). A local diff (data.format: "n8n-mcp") reports added/removed/modified nodes as node IDs; a native diff (data.format: "n8n") is n8n's own payload with field-level before/after values. Branch on data.format rather than assuming field names.

Native modes hit the same consent gate as the routed run methods: a workflow whose "Available in MCP" setting is off answers WORKFLOWNOTEXPOSED, and re-running with exposeToMcp: true turns that setting on and retries once (the response then carries exposedToMcp: true). It is a visible, persistent change to the workflow — ask the user before passing it. timeoutMs (5000-600000) is the client deadline for the native call.

See [WORKFLOWGUIDE.md](WORKFLOWGUIDE.md#n8nworkflowversions-version-control) for every mode with runnable examples of both sources.

Data Table Management

n8nmanagedatatable 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 → OPERATIONPATTERNS.md](../n8n-node-configuration/OPERATIONPATTERNS.md#data-table-nodes-basedatatable)). 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.

Column actions — addColumn, deleteColumn, renameColumn — change an existing table's columns, which the Public API cannot do; they run through n8n's MCP server and need N8NMCPACCESSTOKEN (n8n 2.34+). addColumn takes column: {name, type} (name starts with a letter, letters/digits/underscores only, at most 63 chars; type is string, number, boolean or date); deleteColumn/renameColumn take the columnId from getTable, and renameColumn puts the new column name in name. They address the table by project: projectId is resolved automatically when exactly one project is accessible, otherwise the call returns PROJECTREQUIRED and lists the candidates — pass projectId (from n8nlistcatalog({kind: "projects"})) to skip resolution. Renaming the table is not a column action: use updateTable on the Public API.

deleteColumn drops the column's values along with the column, and there is no undo. That bites hardest where you'd least expect it: a column's type cannot be changed after creation, so "make this column a number" really means drop-and-re-add, which throws away everything in it. Read the values out with getRows first if they matter, and confirm with the user before dropping a populated column.

See [OPERATIONSGUIDE.md](OPERATIONSGUIDE.md) for all actions, filter conditions, and examples.

Workflow Folders

n8nmanagefolders organizes workflows into folders (actions create/list/get/rename/move/delete; n8n 2.19+, registered free Community tier and up). projectId defaults to 'personal'. Placing workflows happens in the workflow tools: parentFolderId on n8ncreateworkflow, or the moveToFolder operation of n8nupdatepartial_workflow (both n8n 2.32+; null = project root). Two things to internalize: a workflow's folder is write-only in n8n's API (verify placement via a folder's get counts, never by reading the workflow), and delete without transferToFolderId archives the folder's workflows (transferToFolderId: "0" moves them to the project root instead, keeping them active).

See [WORKFLOWGUIDE.md](WORKFLOWGUIDE.md) for all actions, list filters/counts, and the delete semantics.

Credential Management

n8nmanagecredentials 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 [WORKFLOWGUIDE.md](WORKFLOWGUIDE.md) for all actions, the includeUsage shape, security notes, and the safe delete/rotate workflow.

Agents

The three tools in this section exist only for n8n's instance-level MCP server (a separate endpoint from the Public API). n8nmanageagents and n8nexplorenoderesources need N8NMCPACCESSTOKEN; n8nlistcatalog works without it and uses the token only for its team-project fallback. Other tools route individual operations through the same server — n8ntestworkflow prepare/pinned/direct, n8nworkflowversions source: "native", the n8nmanagedatatable column actions — as described in their own sections; see "Tool Availability" below.

• n8nmanageagents — create, configure, validate, run and publish persisted n8n Agents (a standalone assistant artifact: model, instructions, tools, skills, tasks, memory, channels — not the AI Agent workflow node). Actions: reference, search, get, create, mutate, validate, call, publish, unpublish, revert, versions, delete, discoverassets, verifymcpserver, updateintegration. Start with action: "reference", then discoverassets → create → mutate (one resource at a time, always the latest hash — n8n returns it as configHash and expects it back as args.baseConfigHash; a stale one comes back as STALECONFIG) → validate. publish only on explicit request; call runs the agent with real credentials and tools and may return approvals[] for the human to decide. timeoutMs is a top-level parameter (default 30000, 180000 for call), not part of args. Needs n8n 2.34+ with the agents module; on 2.36.x the agents runtime rejects azureOpenAiApi/aws credentials. Envelope error codes: NOTCONFIGURED, INVALIDARGS, STALECONFIG, AGENTNOTRUNNABLE, AGENTTOOLERROR (a custom tool that failed to compile, or an unknown agentId), plus the shared OFFICIALMCP* family (AUTHFAILED, NOTENABLED, RATELIMITED, TOOLUNAVAILABLE, URLREJECTED, TIMEOUT, TRANSPORT_ERROR, ERROR). See n8n-agents skill's "Persisted n8n Agents" section for the full workflow.
• n8nexplorenoderesources — resolve the real values behind a node's loadOptions dropdown or resource-locator listSearch (Slack channels, Google Sheets tabs, model lists) using a live credential, instead of guessing an ID. Use it when getnode (standard detail) shows dynamicOptions: {methodName, methodType, dependsOn} on a property. Six parameters are required and none of them are inferred: nodeType (LONG form), version (the node typeVersion the method belongs to), methodName and methodType copied verbatim from dynamicOptions, and credentialType plus a credentialId of that type from n8nmanagecredentials({action: "list"}). Whatever the method dependsOn goes in currentNodeParameters, resource-locator values keeping their {__rl: true, mode: "id", value: "…"} shape. Each result's value is what belongs in the workflow parameter; name is display text only.
• n8nlistcatalog — list instance-level projects (personal project marked, gives projectId for n8nmanageagents/n8nmanagedatatable) or tags. Works without the token via the Public API; with it configured, falls back to the official MCP server for team projects when the Public API's licence gate refuses (teamProjectsEnabled reports which).

Security & Audit

n8nauditinstance combines n8n's built-in audit (categories credentials/database/nodes/instance/filesystem) with a custom deep scan (hardcodedsecrets, unauthenticatedwebhooks, errorhandling, dataretention). 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 [WORKFLOWGUIDE.md](WORKFLOWGUIDE.md) for the two scanning approaches, examples, and remediation types in full.

Self-Help Tools

• toolsdocumentation() — overview of all tools; toolsdocumentation({topic, depth: "full"}) for a specific tool. Code node guides via topics javascriptcodenodeguide / pythoncodenodeguide.
• AI agent guide — toolsdocumentation({topic: "aiagents_guide", depth: "full"}) (no standalone tool); returns architecture, connections, tools, validation, best practices.
• n8nhealthcheck() — quick check; n8nhealthcheck({mode: "diagnostic"}) returns status, env vars, tool status, API connectivity. Both modes also return an officialMcp block — {configured, endpoint, reachable, toolCount, agentTools} — the preflight for everything gated on N8NMCPACCESSTOKEN: the agent tools, n8ntestworkflow's routed methods, native version history, the data-table column actions. Read it once before reaching for any of them, rather than discovering the gap through a NOTCONFIGURED envelope mid-task.

See [OPERATIONSGUIDE.md](OPERATIONSGUIDE.md) for examples.

Tool Availability

Always Available (no n8n API needed):

• searchnodes, getnode
• validatenode, validateworkflow
• searchtemplates, gettemplate
• toolsdocumentation (includes the aiagents_guide topic)

Requires n8n API (N8NAPIURL + N8NAPIKEY):

• n8ncreateworkflow
• n8nupdatepartialworkflow, n8nupdatefullworkflow
• n8nvalidateworkflow (by ID)
• n8nlistworkflows, n8ngetworkflow, n8ndeleteworkflow
• n8ntestworkflow
• n8n_executions
• n8n_evaluations (reads: n8n 2.30+ with an API key created on 2.30+; run/cancel: n8n 2.32+ with a key created on 2.32+ — older keys lack the testRun scopes)
• n8ndeploytemplate
• n8nworkflowversions
• n8nautofixworkflow
• n8nmanagedatatable
• n8nmanagefolders (folder CRUD: n8n 2.19+, registered Community tier and up; workflow placement via parentFolderId/moveToFolder: n8n 2.32+)
• n8nmanagecredentials
• n8nauditinstance
• n8nlistcatalog (works without the token; needs it only for the team-project fallback)

Requires N8NMCPACCESS_TOKEN (a separate token from n8n Settings → Instance-level MCP, in addition to the Public API credentials above):

• n8nmanageagents
• n8nexplorenode_resources
• n8ntestworkflow with method: "prepare"/"pinned"/"direct" (also needs the workflow's "Available in MCP" setting)
• n8nworkflowversions with source: "native" (also needs the workflow's "Available in MCP" setting)
• n8nmanagedatatable with addColumn/deleteColumn/renameColumn

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

Unified Tool Reference

• getnode — detail levels (minimal ~200 tok / standard ~1-2K, RECOMMENDED / full ~3-8K, sparingly) and modes (info default, docs, searchproperties + propertyQuery, versions, compare, breaking, migrations). Deep dive in [SEARCHGUIDE.md](SEARCHGUIDE.md).
• validatenode — modes full (default, errors/warnings/suggestions) and minimal (required-fields check); profiles minimal/runtime (default, recommended)/ai-friendly/strict. Deep dive in [VALIDATIONGUIDE.md](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 n8ndeploytemplate 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 n8nmanagedatatable (CRUD + filtering)
10. Folders managed with n8nmanagefolders; workflow placement is write-only (verify via folder counts, not the workflow)
11. Credentials managed with n8nmanagecredentials (CRUD + schema discovery)
12. Security audits via n8nauditinstance (built-in + custom deep scan)
13. AI agent guide available via toolsdocumentation({topic: "aiagents_guide", depth: "full"})

Common Workflow:

1. search_nodes → find node
2. get_node → understand config
3. validate_node → check config
4. n8ncreateworkflow → build
5. n8nvalidateworkflow → verify
6. n8nupdatepartial_workflow → iterate
7. activateWorkflow → go live!

For details, see:

• [SEARCHGUIDE.md](SEARCHGUIDE.md) - Node discovery
• [VALIDATIONGUIDE.md](VALIDATIONGUIDE.md) - Configuration validation + common mistakes
• [WORKFLOWGUIDE.md](WORKFLOWGUIDE.md) - Workflow management
• [OPERATIONSGUIDE.md](OPERATIONSGUIDE.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