From 00cf56883881f6c320f2e96fc6917ed1be4997b4 Mon Sep 17 00:00:00 2001 From: czlonkowski Date: Thu, 16 Jul 2026 13:28:19 +0200 Subject: [PATCH] docs: stop tracking the competitive analysis in the repo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The document moves to docs/local/ (gitignored) and will be maintained internally going forward. Conceived by Romuald Członkowski - www.aiadvisors.pl/en Co-Authored-By: Claude Fable 5 --- docs/competitive-analysis-july-2026.md | 297 ------------------------- 1 file changed, 297 deletions(-) delete mode 100644 docs/competitive-analysis-july-2026.md diff --git a/docs/competitive-analysis-july-2026.md b/docs/competitive-analysis-july-2026.md deleted file mode 100644 index dab14ac97..000000000 --- a/docs/competitive-analysis-july-2026.md +++ /dev/null @@ -1,297 +0,0 @@ -# n8n Official MCP vs n8n-mcp — Head-to-Head Competitive Analysis - -**Date:** 2026-07-02 (supersedes the 2026-06-19 edition) -**Official server tested:** live n8n MCP server on a **production instance running the current stable release** (July re-test; npm `latest` is n8n 2.28.4, `@n8n/workflow-sdk` 0.21.2), on top of the June edition's evidence: a then-stable live server (full-rewrite path) and the **n8n 2.27.0 source tree**. -**n8n-mcp version tested:** measurements carried from 2.59.0 (bundles n8n 2.26.2, live staging, 2026-06-19); current release at this edition is 2.61.0 (bundles n8n 2.27.4). - ---- - -## 0. What changed since the June 2026 edition - -The June edition's headline was that the official diff-based `update_workflow` existed only in pre-release source, so the April "n8n-mcp wins iterative editing by 6.5×–22×" finding still held on the stable channel — with a near-term expiry. **That expiry has arrived.** This refresh re-ran the June probes on 2026-07-02 against a production n8n instance running the current stable release: - -- **The official diff-based `update_workflow` is shipped and live.** The tool now accepts only `{ workflowId, operations[] }` (12 op types observed; atomic; max 100/call) — the full-SDK-code update path is gone from the schema. A real 4-op "insert one node mid-flow" edit applied cleanly. Note: n8n's docs date partial-update support to v2.20.0, which conflicts with the June live observation of a full-code-only tool on the then-stable channel — most plausibly progressive rollout or flag gating. Either way, current instances have it. -- **Raw per-edit parity for whole-value edits, measured:** the same insert-one-node edit costs **509 chars** on the official server vs **~492 chars** via `n8n_update_partial_workflow` — a tie. The April/June token-multiple claim is **retired for current n8n versions** (it still applies to instances that haven't rolled forward). -- **The surgical-edit advantage survives parity and is now quantified against the shipped diff tool:** a one-line change inside a ~1 KB Code node costs **1,174 chars** officially (`setNodeParameter` resends the whole field; no find/replace, no array indices) vs **220 chars** via `patchNodeField` — **5.3×, scaling linearly with field size**. -- **`validate_node_config` is shipped**, not just in source. It returns precise per-field errors for missing required fields and missing agent subnodes — but silently passes unknown node types, non-existent typeVersions, and **all community nodes** as `valid:true`. -- **The validator-honesty gap persists in full on the current release:** all five June probe workflows still return `valid:true` (three silently, two with non-blocking warnings). An agent loop using `valid:true` as its stop signal still accepts all five broken workflows. n8n-mcp errors on all five. -- **The durable differentiators are unchanged**: templates, community/custom-node coverage, credentials CRUD, instance audit, version history, multi-instance/SaaS, autofix, and surgical in-field edits (`patchNodeField`). - -The June strategic correction now stands without an expiry date: **a raw per-edit token multiple is not the moat.** The moat is validation an agent can trust as a stop signal, surgical large-field edits, and ecosystem breadth (templates, community nodes, credentials, audit, versions, multi-instance). - ---- - -## 1. Executive summary - -n8n ships a first-party MCP server inside the product (`packages/cli/src/modules/mcp/`), with workflow authoring split into `@n8n/workflow-sdk` and `@n8n/ai-workflow-builder.ee`. The architectural divergence has narrowed: the official server makes the LLM **author** workflows as TypeScript code against a fluent SDK, while its **update** path now uses the same JSON-diff model n8n-mcp pioneered (create remains SDK-code-only). - -| Concern | Winner | Margin / Notes | -|---|---|---| -| Greenfield authoring (built-in nodes) | ≈ Tie (different model) | Official: SDK TypeScript → `create_workflow_from_code`. n8n-mcp: direct JSON + 2,700+ templates + NL-to-workflow (hosted). n8n-mcp wins on template-accelerated starts. | -| Iterative editing, raw token cost | ≈ Tie (current versions) | Official diff update shipped and live-verified 2026-07-02: **509 vs ~492 chars** for the same insert-one-node edit. Instances on older versions still see the full-rewrite path and the old 3.5×–20× gap. | -| Surgical large-field / Code-node edits | **n8n-mcp** | `patchNodeField` does find/replace inside a field; the official `setNodeParameter` (RFC 6901 pointer) has no find/replace and no array indices, so it re-sends the whole field value. Measured vs the shipped diff tool: **1,174 vs 220 chars (5.3×)** for a one-line edit in a ~1 KB Code node; ratio scales with field size. | -| Validation depth & actionability | **n8n-mcp** | 4 named profiles + by-ID validation + 13-fix-type autofix. Official: reports-only; **all five broken-config probes still `valid:true`** on the current release (live-verified 2026-07-02). | -| Single-node validation | ≈ Tie (official caught up) | Official `validate_node_config` is shipped with precise per-field errors — but silently passes unknown node types, invalid typeVersions, and all community nodes. | -| Templates / patterns library | **n8n-mcp** | 2,700+ templates; official has zero template tools. | -| Credentials management | **n8n-mcp** | n8n-mcp has CRUD + getSchema; official has read-only `list_credentials` + auto-assign only (HTTP nodes excluded). | -| Instance audit / security scan | **n8n-mcp** | n8n-mcp ships it; official has none. | -| Workflow version history & rollback | **n8n-mcp** | n8n-mcp has it; official has only soft-delete `archive_workflow`. | -| Community-node coverage | **n8n-mcp** | n8n-mcp covers ~1,845 nodes (816 core + 1,029 community). Official can *search* installed community nodes but cannot *type/validate* them (schemas baked to the two built-in packages). | -| Multi-instance / fleet / SaaS | **n8n-mcp** | n8n-mcp ships a multi-tenant SaaS; official is 1:1 to one n8n. | -| Drafts / publish lifecycle | **Official** | `publish_workflow` / `unpublish_workflow`; n8n-mcp uses the activate flag. | -| Project / folder placement on create | **Official** | `create_workflow_from_code` takes `projectId` + `folderId`; n8n-mcp has no folder placement. | -| Pin-data testing | **Official** | `prepare_test_pin_data` + `test_workflow`; n8n-mcp has no pin-data prep surface. | -| Data tables CRUD | ≈ Tie | Official has a 7-tool suite; n8n-mcp has `n8n_manage_datatable` (CRUD + filter + dryRun). | -| Native in-instance integration / no API token (self-host) | **Official** | Runs inside n8n; instance-scoped auth, optional preview UI. n8n-mcp self-host passes an API key (SaaS users do not). | - -**Strategic read:** the official MCP is strongest for authoring and iterating on **built-in-node** workflows inside one n8n account, and the iteration-cost gap is now closed on current versions. n8n-mcp is strongest where the work touches the **ecosystem** — templates, community/custom nodes, credentials, audit, version history, fleets — for **surgical edits to large fields**, and wherever an agent needs **validation it can trust as a stop signal**. - ---- - -## 2. Methodology and reproducibility - -This edition rests on four evidence streams — three from the June edition (dated 2026-06-18/19) plus a July re-test: - -1. **Live head-to-head.** The official server was exercised directly via its connected MCP tools (`search_nodes`, `get_node_types`, `validate_workflow`, `get_sdk_reference`, `update_workflow` schema, `search_workflows`) against its live n8n instance. n8n-mcp was exercised against its live staging instance (`n8n-test.n8n-mcp.com`). Validator probes and a token-cost build were run on both. -2. **Source analysis.** The n8n monorepo was cloned (sparse: `packages/cli/src/modules/mcp`, `packages/@n8n/workflow-sdk`, `packages/@n8n/ai-workflow-builder.ee`, `packages/@n8n/db`, `packages/@n8n/config`) at master HEAD (`package.json` version **2.27.0**, 2026-06-18). All official-side claims about op types, validation internals, tool registration, and gating are cited to specific files/lines in that tree. -3. **Telemetry context.** The usage-pattern figures in §3.4 are carried forward from the 2026-04-30 telemetry pull and are explicitly dated; they were **not** re-queried for this edition. They are used only to establish that iteration dominates usage — not to project a counterfactual dollar figure against the official server (see §3.4 for why that projection was retired). -4. **July re-test (this edition).** On 2026-07-02 the key probes were re-run against the official MCP server of a **production n8n instance running the current stable release** (instance identity withheld): the `update_workflow` schema plus a live 4-op edit, the five validator probes, `validate_node_config` probes, and payload measurements for the insert-node and Code-node edit shapes. n8n-mcp-side payload numbers are carried from the June staging measurements (v2.59.0); the edit shapes are identical, so the comparison holds. - -**A note on version drift.** The June edition's central caveat — the live stable server and the source tree disagreed — is resolved: the diff-based `update_workflow` and `validate_node_config` are live on current instances (§3, §6). What remains is **instance drift**: servers on older n8n versions still expose the full-code update path (one such live server was observed as late as 2026-07-02), while n8n's docs date partial-update support to v2.20.0 — earlier than the June live observation of full-code on the then-stable channel. Treat per-instance MCP capability as a function of that instance's n8n version, not of the docs. - -If you find a factual error or want to challenge a measurement, please open an issue or PR. - ---- - -## 3. The update problem: parity shipped, measured - -### 3.1 Shipped and live-verified (2026-07-02) — diff-based - -On a production instance running the current stable release, `update_workflow` accepts only `{ workflowId, operations[] }`: - -- **12 operation types observed live**: `updateNodeParameters, setNodeParameter, addNode, removeNode, renameNode, addConnection, removeConnection, setNodeCredential, setNodePosition, setNodeDisabled, setNodeSettings, setWorkflowMetadata`. (The 2.27.0 source tree's `addTags`/`removeTags` were not registered on the tested instance — registration appears version- or flag-dependent.) -- **Atomic, max 100 ops/call**; first failing op aborts the batch, nothing saved. There is no dry-run (`validateOnly`) and no best-effort (`continueOnError`) mode — always atomic-or-throw. -- **The full-SDK-code update path is gone from the schema.** The asymmetry noted in June shipped as predicted: `create_workflow_from_code` remains SDK-TypeScript-only — the SDK lives on the create path while update moved to JSON ops. -- A real 4-op "insert one node mid-flow" edit (9→10 nodes) applied cleanly and returned `validationWarnings: []`. - -Measured payloads for identical edit shapes (official live 2026-07-02 vs n8n-mcp June staging measurements): - -| Edit | Official `update_workflow` (diff, live) | n8n-mcp `n8n_update_partial_workflow` | -|---|---|---| -| Insert one node mid-flow (4 ops) | **509 chars** | **~492 chars** | -| One-line change in a ~1 KB Code node | **1,174 chars** (whole `jsCode` resent via `setNodeParameter`) | **220 chars** (`patchNodeField` find/replace) | - -Whole-value edits are a statistical tie. The raw per-edit token multiple from the April/June editions is **retired for current n8n versions**. The surviving, growing gap is the surgical-edit shape (§3.3). - -### 3.2 The lag tail — where the old gap still applies - -Instances that have not rolled forward still expose the full-code `update_workflow` (`{ workflowId, code }`) — one such live server was still observed on 2026-07-02. For those, the June measurements stand: a full program resend per edit (1,715 chars to add one node to a 9-node workflow, where the change itself is 154 chars), scaling with workflow size against n8n-mcp's flat ~550-char diffs: - -| Workflow size | n8n-mcp CREATE (JSON) | n8n-mcp partial-update (ops) | -|---|---|---| -| 4 nodes | 1,320 chars | 561 chars | -| 15 nodes | 5,295 chars | 556 chars | -| 30 nodes | 10,795 chars | 550 chars | - -That puts the per-edit ratio on pre-diff instances at ~3.5× (9 nodes) climbing toward ~20× (30 nodes). n8n's docs date partial-update support to v2.20.0, which conflicts with the June live observation of full-code on the then-stable channel; the likeliest explanation is progressive rollout or flag gating. Practical read: **the gap is now a property of the instance's version, and it shrinks to zero as the fleet upgrades.** - -### 3.3 The advantage that survives parity: surgical in-field edits - -n8n-mcp's `patchNodeField` does **string find/replace inside a single field** (`patches: [{find, replace, replaceAll?, regex?}]` on a dot path like `parameters.jsCode`; `src/services/workflow-diff-engine.ts:1009-1013`). Changing one line of a large Code node sends only the changed snippet — measured at **151 chars** for a `version: '1.0'` → `'2.0'` edit on staging. - -The official `setNodeParameter` is an RFC 6901 JSON Pointer set: it writes the **entire value** at the pointer and explicitly **does not support array indices** — the shipped tool's own schema says *"Array indices are NOT supported — to change a value inside an array, set the whole array."* There is no find/replace anywhere in the official op set. **Measured against the shipped diff tool (2026-07-02):** a one-line edit inside a 999-char `jsCode` cost **1,174 chars** officially (full-field resend) vs **220 chars** via `patchNodeField` — **5.3×**, and because the official cost tracks field size while the patch cost is constant, the ratio grows linearly (a 10 KB Code node → ~50×). - -n8n-mcp also carries **19 ops vs 12 observed live** (14 in the 2.27.0 source tree), plus `validateOnly` (dry-run) and `continueOnError` modes the official tool lacks (it is always atomic-or-throw). Notable additional capabilities vs the official op set include `patchNodeField`, `rewireConnection`, `cleanStaleConnections`, and `replaceConnections` (plus `validateOnly`/best-effort modes). - -### 3.4 Why iteration matters (usage context, 2026-04-30 telemetry — not re-queried) - -*The figures below are dated 2026-04-30 and are carried forward unchanged; they establish that iteration dominates real usage. They are aggregate and anonymized per the [privacy policy](../PRIVACY.md).* - -- **6.21:1 update-to-create ratio** across 84,034 users in 90 days — iteration, not greenfield authoring, is the dominant pattern. -- **89.2% of update calls** go through the diff-based partial tool when users have the choice. -- Real workflow sizes cluster where diffs matter: **mean 23.4 nodes**, p90 51, p99 123. - -**Retired claim.** The April edition projected ~$601k/quarter in avoided output-token cost versus the official server, on the premise that the official path always full-rewrites. That premise has now expired (§3.1), so the headline dollar projection stays withdrawn. The defensible residual cost argument is narrower: (a) it holds only for **instances still on pre-diff n8n versions** (§3.2), and (b) it persists indefinitely for **large-field / Code-node / array edits** via `patchNodeField` (measured 5.3× at ~1 KB, scaling with field size). Anyone re-running the cost analysis should scope it to those two cases and re-query telemetry rather than reuse the old figure. - ---- - -## 4. Architecture & transport (official, 2.27.0 source) - -- **Location:** `packages/cli/src/modules/mcp/` (mounted on the `main` instance). -- **Endpoint:** `/mcp-server/http` with HEAD/GET/POST (`mcp.controller.ts:29,77,110`). -- **Transport:** stateless Streamable HTTP — a fresh `McpServer` + transport per request (`sessionIdGenerator: undefined`, `mcp.controller.ts:200-206`). -- **Auth:** Bearer token routed by a JWT `meta.isOAuth` flag to either OAuth access-token verification or MCP API-key verification (`mcp-server-middleware.service.ts:39-60`). HEAD returns `401` with `WWW-Authenticate: Bearer` for discovery. CORS is wide-open (`*`). -- **Server identity:** name `n8n MCP Server`, version bumps to **1.1.0** when the builder is enabled (`mcp.service.ts:204-213`). -- **Resources:** one MCP resource, `n8n://workflow-sdk/reference` (builder path only). When `N8N_MCP_APPS_ENABLED` (default false) is on, a workflow-preview MCP-App iframe is attached to `create_workflow_from_code` (`mcp.service.ts:475-500,554-571`). - -n8n-mcp by contrast ships a standalone MCP server (stdio + single-session HTTP with persistent session state) plus a multi-tenant SaaS (OAuth2/Auth0, AES-256-GCM-encrypted per-instance credentials so users never expose their n8n API key to the AI client). - ---- - -## 5. The TypeScript Workflow SDK - -The SDK is the codegen engine behind the official create path. It matured from 0.12.x to 0.20.0 over ~9 roughly-weekly minors (npm `time` object: 0.12.0=2026-04-28 … 0.19.2=2026-06-15, 0.20.0=2026-06-16); as of 2026-07-02, npm `latest` is **0.21.2** — the weekly cadence continues. - -- **Authoring (unchanged in spirit):** the LLM writes `workflow('id','name').add(trigger).to(node...)` with `node()/trigger()/ifElse()/switchCase()/merge()/splitInBatches()` and AI subnode binding by reference (`subnodes: { model, tools, memory, outputParser }`). Type-checked authoring for built-in nodes via `get_node_types` (real `.d.ts`); auto-layout via `@dagrejs/dagre`. -- **What's new:** full **bidirectional round-trip codegen** (`json-to-code` and `code-to-json` CLIs with dedicated roundtrip test suites) and composite control-flow handlers (if-else, switch-case, splitInBatches/merge). Round-trip is the mechanism behind "update existing workflows" — and behind the 2.27.x move of update onto JSON ops. -- **What it still gives up:** community-node typing (SDK type generation reads only `nodes-base` and `@n8n/nodes-langchain`, `generate-types.ts:6-8,40-44`); and the AST-interpreter foot-guns remain (reserved JS identifiers like `fetch` rejected as "Security violation"). - ---- - -## 6. Validation - -### 6.1 Live probes against the stable official validator - -Five invalid configurations were sent to the official `validate_workflow` and to n8n-mcp's `validate_workflow` (profile `runtime`): - -| Probe | Official (live, stable) | n8n-mcp (live) | -|---|---|---| -| Unknown node type (`totallyMadeUpNode`) | **`valid:true`** (silent) | **ERROR** — "Unknown node type … must include the package prefix" | -| `typeVersion: 99` on httpRequest | **`valid:true`** (silent) | **ERROR** — "typeVersion 99 exceeds maximum supported version 4.4" | -| HTTP Request without `url` | **`valid:true`** (silent) | **ERROR** — "Required property 'URL' cannot be empty" | -| Two nodes with the same name | **`valid:true`** (silent) | **ERROR** — "Duplicate node name" | -| AI Agent without language model | **`valid:true`** + 3 warnings (incl. "Required field subnodes is missing") | **ERROR** — `MISSING_LANGUAGE_MODEL` | - -Four of five pass silently as `valid:true`; the fifth is `valid:true` with warnings. An agent loop using `valid:true` as its stop signal accepts all five broken workflows as done. n8n-mcp errors on all five. - -**July re-run (current stable release, live 2026-07-02):** all five probes **still return `valid:true`**. Three remain fully silent (unknown node type, `typeVersion: 99`, duplicate node names); two now attach non-blocking warnings (HTTP-without-URL → an `INVALID_PARAMETER` warning; AI-Agent-without-LM → 3 warnings including the missing `subnodes`). The June source-tree prediction — Zod schema errors downgraded to warnings "to maintain backwards compatibility" — is confirmed in shipped behavior. The stop-signal failure mode is unchanged: `valid:true` accepts all five broken workflows. - -### 6.2 What shipped since June (live-verified 2026-07-02) - -- **Single-node validation is live:** `validate_node_config` validates 1–50 candidate node configs in isolation. Probed directly: it returns **precise per-field errors** for a missing required field (`Required field "parameters.url" is missing. Expected string.`) and for an AI Agent missing its model (`Required field "subnodes" is missing`). But it **silently returns `valid:true`** for an unknown node type (`totallyMadeUpNode`), an impossible `typeVersion: 99`, and **any community-node type** — no schema means no validation, exactly the `loadSchema` graceful-fallback hole the June source analysis predicted. For community nodes the official validation surface is a rubber stamp. -- **Structured result:** `validate_workflow` returns `{valid, errors, warnings}`; hard parse failures yield `valid:false`. -- **Expanded taxonomy** (2.27.0 source): ~33 error/warning codes with `violationLevel`; new structural checks (Switch outputs/fallback, Merge `numberInputs`, input/output index validity, invalid `ai_tool` source, placeholder slots). Note: the source tree treats AI-Agent-without-LM as a hard error (`MISSING_REQUIRED_INPUT`), but the live current-release server reports it as a **warning** (§6.1 July re-run) — the softer path is what shipped. -- **Both April findings are now confirmed in shipped behavior:** (1) Zod config errors are downgraded to warnings (source comment: *"Report as WARNING (non-blocking) to maintain backwards compatibility"*) — a broken node config is still `valid:true`. (2) Unknown node types and invalid typeVersions pass silently via the no-schema fallback, at both workflow and single-node level. - -### 6.3 n8n-mcp validation edge - -- **4 named profiles** (`minimal`, `runtime`, `ai-friendly`, `strict`) vs one un-exposed `strictMode` boolean. -- **By-ID validation** (`n8n_validate_workflow`) and **autofix** (`n8n_autofix_workflow`, 13 fix types) — the official server reports warnings but never repairs. -- **Schema errors are real errors**, not silent warnings; **community nodes are validated** (the official server treats no-schema nodes as `valid:true`). - -### 6.4 Where the official validator is genuinely strong - -Field-level expression-path validation against upstream `output:` samples and `INVALID_INPUT_INDEX` with concrete fix suggestions remain clever patterns n8n-mcp does not fully replicate; the SDK error messages are high quality and speak the SDK syntax directly. - ---- - -## 7. Tool inventory - -The 2.27.0 source tree registers **30 tools** (18 always-on + 12 builder-only, `mcp.service.ts:216-576`). The current-release production server tested 2026-07-02 exposed **28 tools live**, including `validate_node_config`, `list_credentials`, `search_executions`, `get_suggested_nodes` (now registered — June's stable had it defined but unregistered), the 7-tool data-table suite, and `prepare_test_pin_data`; **not** observed on that instance: `explore_node_resources`, `get_workflow_best_practices`, `list_tags` (registration appears version- or flag-dependent). Two other July observations: the server's mandated authoring pipeline got heavier (SDK reference → `get_suggested_nodes` → search → `get_node_types` → per-node `validate_node_config` → `validate_workflow` → create), and `search_nodes` results now carry rich `@builderHint`/`@relatedNodes` guidance metadata — including a first-party **`@n8n/mcp-registry.*` node family** (e.g. `@n8n/mcp-registry.apify`) for agent-optimized MCP integrations. - -| Capability | Official | n8n-mcp | -|---|---|---| -| **Discovery** | | | -| Search nodes | `search_nodes` (instance registry) | `search_nodes` (FTS5, OR/AND/FUZZY, source filter) | -| Node detail | `get_node_types` (`.d.ts`, built-ins only) | `get_node` (info/docs/search_properties/versions/compare/breaking/migrations) | -| Suggest nodes | `get_suggested_nodes` (registered, live 2026-07-02) | `search_templates` mode `patterns` | -| SDK reference | `get_sdk_reference` + resource | n/a — no SDK | -| **Authoring** | | | -| Create | `create_workflow_from_code` (SDK code) | `n8n_create_workflow` (JSON) + `n8n_generate_workflow` (NL, hosted) | -| Update full | n/a (update is the diff/code tool) | `n8n_update_full_workflow` (JSON) | -| **Update partial** | ✅ shipped (12 ops observed live) | ✅ `n8n_update_partial_workflow` (19 ops) | -| Validate workflow | `validate_workflow` (all 5 broken probes pass as `valid:true`) | `validate_workflow` (4 profiles) + `n8n_validate_workflow` (by ID) | -| Validate single node | `validate_node_config` (shipped; blind to unknown types/versions & community nodes) | `validate_node` | -| Autofix | ❌ | `n8n_autofix_workflow` | -| **Lifecycle** | | | -| Drafts/publish | `publish_workflow` / `unpublish_workflow` | n/a — `active` flag | -| Archive / delete | `archive_workflow` (soft) | `n8n_delete_workflow` | -| Version history | ❌ | `n8n_workflow_versions` (list/get/rollback/delete/prune) | -| **Execution** | | | -| Execute / test | `execute_workflow`, `test_workflow` | `n8n_test_workflow` | -| Executions | `get_execution`, `search_executions` | `n8n_executions` | -| Pin-data prep | `prepare_test_pin_data` | ❌ | -| **Org / structure** | | | -| Projects / folders | `search_projects` / `search_folders` | projectId only; no folders | -| Data tables | 7 dedicated tools | `n8n_manage_datatable` (CRUD + filter + dryRun) | -| **Operations** | | | -| Health check | ❌ | `n8n_health_check` | -| Templates | ❌ | `search_templates` + `get_template` + `n8n_deploy_template` (2,700+) | -| Credentials | read-only `list_credentials` + auto-assign | `n8n_manage_credentials` (CRUD + getSchema + includeUsage) | -| Instance audit | ❌ | `n8n_audit_instance` | - ---- - -## 8. Workflow management - -### 8.1 Drafts/publish, projects/folders, pin-data (official advantages — still hold) - -`publish_workflow` / `unpublish_workflow` operate the draft/publish model in `WorkflowEntity`; `create_workflow_from_code` accepts `projectId` + `folderId`; `prepare_test_pin_data` returns JSON Schemas for pin-data so logic nodes run for real while credentialed/external I/O is bypassed. n8n-mcp has none of these surfaces (folder placement is deferred). - -### 8.2 Credentials — two trust models (unchanged) - -The official server walks each added node's credential slots and auto-assigns the user's first matching credential, **excluding HTTP Request node types for security** (`credentials-auto-assign.ts:19-23`) — live-confirmed 2026-07-02: on create, auto-assign explicitly skipped the workflow's HTTP Request node ("credentials must be configured manually"); `list_credentials` is read-only and never returns secrets. The LLM has no credential CRUD. n8n-mcp takes the opposite approach: full visibility via `n8n_manage_credentials` (list/get/create/update/delete/getSchema), explicit selection between multiple credentials of a type, and HTTP nodes as first-class — appropriate to its standalone-server architecture where the agent operates with the user's API key. - ---- - -## 9. Distribution & gating (official, 2.27.0 source) - -| Flag | Default | Effect | -|---|---|---| -| `N8N_MCP_ACCESS_ENABLED` | `false` | Master switch (instance MCP access) | -| `N8N_MCP_MANAGED_BY_ENV` | `false` | Env-only management (cloud managed mode) | -| `N8N_MCP_BUILDER_ENABLED` | `true` | Toggles the 12 builder-only tools | -| `N8N_MCP_APPS_ENABLED` | `false` | Force-enables the MCP-App preview iframe | -| `N8N_MCP_MAX_REGISTERED_CLIENTS` | `5000` | OAuth client cap | -| `N8N_MCP_SERVER_RATE_LIMIT` | `100` | Requests / IP / 5 min | -| `settings.availableInMCP` (per workflow) | `false` | Workflows must opt in to MCP | - -Source: `packages/@n8n/config/src/configs/endpoints.config.ts:162-175`, `instance-settings-loader.config.ts:117-121`, `mcp.config.ts:11-12`. - ---- - -## 10. Empirical artifacts from this analysis - -**Live, official server on a production instance, current stable release (2026-07-02; instance identity withheld):** -- `update_workflow` schema = `{ workflowId, operations[] }`, 12 op types, atomic, max 100/call; the full-code path is absent. A 4-op "insert one node mid-flow" edit applied cleanly (9→10 nodes, `validationWarnings: []`). -- Payload measurements: insert-one-node = **509 chars** (vs n8n-mcp ~492, June staging); one-line edit in a 999-char `jsCode` = **1,174 chars** via `setNodeParameter` full-field resend (vs **220 chars** via `patchNodeField` for the identical edit — 5.3×). -- Validator probes (all five still `valid:true`): unknown node type, `typeVersion: 99`, duplicate node names → silent; HTTP-without-URL → + `INVALID_PARAMETER` warning; AI-Agent-without-LM → + 3 warnings. -- `validate_node_config` probes: precise errors for missing `parameters.url` and missing agent `subnodes`; **silent `valid:true`** for `totallyMadeUpNode`, httpRequest `typeVersion: 99`, and a community-node type. -- Credential auto-assign on create skipped the HTTP Request node (security exclusion live-confirmed). -- 28 tools registered, incl. `validate_node_config`, `list_credentials`, `search_executions`, `get_suggested_nodes`; `list_tags` / `explore_node_resources` / `get_workflow_best_practices` absent on this instance. -- Ecosystem observation: `search_nodes` surfaced a first-party `@n8n/mcp-registry.apify` node with agent-targeted builder hints — an MCP-registry node family. - -**Live, official server (stable channel, 2026-06-18/19 — previous edition):** -- `update_workflow` tool schema = `{ workflowId, code }` (full SDK code) — full-rewrite confirmed. -- 9-node SDK workflow: validated `{valid:true, nodeCount:9}`; CREATE code 1,561 chars; full resend to add one node = 1,715 chars (change itself 154 chars). -- Validator probes: unknown node, typeVersion 99, HTTP-without-URL, duplicate name → `valid:true` (silent); AI-Agent-without-LM → `valid:true` + 3 warnings. -- Community nodes: `search_nodes(["playwright"])` → "No nodes found"; `get_node_types(["n8n-nodes-playwright.playwright"])` → "not found"; `get_node_types(["n8n-nodes-anchorbrowser.anchorBrowser"])` → "not found" **even though that node is installed** (search surfaced it under "browser automation"). Confirms: official can discover installed community nodes but cannot type/validate them. - -**Live, n8n-mcp staging (v2.59.0):** -- `n8n_update_partial_workflow` advertises 19 op types; atomic by default, `continueOnError` + `validateOnly` modes. -- CREATE vs partial-update payloads: 1,320/561 (4 nodes), 5,295/556 (15), 10,795/550 (30). -- 4-edit cumulative on a 15-node workflow: 492 + 151 + 184 + 273 = 1,100 chars / 11 ops; the `patchNodeField` one-line edit was 151 chars. -- Validator probes: all 5 ERROR (`valid:false`) with precise messages. -- Community node: `search_nodes("playwright")` returns the node (community, v0.2.21, 10k npm downloads, full schema). - -**Source (n8n 2.27.0 clone, master, 2026-06-18):** diff-based `update_workflow` (14 ops, 100 cap, atomic), `validate_node_config`, 30-tool surface, ~33 validation codes, SDK 0.20.0 round-trip codegen — none yet in a release tag. - ---- - -## 11. Source citations - -**Official MCP (n8n monorepo, master @ 2.27.0, 2026-06-18 clone):** -- `packages/cli/src/modules/mcp/mcp.service.ts` (tool registration; server identity; resources) -- `packages/cli/src/modules/mcp/tools/workflow-builder/{update-workflow.tool,workflow-operations,create-workflow-from-code.tool,validate-node.tool,validate-workflow-code.tool,credentials-auto-assign}.ts` -- `packages/cli/src/modules/mcp/tools/list-credentials.tool.ts` -- `packages/cli/src/modules/mcp/{mcp.controller,mcp-server-middleware.service,mcp.config}.ts` -- `packages/@n8n/workflow-sdk/{package.json,src/validation/index.ts,src/generate-types/generate-types.ts}` -- `packages/@n8n/config/src/configs/{endpoints.config,instance-settings-loader.config}.ts` - -**Official live observations:** the connected official MCP server's tool schemas and responses (`update_workflow`, `validate_workflow`, `search_nodes`, `get_node_types`, `get_sdk_reference`, `search_workflows`), 2026-06-18. - -**Official live observations (2026-07-02):** the connected official MCP server of a production instance on the current stable release — `update_workflow` operations schema and applied edits, `validate_workflow` and `validate_node_config` probe responses, `search_nodes` results, `create_workflow_from_code` / `archive_workflow` behavior. Instance identity withheld. - -**External:** -- npm: `registry.npmjs.org/@n8n/workflow-sdk` (0.12.0 → 0.20.0; `latest` 0.19.2 as of 2026-06-19, **0.21.2** as of 2026-07-02) and `n8n` (`latest` 2.26.7 as of 2026-06-19, **2.28.4** as of 2026-07-02; the 1.x line remains maintained at 1.123.62) -- docs.n8n.io: MCP server tools reference (dates `update_workflow` partial updates to v2.20.0 and `validate_node_config` to v2.25.1; see §2 on the conflict with the June live observation) -- Blog: `blog.n8n.io/n8n-mcp-server` (frames update as conversational full re-generation; no diff/partial messaging) -- Community: `community.n8n.io/t/create-workflows-via-mcp/280856` (create+update shipped in n8n 2.14.0 beta) - -**n8n-mcp side:** -- `src/services/workflow-diff-engine.ts` (partial-update engine; `patchNodeField` at 1009-1013) -- `src/types/workflow-diff.ts` (`PatchNodeFieldOperation`, 58-69) -- `src/mcp/tools.ts`, `src/mcp/tools-n8n-manager.ts` (full tool surface; credentials, audit, templates) -- `PRIVACY.md` (telemetry policy) - -**Telemetry sources (queried 2026-04-30, not refreshed for this edition):** landing-page aggregates and daily tool-usage aggregates as cited inline in §3.4.