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:
- Node Discovery → SEARCH_GUIDE.md
- Configuration Validation → VALIDATION_GUIDE.md
- Workflow Management → WORKFLOW_GUIDE.md
- Template Library - Search and deploy 2,700+ real workflows
- Data Tables - Manage n8n data tables, rows and columns (
n8n_manage_datatable)
- Workflow Folders - Folder CRUD + workflow placement (
n8n_manage_folders)
- Credential Management - Full credential CRUD + schema discovery (
n8n_manage_credentials)
- Security & Audit - Instance security auditing with custom deep scan (
n8n_audit_instance)
- Documentation & Guides - Tool docs, AI agent guide, Code node guides
- Agents - Create, configure, validate, run and publish persisted n8n Agents (
n8n_manage_agents, requires N8N_MCP_ACCESS_TOKEN)
- Node Resource Resolution - Resolve live dropdown/resource-locator values with a real credential (
n8n_explore_node_resources, requires N8N_MCP_ACCESS_TOKEN)
- 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:
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:
- 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
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.
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"}}} // ✅
| # |
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.
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 (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 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.
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 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 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 WORKFLOW_NOT_EXPOSED, 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 WORKFLOW_GUIDE.md for every mode with runnable examples of both sources.
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.
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 N8N_MCP_ACCESS_TOKEN (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 PROJECT_REQUIRED and lists the candidates — pass projectId (from n8n_list_catalog({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 OPERATIONS_GUIDE.md for all actions, filter conditions, and examples.
Workflow Folders
n8n_manage_folders 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 n8n_create_workflow, or the moveToFolder operation of n8n_update_partial_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 WORKFLOW_GUIDE.md for all actions, list filters/counts, and the delete semantics.
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.
Agents
The three tools in this section exist only for n8n's instance-level MCP server (a separate endpoint from the Public API). n8n_manage_agents and n8n_explore_node_resources need N8N_MCP_ACCESS_TOKEN; n8n_list_catalog works without it and uses the token only for its team-project fallback. Other tools route individual operations through the same server — n8n_test_workflow prepare/pinned/direct, n8n_workflow_versions source: "native", the n8n_manage_datatable column actions — as described in their own sections; see "Tool Availability" below.
n8n_manage_agents — 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, discover_assets, verify_mcp_server, update_integration. Start with action: "reference", then discover_assets → 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 STALE_CONFIG) → 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: NOT_CONFIGURED, INVALID_ARGS, STALE_CONFIG, AGENT_NOT_RUNNABLE, AGENT_TOOL_ERROR (a custom tool that failed to compile, or an unknown agentId), plus the shared OFFICIAL_MCP_* family (AUTH_FAILED, NOT_ENABLED, RATE_LIMITED, TOOL_UNAVAILABLE, URL_REJECTED, TIMEOUT, TRANSPORT_ERROR, ERROR). See n8n-agents skill's "Persisted n8n Agents" section for the full workflow.
n8n_explore_node_resources — 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 get_node (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 n8n_manage_credentials({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.
n8n_list_catalog — list instance-level projects (personal project marked, gives projectId for n8n_manage_agents/n8n_manage_datatable) 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
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. Both modes also return an officialMcp block — {configured, endpoint, reachable, toolCount, agentTools} — the preflight for everything gated on N8N_MCP_ACCESS_TOKEN: the agent tools, n8n_test_workflow'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 NOT_CONFIGURED envelope mid-task.
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_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)
- n8n_deploy_template
- n8n_workflow_versions
- n8n_autofix_workflow
- n8n_manage_datatable
- n8n_manage_folders (folder CRUD: n8n 2.19+, registered Community tier and up; workflow placement via parentFolderId/moveToFolder: n8n 2.32+)
- n8n_manage_credentials
- n8n_audit_instance
- n8n_list_catalog (works without the token; needs it only for the team-project fallback)
Requires N8N_MCP_ACCESS_TOKEN (a separate token from n8n Settings → Instance-level MCP, in addition to the Public API credentials above):
- n8n_manage_agents
- n8n_explore_node_resources
- n8n_test_workflow with
method: "prepare"/"pinned"/"direct" (also needs the workflow's "Available in MCP" setting)
- n8n_workflow_versions with
source: "native" (also needs the workflow's "Available in MCP" setting)
- n8n_manage_datatable with
addColumn/deleteColumn/renameColumn
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
| Tool |
Response Time |
Payload Size |
| search_nodes |
<20ms |
Small |
| get_node (standard) |
<10ms |
~1-2KB |
| get_node (full) |
<100ms |
3-8KB |
| validate_node (minimal) |
<50ms |
Small |
| validate_node (full) |
<100ms |
Medium |
| validate_workflow |
100-500ms |
Medium |
| n8n_manage_folders |
100-500ms |
Small |
| n8n_manage_credentials |
50-500ms |
Small-Medium |
| n8n_audit_instance |
500-5000ms |
Large |
| n8n_create_workflow |
100-500ms |
Medium |
| n8n_update_partial_workflow |
50-200ms |
Small |
| n8n_deploy_template |
200-500ms |
Medium |
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:
- Use get_node with
detail: "standard" (default) - covers 95% of use cases
- nodeType formats differ:
nodes-base.* (search/validate) vs n8n-nodes-base.* (workflows)
- Specify validation profiles (
runtime recommended)
- Use smart parameters (
branch="true", case=0)
- Include intent parameter in workflow updates
- Auto-sanitization runs on ALL nodes during updates
- Workflows can be activated via API (
activateWorkflow operation)
- Workflows are built iteratively (56s avg between edits)
- Data tables managed with
n8n_manage_datatable (CRUD + filtering)
- Folders managed with
n8n_manage_folders; workflow placement is write-only (verify via folder counts, not the workflow)
- Credentials managed with
n8n_manage_credentials (CRUD + schema discovery)
- Security audits via
n8n_audit_instance (built-in + custom deep scan)
- AI agent guide available via
tools_documentation({topic: "ai_agents_guide", depth: "full"})
Common Workflow:
- search_nodes → find node
- get_node → understand config
- validate_node → check config
- n8n_create_workflow → build
- n8n_validate_workflow → verify
- n8n_update_partial_workflow → iterate
- 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
1---
2name: n8n-mcp-tools-expert
3description: 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, parameter formats, and common patterns. IMPORTANT — Always consult this skill before calling any n8n-mcp tool — it prevents common mistakes like wrong nodeType formats, incorrect parameter structures, and inefficient tool usage. If the user mentions n8n, workflows, nodes, or automation and you have n8n MCP tools available, use this skill first.
4metadata:
5 source: https://skillmd.com/skills/gabrielmoreira/n8n-mcp-tools-expert
6---
7
8# n8n MCP Tools Expert
9
10Master guide for using n8n-mcp MCP server tools to build workflows.
11
12---
13
14## Tool Categories
15
16n8n-mcp provides tools organized into categories:
17
181. **Node Discovery** → [SEARCH_GUIDE.md](SEARCH_GUIDE.md)
192. **Configuration Validation** → [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md)
203. **Workflow Management** → [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md)
214. **Template Library** - Search and deploy 2,700+ real workflows
225. **Data Tables** - Manage n8n data tables, rows and columns (`n8n_manage_datatable`)
236. **Workflow Folders** - Folder CRUD + workflow placement (`n8n_manage_folders`)
247. **Credential Management** - Full credential CRUD + schema discovery (`n8n_manage_credentials`)
258. **Security & Audit** - Instance security auditing with custom deep scan (`n8n_audit_instance`)
269. **Documentation & Guides** - Tool docs, AI agent guide, Code node guides
2710. **Agents** - Create, configure, validate, run and publish persisted n8n Agents (`n8n_manage_agents`, requires `N8N_MCP_ACCESS_TOKEN`)
2811. **Node Resource Resolution** - Resolve live dropdown/resource-locator values with a real credential (`n8n_explore_node_resources`, requires `N8N_MCP_ACCESS_TOKEN`)
2912. **Instance Catalog** - List projects and tags (`n8n_list_catalog`)
30
31---
32
33## Quick Reference
34
35### Most Used Tools (by success rate)
36
37| Tool | Use When | Speed |
38|------|----------|-------|
39| `search_nodes` | Finding nodes by keyword | <20ms |
40| `get_node` | Understanding node operations (detail="standard") | <10ms |
41| `validate_node` | Checking configurations (mode="full") | <100ms |
42| `n8n_create_workflow` | Creating workflows | 100-500ms |
43| `n8n_update_partial_workflow` | Editing workflows (MOST USED!) | 50-200ms |
44| `validate_workflow` | Checking complete workflow | 100-500ms |
45| `n8n_deploy_template` | Deploy template to n8n instance | 200-500ms |
46| `n8n_manage_datatable` | Managing data tables and rows | 50-500ms |
47| `n8n_manage_folders` | Folder CRUD + organizing workflows | 100-500ms |
48| `n8n_manage_credentials` | Credential CRUD + schema discovery | 50-500ms |
49| `n8n_audit_instance` | Security audit (built-in + custom scan) | 500-5000ms |
50| `n8n_autofix_workflow` | Auto-fix validation errors | 200-1500ms |
51| `n8n_manage_agents` | Persisted n8n Agent CRUD/validate/publish | 150-400ms; `call` action: 5-60s |
52| `n8n_explore_node_resources` | Resolve live loadOptions/listSearch values | 200 ms - 5 s |
53| `n8n_list_catalog` | List projects or tags | 50-300ms |
54
55---
56
57## Tool Selection Guide
58
59### Finding the Right Node
60
61**Workflow**:
62```
631. search_nodes({query: "keyword"})
642. get_node({nodeType: "nodes-base.name"})
653. [Optional] get_node({nodeType: "nodes-base.name", mode: "docs"})
66```
67
68**Example**:
69```javascript
70// Step 1: Search
71search_nodes({query: "slack"})
72// Returns: nodes-base.slack
73
74// Step 2: Get details
75get_node({nodeType: "nodes-base.slack"})
76// Returns: operations, properties, examples (standard detail)
77
78// Step 3: Get readable documentation
79get_node({nodeType: "nodes-base.slack", mode: "docs"})
80// Returns: markdown documentation
81```
82
83**Common pattern**: search → get_node (18s average)
84
85### Validating Configuration
86
87**Workflow**:
88```
891. validate_node({nodeType, config: {}, mode: "minimal"}) - Check required fields
902. validate_node({nodeType, config, profile: "runtime"}) - Full validation
913. [Repeat] Fix errors, validate again
92```
93
94**Common pattern**: validate → fix → validate (23s thinking, 58s fixing per cycle)
95
96### Managing Workflows
97
98**Workflow**:
99```
1001. n8n_create_workflow({name, nodes, connections})
1012. n8n_validate_workflow({id})
1023. n8n_update_partial_workflow({id, operations: [...]})
1034. n8n_validate_workflow({id}) again
1045. n8n_update_partial_workflow({id, operations: [{type: "activateWorkflow"}]})
105```
106
107**Common pattern**: iterative updates (56s average between edits)
108
109### Critical: Node JSON Hygiene When Creating Workflows
110
111Three structural mistakes in generated node JSON break the n8n UI even when the workflow validates:
112
1131. **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.
114
115```javascript
116// ❌ Breaks the credential selector
117"credentials": {"httpHeaderAuth": {"id": "REPLACE_ME", "name": "My API Key"}}
118
119// ✅ Unknown ID → omit credentials block; user picks in UI
120// ✅ Known ID (from n8n_manage_credentials list) → use the real ID
121```
122
1232. **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.
124
1253. **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).
126
127---
128
129## Critical: nodeType Formats
130
131**Two different formats** for different tools!
132
133### Format 1: Search/Validate Tools
134```javascript
135// Use SHORT prefix
136"nodes-base.slack"
137"nodes-base.httpRequest"
138"nodes-base.webhook"
139"nodes-langchain.agent"
140```
141
142**Tools that use this**:
143- search_nodes (returns this format)
144- get_node
145- validate_node
146- validate_workflow
147
148### Format 2: Workflow Tools
149```javascript
150// Use FULL prefix
151"n8n-nodes-base.slack"
152"n8n-nodes-base.httpRequest"
153"n8n-nodes-base.webhook"
154"@n8n/n8n-nodes-langchain.agent"
155```
156
157**Tools that use this**:
158- n8n_create_workflow
159- n8n_update_partial_workflow
160
161### Conversion
162
163```javascript
164// search_nodes returns BOTH formats
165{
166 "nodeType": "nodes-base.slack", // For search/validate tools
167 "workflowNodeType": "n8n-nodes-base.slack" // For workflow tools
168}
169```
170
171---
172
173## Common Mistakes
174
175Eight recurring mistakes. Two are worth showing in full because they silently corrupt structure:
176
177```javascript
178// nodeType prefix (search/validate tools want the SHORT form)
179get_node({nodeType: "slack"}) // ❌ missing prefix → "Node not found"
180get_node({nodeType: "n8n-nodes-base.slack"}) // ❌ FULL prefix is for workflow tools
181get_node({nodeType: "nodes-base.slack"}) // ✅
182
183// credentials must be nested by type with {id, name} — not a flat string
184updates: {credentials: "myApiKey"} // ❌
185updates: {credentials: {httpHeaderAuth: {id: "abc123", name: "My API Key"}}} // ✅
186```
187
188| # | Mistake | Fix |
189|---|---------|-----|
190| 1 | Wrong nodeType format | SHORT `nodes-base.*` for search/validate; FULL `n8n-nodes-base.*` for workflow tools (see above) |
191| 2 | `detail: "full"` by default | Default `standard` covers 95%; reach for `docs`/`search_properties` instead of `full` |
192| 3 | No validation profile | Pass `profile: "runtime"` explicitly (`minimal`/`ai-friendly`/`strict` for other stages) |
193| 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 |
194| 5 | Not using smart parameters | Use `branch: "true"` / `case: 0` instead of fragile `sourceIndex` math |
195| 6 | Omitting `intent` | Always include `intent` on `n8n_update_partial_workflow` for better responses |
196| 7 | `parameters` instead of `updates` | `updateNode` takes `updates: {...}`, not `parameters: {...}` |
197| 8 | Wrong credential format | Nest by type with `{id, name}` (see above) |
198
199Full WRONG/CORRECT examples for each: see [VALIDATION_GUIDE.md → Common Mistakes](VALIDATION_GUIDE.md).
200
201---
202
203## Tool Usage Patterns
204
205Three patterns dominate real usage. Worked, step-by-step examples for each live in the reference guides.
206
207- **Pattern 1 — Node Discovery** (18s avg between steps): `search_nodes({query})` → `get_node({nodeType, includeExamples: true})`. See [SEARCH_GUIDE.md](SEARCH_GUIDE.md).
208- **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).
209- **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).
210
211---
212
213## Detailed Guides
214
215### Node Discovery Tools
216See [SEARCH_GUIDE.md](SEARCH_GUIDE.md) for:
217- search_nodes
218- get_node with detail levels (minimal, standard, full)
219- get_node modes (info, docs, search_properties, versions)
220
221### Validation Tools
222See [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) for:
223- Validation profiles explained
224- validate_node with modes (minimal, full)
225- validate_workflow complete structure
226- Auto-sanitization system
227- Handling validation errors
228
229### Workflow Management
230See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for:
231- n8n_create_workflow
232- n8n_update_partial_workflow (21 operation types including patchNodeField, setNodeGroups, and moveToFolder!)
233- Smart parameters (branch, case)
234- AI connection types (8 types)
235- Workflow activation (activateWorkflow/deactivateWorkflow)
236- n8n_deploy_template
237- n8n_workflow_versions
238- n8n_manage_folders (folder CRUD + workflow placement)
239- n8n_manage_credentials (credential CRUD + schema discovery)
240- n8n_audit_instance (security auditing)
241
242### Templates, Data Tables & Self-Help
243See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for:
244- search_templates / get_template / n8n_deploy_template examples
245- n8n_manage_datatable (full actions, filter conditions, examples)
246- tools_documentation, ai_agents_guide, n8n_health_check
247
248---
249
250## Template Usage
251
252The 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).
253
254See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for full search/get/deploy examples.
255
256---
257
258## Running Workflows
259
260`n8n_test_workflow` has one required parameter (`workflowId`) and a `method` that picks the path:
261
262| `method` | Backend | What it does |
263|---|---|---|
264| `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.** |
265| `trigger` | Public API | Same HTTP path, requested explicitly. |
266| `prepare` | n8n's MCP server | Read-only: lists the nodes that need pinned data. |
267| `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`. |
268| `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. |
269
270- The last three need `N8N_MCP_ACCESS_TOKEN` (n8n 2.34+) and the workflow's "Available in MCP" setting.
271- `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.
272- `triggerNodeName` picks the trigger node to start from (defaults to the detected one; n8n requires it whenever inputs are given).
273- **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.
274- `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.
275- `timeoutMs` is the client deadline for the official call (5000-600000; default 30000 for `prepare`, 300000 for `pinned`/`direct`).
276- `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`.
277- 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.
278
279Successful and routed responses state `method` and `backend` (`public-api` or `official-mcp`); an envelope rejected on argument validation may carry neither.
280
281See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md#n8n_test_workflow-running-workflows) for runnable examples of each method.
282
283---
284
285## Version History
286
287`n8n_workflow_versions` reads two independent histories, selected with `source`:
288
289- `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`.
290- `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.
291
292`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.
293
294Native modes hit the same consent gate as the routed run methods: a workflow whose "Available in MCP" setting is off answers `WORKFLOW_NOT_EXPOSED`, 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.
295
296See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md#n8n_workflow_versions-version-control) for every mode with runnable examples of both sources.
297
298---
299
300## Data Table Management
301
302`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](../n8n-node-configuration/OPERATION_PATTERNS.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.
303
304**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 `N8N_MCP_ACCESS_TOKEN` (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 `PROJECT_REQUIRED` and lists the candidates — pass `projectId` (from `n8n_list_catalog({kind: "projects"})`) to skip resolution. Renaming the *table* is not a column action: use `updateTable` on the Public API.
305
306**`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.
307
308See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for all actions, filter conditions, and examples.
309
310---
311
312## Workflow Folders
313
314`n8n_manage_folders` 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 `n8n_create_workflow`, or the `moveToFolder` operation of `n8n_update_partial_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).
315
316See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for all actions, list filters/counts, and the delete semantics.
317
318---
319
320## Credential Management
321
322`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).
323
324See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for all actions, the includeUsage shape, security notes, and the safe delete/rotate workflow.
325
326---
327
328## Agents
329
330The three tools in this section exist only for n8n's instance-level MCP server (a separate endpoint from the Public API). `n8n_manage_agents` and `n8n_explore_node_resources` need `N8N_MCP_ACCESS_TOKEN`; `n8n_list_catalog` works without it and uses the token only for its team-project fallback. Other tools route individual operations through the same server — `n8n_test_workflow` `prepare`/`pinned`/`direct`, `n8n_workflow_versions` `source: "native"`, the `n8n_manage_datatable` column actions — as described in their own sections; see "Tool Availability" below.
331
332- `n8n_manage_agents` — 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`, `discover_assets`, `verify_mcp_server`, `update_integration`. Start with `action: "reference"`, then `discover_assets` → `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 `STALE_CONFIG`) → `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: `NOT_CONFIGURED`, `INVALID_ARGS`, `STALE_CONFIG`, `AGENT_NOT_RUNNABLE`, `AGENT_TOOL_ERROR` (a custom tool that failed to compile, or an unknown `agentId`), plus the shared `OFFICIAL_MCP_*` family (`AUTH_FAILED`, `NOT_ENABLED`, `RATE_LIMITED`, `TOOL_UNAVAILABLE`, `URL_REJECTED`, `TIMEOUT`, `TRANSPORT_ERROR`, `ERROR`). See **n8n-agents** skill's "Persisted n8n Agents" section for the full workflow.
333- `n8n_explore_node_resources` — 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 `get_node` (`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 `n8n_manage_credentials({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.
334- `n8n_list_catalog` — list instance-level `projects` (personal project marked, gives `projectId` for `n8n_manage_agents`/`n8n_manage_datatable`) 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).
335
336---
337
338## Security & Audit
339
340`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.
341
342See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) for the two scanning approaches, examples, and remediation types in full.
343
344---
345
346## Self-Help Tools
347
348- `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`.
349- **AI agent guide** — `tools_documentation({topic: "ai_agents_guide", depth: "full"})` (no standalone tool); returns architecture, connections, tools, validation, best practices.
350- `n8n_health_check()` — quick check; `n8n_health_check({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 `N8N_MCP_ACCESS_TOKEN`: the agent tools, `n8n_test_workflow`'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 `NOT_CONFIGURED` envelope mid-task.
351
352See [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) for examples.
353
354---
355
356## Tool Availability
357
358**Always Available** (no n8n API needed):
359- search_nodes, get_node
360- validate_node, validate_workflow
361- search_templates, get_template
362- tools_documentation (includes the ai_agents_guide topic)
363
364**Requires n8n API** (N8N_API_URL + N8N_API_KEY):
365- n8n_create_workflow
366- n8n_update_partial_workflow, n8n_update_full_workflow
367- n8n_validate_workflow (by ID)
368- n8n_list_workflows, n8n_get_workflow, n8n_delete_workflow
369- n8n_test_workflow
370- n8n_executions
371- 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)
372- n8n_deploy_template
373- n8n_workflow_versions
374- n8n_autofix_workflow
375- n8n_manage_datatable
376- n8n_manage_folders (folder CRUD: n8n 2.19+, registered Community tier and up; workflow placement via parentFolderId/moveToFolder: n8n 2.32+)
377- n8n_manage_credentials
378- n8n_audit_instance
379- n8n_list_catalog (works without the token; needs it only for the team-project fallback)
380
381**Requires `N8N_MCP_ACCESS_TOKEN`** (a separate token from n8n Settings → Instance-level MCP, in addition to the Public API credentials above):
382- n8n_manage_agents
383- n8n_explore_node_resources
384- n8n_test_workflow with `method: "prepare"`/`"pinned"`/`"direct"` (also needs the workflow's "Available in MCP" setting)
385- n8n_workflow_versions with `source: "native"` (also needs the workflow's "Available in MCP" setting)
386- n8n_manage_datatable with `addColumn`/`deleteColumn`/`renameColumn`
387
388If API tools unavailable, use templates and validation-only workflows.
389
390---
391
392## Unified Tool Reference
393
394- **`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](SEARCH_GUIDE.md).
395- **`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](VALIDATION_GUIDE.md).
396
397---
398
399## Performance Characteristics
400
401| Tool | Response Time | Payload Size |
402|------|---------------|--------------|
403| search_nodes | <20ms | Small |
404| get_node (standard) | <10ms | ~1-2KB |
405| get_node (full) | <100ms | 3-8KB |
406| validate_node (minimal) | <50ms | Small |
407| validate_node (full) | <100ms | Medium |
408| validate_workflow | 100-500ms | Medium |
409| n8n_manage_folders | 100-500ms | Small |
410| n8n_manage_credentials | 50-500ms | Small-Medium |
411| n8n_audit_instance | 500-5000ms | Large |
412| n8n_create_workflow | 100-500ms | Medium |
413| n8n_update_partial_workflow | 50-200ms | Small |
414| n8n_deploy_template | 200-500ms | Medium |
415
416---
417
418## Best Practices
419
420### Do
421- For simple workflows (<=5 nodes), use MCP tools directly — don't over-engineer the investigation
422- Use `patchNodeField` for surgical edits to Code node content instead of replacing the entire node
423- Use `get_node({detail: "standard"})` for most use cases
424- Specify validation profile explicitly (`profile: "runtime"`)
425- Use smart parameters (`branch`, `case`) for clarity
426- Include `intent` parameter in workflow updates
427- Follow search → get_node → validate workflow
428- Iterate workflows (avg 56s between edits)
429- Validate after every significant change
430- Use `includeExamples: true` for real configs
431- Use `n8n_deploy_template` for quick starts
432
433### Don't
434- Use `detail: "full"` unless necessary (wastes tokens)
435- Forget nodeType prefix (`nodes-base.*`)
436- Skip validation profiles
437- Try to build workflows in one shot (iterate!)
438- Ignore auto-sanitization behavior
439- Use full prefix (`n8n-nodes-base.*`) with search/validate tools
440- Forget to activate workflows after building
441
442---
443
444## Summary
445
446**Most Important**:
4471. Use **get_node** with `detail: "standard"` (default) - covers 95% of use cases
4482. nodeType formats differ: `nodes-base.*` (search/validate) vs `n8n-nodes-base.*` (workflows)
4493. Specify **validation profiles** (`runtime` recommended)
4504. Use **smart parameters** (`branch="true"`, `case=0`)
4515. Include **intent parameter** in workflow updates
4526. **Auto-sanitization** runs on ALL nodes during updates
4537. Workflows can be **activated via API** (`activateWorkflow` operation)
4548. Workflows are built **iteratively** (56s avg between edits)
4559. **Data tables** managed with `n8n_manage_datatable` (CRUD + filtering)
45610. **Folders** managed with `n8n_manage_folders`; workflow placement is write-only (verify via folder counts, not the workflow)
45711. **Credentials** managed with `n8n_manage_credentials` (CRUD + schema discovery)
45812. **Security audits** via `n8n_audit_instance` (built-in + custom deep scan)
45913. **AI agent guide** available via `tools_documentation({topic: "ai_agents_guide", depth: "full"})`
460
461**Common Workflow**:
4621. search_nodes → find node
4632. get_node → understand config
4643. validate_node → check config
4654. n8n_create_workflow → build
4665. n8n_validate_workflow → verify
4676. n8n_update_partial_workflow → iterate
4687. activateWorkflow → go live!
469
470For details, see:
471- [SEARCH_GUIDE.md](SEARCH_GUIDE.md) - Node discovery
472- [VALIDATION_GUIDE.md](VALIDATION_GUIDE.md) - Configuration validation + common mistakes
473- [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md) - Workflow management
474- [OPERATIONS_GUIDE.md](OPERATIONS_GUIDE.md) - Templates, data tables, self-help tools
475
476---
477
478**Related Skills**:
479- n8n Expression Syntax - Write expressions in workflow fields
480- n8n Workflow Patterns - Architectural patterns from templates
481- n8n Validation Expert - Interpret validation errors
482- n8n Node Configuration - Operation-specific requirements
483- n8n Code JavaScript - Write JavaScript in Code nodes
484- n8n Code Python - Write Python in Code nodes