Using N8n MCP Skills

n8n-mcp tools — working knowledge from turn one

Qualified names look like mcp__<server>__<tool> (<server> is usually n8n-mcp). This closes the gap where a tool's full description isn't loaded until first use.

Two tiers, and how to tell which one you have. The documentation and validation tools below work offline and are always present. The n8n_* management tools talk to a live n8n instance and appear only once one is connected. If they are absent, nothing is broken and there is nothing to retry — say so plainly and point the user at the right fix for their install:

• Hosted (https://api.n8n-mcp.com/mcp) — sign in through the OAuth prompt the client shows on first use, then connect the n8n instance in the dashboard. No environment variables, and no API key pasted into a config file.
• Self-hosted (npx n8n-mcp, Docker) — the server needs N8N_API_URL and N8N_API_KEY in its environment, exported before the client starts.

n8n_health_check confirms a working connection and returns the resolved instance.

Discovery & docs

• tools_documentation — meta-docs for every tool; {topic:"ai_agents_guide", depth:"full"} for the agent guide.
• search_nodes — find nodes by keyword.
• get_node — node info. Takes a single SHORT-form nodeType (nodes-base.httpRequest, nodes-langchain.agent), plus detail (minimal/standard/full) and mode (info/docs/search_properties/versions).
• validate_node — validate one node's config in isolation (profiles: minimal/runtime/ai-friendly/strict).
• search_templates / get_template — the template library (by keyword, nodes, task, metadata).

Build & edit

• n8n_create_workflow — create from full workflow JSON.
• n8n_update_partial_workflow — incremental diff ops ({id, operations:[…]}): addNode, updateNode, patchNodeField, addConnection, setNodeGroups, activateWorkflow, etc. Preferred for edits.
• Canvas groups (n8n 2.28+) survive your edits without being managed: a grouped node you remove is pruned from its group, and a group n8n can no longer accept is ungrouped so the edit still lands — nodes and connections untouched, every adjustment reported in details.warnings. To create or change groups, use the setNodeGroups op (full replacement; [] ungroups everything). See n8n-mcp-tools-expert.
• n8n_update_full_workflow — full replacement.
• n8n_autofix_workflow — auto-fix common issues.
• n8n_deploy_template — deploy a template to the instance.

Validate (necessary, not sufficient — always pair with the antipattern scan)

• validate_workflow — full JSON in, errors/warnings/fixes out. Node types here are LONG form (n8n-nodes-base.set).
• n8n_validate_workflow — validate a deployed workflow by {id} (no node JSON to inspect).

Inspect & lifecycle

• n8n_get_workflow — fetch a workflow (full / structure / active / filtered / minimal). Use it to verify connections after edits; mode="filtered" + nodeNames reads one heavy node (e.g. long Code source) without pulling the whole workflow, which can truncate client-side.
• n8n_list_workflows — list/filter (search before duplicating logic).
• n8n_delete_workflow, n8n_workflow_versions (history/rollback/diff; source: "local" = n8n-mcp's own snapshots, source: "native" = n8n's own history including edits people made in the UI — see n8n-mcp-tools-expert), n8n_instances (multi-instance accounts only: list/switch the target instance — see n8n-multi-instance), n8n_health_check (returns the resolved instanceName, plus an officialMcp block saying whether the instance-level MCP server below is configured and reachable).

Test & run

• n8n_test_workflow — runs real nodes (Code, HTTP, DB writes, sends all fire). Ask the user before running when side effects exist. method picks the path: auto (default) and trigger fire a webhook/form/chat trigger over HTTP on an active workflow; prepare/pinned/direct route through n8n's own MCP server and can run a workflow that has no HTTP trigger at all (Manual, Schedule, sub-workflow) — see n8n-mcp-tools-expert.
• n8n_executions — list/inspect executions. There is no execute_workflow tool.
• n8n_evaluations — evaluation test runs: list runs, aggregated metrics, per-case results (n8n ≥ 2.30), plus run/cancel to start or stop a run (n8n ≥ 2.32). run executes the workflow against its whole dataset — real nodes fire, so ask the user first. A 403 can mean the API key was created before the action's minimum version (re-create it for the testRun scopes), evaluations aren't licensed on the plan, or the key's owner lacks access to the workflow — for run/cancel, specifically the workflow:execute scope.

Data, folders, credentials, audit

• n8n_manage_datatable — Data Table CRUD, filtering, dry-run. addColumn/deleteColumn/renameColumn change an existing table's columns (the Public API cannot) through n8n's MCP server — deleteColumn drops the column's values along with it.
• n8n_manage_folders — workflow folder CRUD with contents counts (n8n ≥ 2.19, registered Community tier and up; projectId defaults to personal). Place workflows via parentFolderId on n8n_create_workflow or the moveToFolder op (n8n ≥ 2.32). Placement is write-only — verify via a folder's get counts, never by reading the workflow. delete without transferToFolderId moves the folder's workflows to the project root and ARCHIVES them — they still exist, but deactivated (transferToFolderId: "0" = transfer to project root without archiving).
• n8n_manage_credentials — credential CRUD + getSchema discovery.
• n8n_audit_instance — security audit (hardcoded secrets, unauthenticated webhooks, error-handling gaps).

Instance-level MCP server — a second endpoint alongside the Public API, gated on N8N_MCP_ACCESS_TOKEN (n8n 2.34+). n8n_health_check reports whether it is reachable; without it these calls answer NOT_CONFIGURED rather than failing obscurely.

• n8n_manage_agents — persisted n8n Agents: a standalone assistant artifact with its own lifecycle (model, instructions, skills, tasks, memory, channels), not the AI Agent workflow node. call runs it live with real credentials and may return approvals[]; publish only when the user asks. See n8n-agents.
• n8n_explore_node_resources — resolve a node's live dropdown / resource-locator values through a real credential instead of guessing an ID. See n8n-node-configuration.
• n8n_list_catalog — list projects (to get a projectId) or tags. The one tool here that also works without the token.
• The same server backs n8n_test_workflow prepare/pinned/direct, n8n_workflow_versions source: "native", and the n8n_manage_datatable column actions. Those are additionally gated per workflow on its "Available in MCP" setting; a refusal reads WORKFLOW_NOT_EXPOSED, and turning the setting on (exposeToMcp: true) is a visible, persistent change — ask the user first.

Node-type form trap: get_node / validate_node take SHORT form (nodes-base.set); workflow JSON inside validate_workflow / n8n_create_workflow uses LONG form (n8n-nodes-base.set). Mixing them is a common, silent mistake — see n8n-mcp-tools-expert.

The protocol, in order

1. Recognize the matching skill from the index and invoke it before the first MCP call.
2. Skim tools_documentation once per session to refresh the tool surface if you're unsure.
3. get_node before configuring any node — read the live schema, don't assume.
4. Build / edit, then validate_workflow before activating and n8n_get_workflow after to check connections.
5. Surface any drift you notice (missing tool, changed parameter, diverging behavior).

When in doubt

• Can't find a workflow the user built in the UI? The most common cause is per-workflow MCP access being off. Ask them to open it in n8n, go to Settings, and enable MCP access.
• User says it's broken? Believe them. Re-check parameters against get_node, trace data references, inspect the execution. See n8n-validation-expert.
• No skill fits and the task is non-trivial? Ask before guessing.

These are opinionated best practices, not laws. Disagree with a call? It's all markdown — edit the skill.