Expert guide for using n8n-mcp MCP tools effectively. Use when searching for nodes, validating configurations, accessing templates, managing workflows, organizing workflows into folders, managing credentials, auditing instance security, or using any n8n-mcp tool. Provides tool selection guidance, pa

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](SEARCH GUIDE.md) 2. Configuration Validation → [VALIDATION GUIDE.md](VALIDATION GUIDE.md) 3. Workflow Management → [WORKFLOW GUIDE.md](WORKFLOW GUIDE.md) 4. Template Library Search and deploy 2,700+ real workflows 5. Data Tables Manage n8n data tables, rows and columns ( n8n manage datatable ) 6. Workflow Folders Folder CRUD + workflow placement ( n8n manage folders ) 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 10. Agents Create, configure, validate, run and publish persisted n8n Agents ( n8n manage agents , requires N8N MCP ACCESS TOKEN ) 11. Node Resource Resolution Resolve live dropdown/resource locator values with a real credential ( n8n explore node resources , requires N8N MCP ACCESS TOKEN ) 12. Instance Catalog List projects and tags ( n8n list catalog ) Quick Reference Most Used Tools (by success rate) Tool Use When Speed search nodes Finding nodes by keyword <20ms get node Understanding node operations (detail="standard") <10ms validate node Checking configurations (mode="full") <100ms n8n create workflow Creating workflows 100 500ms n8n update partial workflow Editing workflows (MOST USED!) 50 200ms validate workflow Checking complete workflow 100 500ms n8n deploy template Deploy template to n8n instance 200 500ms n8n manage datatable Managing data tables and rows 50 500ms n8n manage folders Folder CRUD + organizing workflows 100 500ms n8n manage credentials Credential CRUD + schema discovery 50 500ms n8n audit instance Security audit (built in + custom scan) 500 5000ms n8n autofix workflow Auto fix validation errors 200 1500ms n8n manage agents Persisted n8n Agent CRUD/validate/publish 150 400ms; call action: 5 60s n8n explore node resources Resolve live loadOptions/listSearch values 200 ms 5 s n8n list catalog List projects or tags 50 300ms Tool Selection Guide Finding the Right Node Workflow : Example : Common pattern : search → get node (18s average) Validating Configuration Workflow : Common pattern : validate → fix → validate (23s thinking, 58s fixing per cycle) Managing Workflows Workflow : 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. 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 Tools that use this : search nodes (returns this format) get node validate node validate workflow Format 2: Workflow Tools Tools that use this : n8n create workflow n8n update partial workflow Conversion Common Mistakes Eight recurring mistakes. Two are worth showing in full because they silently corrupt structure: Mistake Fix 1 Wrong nodeType format SHORT nodes base. for search/validate; FULL n8n nodes base. for workflow tools (see above) 2 detail: "full" by default Default standard covers 95%; reach for docs / search properties instead of full 3 No validation profile Pass profile: "runtime" explicitly ( minimal / ai friendly / strict for other stages) 4 Ignoring auto sanitization ALL nodes sanitized on ANY update (operator structures, IF/Switch metadata); it can't fix broken connections or branch count mismatches 5 Not using smart parameters Use branch: "true" / case: 0 instead of fragile sourceIndex math 6 Omitting intent Always include intent on n8n update partial workflow for better responses 7 parameters instead of updates updateNode takes updates: {...} , not parameters: {...} 8 Wrong credential format Nest by type with {id, name} (see above) Full WRONG/CORRECT examples for each: see [VALIDATION GUIDE.md → Common Mistakes](VALIDATION GUIDE.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): search nodes({query}) → get node({nodeType, includeExamples: true}) . See [SEARCH GUIDE.md](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](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](WORKFLOW GUIDE.md). Detailed Guides Node Discovery Tools See [SEARCH GUIDE.md](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](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](WORKFLOW GUIDE.md) for: n8n create workflow n8n update partial workflow (21 operation types including patchNodeField, setNodeGroups, and moveToFolder!) Smart parameters (branch, case) AI connection types (8 types) Workflow activation (activateWorkflow/deactivateWorkflow) n8n deploy template n8n workflow versions n8n manage folders (folder CRUD + workflow placement) n8n manage credentials (credential CRUD + schema discovery) n8n audit instance (security auditing) Templates, Data Tables & Self Help See [OPERATIONS GUIDE.md](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](OPERATIONS GUIDE.md) for full search/get/deploy examples. Running Workflows n8n test workflow has one required parameter ( workflowId ) and a method that picks the path: method Backend What it does auto (default) Public API Detects a webhook/form/chat trigger and fires it over HTTP — the workflow must be active . No such trigger → it reports that the workflow cannot be triggered and names the methods below. auto never runs anything through n8n's MCP server. trigger Public API Same HTTP path, requested explicitly. prepare n8n's MCP server Read only: lists the nodes that need pinned data. pinned n8n's MCP server Runs the workflow with pinData standing in for trigger, credentialed and HTTP Request nodes, and waits. Every other node still runs. A run that finishes in error / crashed / canceled comes back as EXECUTION FAILED with the executionId . direct n8n's MCP server Starts a run and returns once it has started; nothing is pinned, so every node runs. message or data / headers are forwarded to the trigger as input. The last three need N8N MCP ACCESS 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 n8n executions({action: "get", id: executionId}) for the outcome. A dispatch n8n refuses outright comes back as OFFICIAL MCP ERROR , not EXECUTION FAILED . A workflow whose "Available in MCP" setting is off answers WORKFLOW NOT EXPOSED ; 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 [WORKFLOW GUIDE.md](WORKFLOW GUIDE.md n8n test workflow running workflows) for runnable examples of each method. Version History n8n workflow versions 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 N8N MCP ACCESS TOKEN (n8n 2.34+; the native diff needs 2.36, where get workflow versions diff 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 MODE NOT SUPPORTED FOR SOURCE (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

n8n-mcp-tools-expert