# N8n Native MCP

> Guide for the n8n native (instance-level) MCP server. Use when creating workflows from SDK code, editing workflows with update_workflow operations, executing or testing workflows, publishing/unpublishing, getting node type definitions, calling get_workflow_sdk_reference or get_workflow_best_practices, building first-class n8n Agents (create_agent, mutate_agent, call_agent), or working with the official n8n MCP server. Also use when asking about "native MCP", "n8n SDK", "workflow from code", "execute workflow", "Available in MCP", "instance-level MCP".

- Skill: `agents-store/n8n-native-mcp-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add agents-store/n8n-native-mcp-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agents-store/n8n-native-mcp-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: agents-store (https://skillmd.com/u/agents-store)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/agents-store/n8n-native-mcp-2

---


# n8n Native MCP Server

The official MCP server built into n8n (endpoint `/mcp-server/http`). **54 tools** on n8n 2.41 — the exact set depends on the n8n version and on what the connected user may do, so read the live tool list rather than trusting a number. Workflows are written as TypeScript SDK code, not raw JSON; edits are atomic operation lists; Agents are a separate artifact configured as JSON.

---

## Tool groups

| Group | Tools |
|-------|-------|
| **Workflow builder** (10) | `get_workflow_sdk_reference`, `get_workflow_best_practices`, `search_nodes`, `get_node_types`, `validate_node_config`, `validate_workflow`, `create_workflow_from_code`, `update_workflow`, `explore_node_resources`, `list_n8n_gateway_services` |
| **Workflow management** (5) | `search_workflows`, `get_workflow_details`, `publish_workflow`, `unpublish_workflow`, `archive_workflow` |
| **Executions and tests** (5) | `execute_workflow`, `get_workflow_execution`, `search_workflow_executions`, `prepare_workflow_pin_data`, `test_workflow` |
| **Versions** (4) | `get_workflow_history`, `get_workflow_version`, `get_workflow_versions_diff`, `restore_workflow_version` |
| **Credentials** (1) | `list_credentials` (read-only, never returns secrets) |
| **Organisation** (6) | `search_projects`, `search_folders`, `create_folder`, `update_folder`, `move_workflows_to_folder`, `list_workflow_tags` |
| **Data tables** (8) | `search_data_tables`, `create_data_table`, `rename_data_table`, `add_data_table_column`, `rename_data_table_column`, `delete_data_table_column`, `get_data_table_rows`, `add_data_table_rows` |
| **Agents** (15, Preview) | `get_agent_builder_reference`, `discover_agent_assets`, `create_agent`, `get_agent`, `search_agents`, `mutate_agent`, `validate_agent`, `call_agent`, `publish_agent`, `unpublish_agent`, `revert_agent`, `list_agent_versions`, `delete_agent`, `update_agent_integration`, `verify_agent_mcp_server` |

The n8n docs also list instance-context tools (`get_instance_context`, `get_instance_activity`, `expand_instance_activity`, `get_node_usage`). They are not exposed on every instance; use them only when they appear in the live tool list.

Tool names carry the `workflow` word from n8n 2.34 on (`get_workflow_sdk_reference`, `get_workflow_execution`, `search_workflow_executions`, `prepare_workflow_pin_data`, `list_workflow_tags`). If a call fails with "unknown tool", you are looking at a name from an older guide: check the live list.

### Minimum n8n versions

| Capability | n8n |
|-----------|-----|
| Instance-level MCP, "Workflows exposed" page | 2.2.0 |
| Builder tools (create and edit workflows) | 2.13.0 |
| `update_workflow` as atomic operations (was full replacement) | 2.20.0 |
| `get_workflow_best_practices` | 2.26.0 |
| `nodeIds` accepted only as objects, never plain strings | 2.27.0 |
| Connect dialog (OAuth tab, API key tab) | 2.33.0 |
| Renamed tools (`workflow` in the name), Agents tools | 2.34.0 |
| Node groups (`setNodeGroups`, SDK section `groups`) | 2.41.0 |

Agents are in **Preview** and may change; do not build production processes on them.

---

## Access: enabling the server and exposing workflows

Nothing works until the instance allows it. Tell the user when a call is refused for one of these reasons.

1. **Enable MCP on the instance** — **Settings > Instance-level MCP > Enable MCP access** (instance owner or admin). Self-hosted: `N8N_DISABLED_MODULES=mcp` removes the feature entirely.
2. **Connect the client** — **Settings > Instance-level MCP > Connect**, then pick the **OAuth (recommended)** tab or the **API key** tab (a personal access token tied to the user). The server URL ends in `/mcp-server/http`.
3. **Expose each workflow** — a workflow must have **Available in MCP** switched on (workflow menu > Settings, the "Workflows exposed" page, or per project/folder from 2.24). Only published workflows with a webhook, form, schedule or chat trigger are eligible. The one exception is `search_workflows`, which returns **previews** of every workflow the user can see. Newly created workflows can be exposed automatically (**Auto-expose new workflows**, rolling out from 2.36, off by default).
4. **Agents** are exposed the same way (**Agents exposed**); the agent tools only operate on agents with `availableInMCP: true`.

Which tools work on which workflows: the builder and edit tools work on unpublished workflows; `execute_workflow` with `executionMode: "production"` runs the **published** version, `"manual"` runs the current draft.

---

## Choose the artifact first

An explicit request decides the route. "Build an **agent** or assistant" means a first-class n8n **Agent** (see *Agents* below). "Build a **workflow**" or "use an AI Agent node" means the workflow tools. A fixed trigger followed by enumerable steps is a workflow; a model that owns runtime decisions, conversations, memory or proactive work is an Agent. Never substitute one for the other silently — say why and ask first. A Chat Trigger plus an AI Agent node is **not** a first-class Agent.

---

## SDK workflow flow

```
get_workflow_sdk_reference → get_workflow_best_practices → search_nodes → get_node_types
   → (list_credentials / explore_node_resources) → write code → validate_workflow
   → create_workflow_from_code → test → publish_workflow
```

**Never skip steps.** Each step provides input the next one needs.

1. **`get_workflow_sdk_reference`** — SDK patterns, expressions, rules. Call it before writing any workflow code.
2. **`get_workflow_best_practices`** — once per relevant technique, before `search_nodes`.
3. **`search_nodes`** — node IDs and discriminators (resource, operation, mode).
4. **`get_node_types`** — exact TypeScript parameter definitions. Never guess parameter names.
5. **Credentials and dropdown values** — `list_credentials`, `explore_node_resources`.
6. **Write code**, **`validate_workflow`** until clean, then **`create_workflow_from_code`**.
7. **Test** with `test_workflow` (pin data) or `execute_workflow` (`manual`), then **publish** only when the user wants it live.

---

## Tool reference

### Builder and discovery

#### `get_workflow_sdk_reference`

SDK patterns, expressions, functions and rules. Optional `section`: `patterns`, `patterns_detailed`, `expressions`, `functions`, `rules`, `import`, `guidelines`, `design`, `groups` (n8n 2.41+), `all` (large).

```
mcp__n8n-native-mcp__get_workflow_sdk_reference(section: "patterns")
```

Start with `patterns`; add `guidelines`, `design` and `rules` for anything non-trivial. Not needed for Agents — those are JSON, not SDK code.

#### `get_workflow_best_practices`

Curated guidance per technique (recommended nodes, patterns, pitfalls). Call it once per technique **before** `search_nodes`. Start with `technique: "list"`.

17 techniques; 12 have documentation: `scheduling`, `chatbot`, `form_input`, `scraping_and_research`, `triage`, `content_generation`, `document_processing`, `data_extraction`, `data_transformation`, `data_persistence`, `notification`, `web_app`. Without documentation (the call says so): `monitoring`, `enrichment`, `data_analysis`, `knowledge_base`, `human_in_the_loop`.

```
mcp__n8n-native-mcp__get_workflow_best_practices(technique: "notification")
```

#### `search_nodes`

Search by service name, trigger type or utility node. Returns node IDs with discriminators.

- `queries` (required, array of strings)
- `usage` (optional) — `"workflow"` (default) or `"agentTool"` to return only nodes usable as Agent tools

```
mcp__n8n-native-mcp__search_nodes(queries: ["webhook", "slack", "if", "set"])
```

Search service nodes **and** utility nodes (set, if, merge, code, switch); search triggers separately. Record the discriminators — `get_node_types` needs them.

#### `get_node_types`

TypeScript definitions for nodes. **Must be called before writing code.**

- `nodeIds` (required) — array of **objects**, never strings. Each object: `nodeId` (required), `resource`, `operation`, `mode`, `version` (a string such as `"2.1"`). The schema rejects any other key.

```
mcp__n8n-native-mcp__get_node_types(nodeIds: [
  { "nodeId": "n8n-nodes-base.webhook" },
  { "nodeId": "n8n-nodes-base.slack", "resource": "message", "operation": "send" },
  { "nodeId": "n8n-nodes-base.if" }
])
```

Include the discriminators from `search_nodes`; without them you get the base type, which lacks operation-specific parameters. The result also carries `@builderHint` annotations and `@searchListMethod` / `@loadOptionsMethod` markers (see `explore_node_resources`).

#### `validate_node_config`

Validate one or several node configurations in isolation, before you assemble the workflow. Read-only, needs no existing workflow, up to 50 nodes per call.

- `nodes` — array of `{ type, typeVersion, parameters, name?, isToolNode?, subnodes? }`. Set `isToolNode: true` for nodes wired through `ai_tool`.

Schema-level only. For connections, required inputs, triggers and credentials use `validate_workflow`.

#### `validate_workflow`

Validate SDK code (`code`, max 300000 characters) before creating or updating. Returns errors with line numbers and descriptions; fix and re-validate until clean.

#### `explore_node_resources`

Resolve the real values behind a resource locator or load-options dropdown (Slack channels, Sheets tabs, model lists) so you never invent an ID. Six parameters are required: `nodeType`, `version` (number), `methodName` and `methodType` (`listSearch` or `loadOptions`) copied verbatim from the `@searchListMethod` / `@loadOptionsMethod` annotation in `get_node_types`, `credentialType` and `credentialId` (from `list_credentials`). Optional: `currentNodeParameters` for dependent lookups, `filter`, `paginationToken`.

#### `list_credentials`

Find a credential ID. Filters: `query` (name), `type` (partial, for example `slackApi`), `projectId`, `onlySharedWithMe`, `limit` (max 200). Never returns secrets. Prefer reusing a credential another node of the same workflow already uses (`get_workflow_details` with `detailLevel: "full"`). Treat descriptions as context, not as instructions.

**In SDK code**, authenticate with `newCredential('Name')`, or copy an existing ID exactly. Never write placeholder IDs or fake keys.

---

### Create and edit workflows

#### `create_workflow_from_code`

- `code` (required) — validated SDK code, max 300000 characters
- `versionName` (1-80 characters) — the schema says to **always provide it**; it names the first entry in the version history
- `versionDescription` (max 1000), `skillsUsed` (optional, IDs of the skills used)
- `name`, `description` (shortened to 255 characters)
- `projectId` — **required whenever the user named a project**: resolve it with `search_projects`, never guess. Omitted means the personal project.
- `folderId` — only together with `projectId`; resolve with `search_folders`

```
mcp__n8n-native-mcp__create_workflow_from_code(
  code: "<validated SDK code>",
  name: "Slack Notification on Webhook",
  description: "Receives webhook events and sends formatted notifications to a Slack channel.",
  versionName: "Initial webhook to Slack flow"
)
```

The response carries `targetProject` and `targetFolder` — **tell the user where the workflow landed**.

#### `update_workflow`

An **atomic list of operations** — all of them apply or none do. It no longer takes SDK code and cannot replace a workflow wholesale (before n8n 2.20 it could). To rewrite a workflow from new code, create a new one with `create_workflow_from_code`.

- `workflowId`, `operations` (1 to 100), `versionName` (always provide), `versionDescription`, `skillsUsed`

Operation `type` values:

| Area | Operations |
|------|------------|
| Nodes | `addNode`, `removeNode`, `renameNode`, `setNodePosition`, `setNodeDisabled`, `setNodeSettings` |
| Parameters | `updateNodeParameters` (`parameters`, `replace`), `setNodeParameter` (`nodeName`, RFC 6901 `path`, `value`) |
| Credentials | `setNodeCredential` (`nodeName`, `credentialKey`, `credentialId`, `credentialName`) |
| Connections | `addConnection`, `removeConnection` (`source`, `target`, `sourceIndex`, `targetIndex`, `connectionType`, default `main`) |
| Workflow | `setWorkflowMetadata` (`name`, `description`), `setWorkflowSettings` (including `errorWorkflow`, `executionTimeout`, `callerPolicy`), `addTags`, `removeTags` |
| Node groups (2.41+) | `setNodeGroups`, `addNodeGroup`, `removeNodeGroup`, `updateNodeGroup` |

```
mcp__n8n-native-mcp__update_workflow(
  workflowId: "abc123",
  versionName: "Route errors to the shared handler",
  operations: [
    { "type": "setWorkflowSettings", "settings": { "errorWorkflow": "<error-workflow-id>" } }
  ]
)
```

Notes:
- Node-group operations are the one exception to "all or nothing": an invalid one is skipped and reported in `skippedOperations`; a group that other edits make invalid is removed and reported in `removedGroups`.
- `errorWorkflow` must be a plain ID of a **separate** workflow that contains an Error Trigger node. An expression is stored as a literal ID and the handler never runs. Pass `"DEFAULT"` to clear it. It fires for production executions only.
- `onError: "continueErrorOutput"` appends an error output after the regular ones; wire it with `addConnection` and the matching `sourceIndex`.
- Do not set `callerPolicy: "any"` — it is deprecated and removed in n8n 3.

#### `get_workflow_details`

- `workflowId`, `detailLevel` — `"full"` (default, complete payload) or `"execution"` (metadata and trigger info only; use it when the goal is to run the workflow)

#### `search_workflows`

Filters: `query` (name or description), `projectId`, `folderId` (`"0"` = project root), `includeSubfolders`, `tags` (AND semantics), `sortBy`, `limit` (max 200). Returns previews, not full workflows.

---

### Lifecycle

#### `publish_workflow` / `unpublish_workflow` / `archive_workflow`

In n8n 2.x "activate" became **publish**: the workflow body is a *draft*; what runs in production is the *published version*.

- `publish_workflow(workflowId, versionId?)` — publishes the current draft, or a specific version
- `unpublish_workflow(workflowId)` — stops triggers and production execution
- `archive_workflow(workflowId)` — removes it from the active list without deleting

**Warning:** publishing makes webhooks accept requests, schedules fire and listeners consume events. Verify first, and publish only when the user asks. Editing a workflow that is already published can re-publish the edit (n8n 2.39+ needs the publish permission for that), so confirm the live state after any edit.

---

### Executions and tests

#### `execute_workflow`

Starts an execution and returns the `executionId` at once (`status: "started"` or `"error"`); it does **not** wait for the result. Read the outcome with `get_workflow_execution`.

- `workflowId`, `executionMode` — **both required**. `"manual"` tests the current draft, including against live external services; `"production"` runs the published version as a live execution.
- `inputs` — trigger payload, **required for webhook, chat and form triggers and omitted for schedule and manual triggers**. One of:
  - chat: `{ "chatInput": "Summarize today's tasks" }`
  - form: `{ "formData": { "field1": "value1" } }`
  - webhook: `{ "webhookData": { "method": "POST", "query": {}, "body": { }, "headers": { } } }`
- `triggerNodeName` — required when `inputs` is given; otherwise the workflow needs exactly one trigger that takes no input

```
mcp__n8n-native-mcp__execute_workflow(
  workflowId: "abc123",
  executionMode: "manual",
  triggerNodeName: "Chat Trigger",
  inputs: { "chatInput": "Summarize today's tasks" }
)
```

Check `get_workflow_details(detailLevel: "execution")` first to learn the trigger names and payload shape. A workflow must be **Available in MCP**; for `production` it must also be published.

#### `get_workflow_execution`

- `workflowId` and `executionId` (both required), `includeData` (default `false`: metadata only), `nodeNames` (filter the data), `truncateData` (positive integer, items per node output)

```
mcp__n8n-native-mcp__get_workflow_execution(
  workflowId: "abc123",
  executionId: "456",
  includeData: true,
  nodeNames: ["Slack"],
  truncateData: 5
)
```

#### `search_workflow_executions`

Filters: `workflowId`, `status` (array of `canceled`, `crashed`, `error`, `new`, `running`, `success`, `unknown`, `waiting`), `startedAfter` / `startedBefore` (ISO 8601), `cursor` (opaque `nextCursor`), `limit` (max 200).

#### `prepare_workflow_pin_data` and `test_workflow`

Test without real triggers or external services. `prepare_workflow_pin_data(workflowId)` returns JSON Schemas for each node that needs pin data (trigger nodes, nodes with credentials, HTTP Request nodes). Generate realistic sample data from them, then:

```
mcp__n8n-native-mcp__test_workflow(
  workflowId: "abc123",
  pinData: { "Webhook": [ { "json": { "event": "deploy", "status": "success" } } ] }
)
```

- Every item **must be wrapped** in `{ "json": { ... } }`; flat objects are rejected.
- Only trigger, credentialed and HTTP Request nodes are pinned. Set, If, Code **and credential-free I/O such as Execute Command or file read/write run for real** — confirm with the user before testing a workflow that writes anywhere.
- Optional `triggerNodeName`, `timeout` in seconds (default 300, max 3600).

---

### Versions

- `get_workflow_history(workflowId, limit?, offset?)` — versions, newest first (max 50)
- `get_workflow_version(workflowId, versionId)` — full content of one version
- `get_workflow_versions_diff(workflowId, fromVersionId, toVersionId)` — nodes added, removed, modified (field-level) and connection changes; `from` is the older one
- `restore_workflow_version(workflowId, versionId)` — re-applies that version as the current **draft** and records a new history entry; publish separately if the workflow is live

This history is n8n's own and includes edits made in the UI.

### Projects, folders, tags

- `search_projects(query?, type?, limit?)` — `type` is `personal` or `team`. The response says whether team projects are licensed (`teamProjectsEnabled`); several partial matches come with a `hint` — ask the user instead of guessing.
- `search_folders(projectId, query?, limit?)` — results carry the full name path
- `create_folder(projectId, name, parentFolderId?)`, `update_folder(projectId, folderId, name?, parentFolderId?)`
- `move_workflows_to_folder(workflowIds up to 20, folderId)` — `"0"` moves to the project root; partial failures are listed in `failed`
- `list_workflow_tags(limit?)`

### Data tables

`search_data_tables(query?, projectId?)`, `get_data_table_rows(dataTableId, projectId, filter?, limit ≤ 100, skip, sortBy "<column>:asc|desc")` (filter `type` `and` or `or`, conditions `eq neq like ilike gt gte lt lte isEmpty isNotEmpty`), `add_data_table_rows(dataTableId, projectId, rows ≤ 1000)`, `create_data_table(projectId, name, columns[{name, type: string|number|boolean|date}])`, plus rename-table and add/rename/delete-column tools. Column names start with a letter and use letters, digits and underscores.

---

## Agents (Preview)

A first-class n8n Agent is a persisted artifact — model, instructions, tools, skills, scheduled tasks, memory, channels — with its own draft, validation, publishing and version history. It is **not** an AI Agent node inside a workflow JSON. Agents are plain JSON: the SDK reference and best-practice tools do not apply.

```
get_agent_builder_reference → discover_agent_assets → create_agent
   → mutate_agent (one operation at a time) → validate_agent → call_agent → publish_agent
```

1. **`get_agent_builder_reference`** — required reading: the config schema and the exact `mutate_agent` operations.
2. **`discover_agent_assets(projectId, kind)`** — `kind` is `models`, `integrations`, `workflows`, `subagents` or `mcpServers`. For models pass `provider` (and `credentialId` to verify against the account). Take the model from here; never hard-code one.
3. **`create_agent(projectId, name, config?)`** — creates a draft and returns the editor URL. The model id has the form `<provider>/<model>`.
4. **`mutate_agent(agentId, baseConfigHash, operation)`** — **one** operation per call, always with the **latest** `configHash` (from `get_agent` or the previous mutation). Operations: `config.replace`, `config.patch` (JSON Patch), `skill.upsert` / `skill.delete`, `task.upsert` / `task.delete` (cron schedule), `customTool.upsert` / `customTool.delete`. A stale hash is rejected; re-read and retry.
5. **`validate_agent(agentId)`** — checks the draft, sidecar references and the credentials the user can access.
6. **`call_agent(agentId, request)`** — tests the draft through the Preview chat. It uses **real tools and credentials**, so side effects are possible. Start with `{ "type": "message", "message": "...", "sessionId"? }`. A returned approval is for the **human** to decide; resume with `{ "type": "approval", "approved": true|false, "continuation": {...} }` only after they answer.
7. **`publish_agent`** — **only after the user explicitly asks or confirms**; finishing a build is not approval. It activates tasks and integrations. `unpublish_agent`, `revert_agent`, `list_agent_versions`, `delete_agent`, `update_agent_integration` and `verify_agent_mcp_server` cover the rest of the lifecycle.

`search_agents` lists agents; the tools only operate on agents with **Available in MCP** on. The same agents are reachable through the external server's `n8n_manage_agents`; the vendored **n8n-agents** skill covers designing them and the AI Agent node.

---

## Native vs External MCP

| Aspect | Native MCP | External MCP (`n8n-mcp`) |
|--------|-----------|--------------------------|
| **Workflow input** | TypeScript SDK code | JSON objects (`nodes[]`, `connections{}`) |
| **Creation flow** | Reference → validate code → create | Build JSON → create directly |
| **Editing** | Atomic operation list (`update_workflow`) | Diff operations (`n8n_update_partial_workflow`) or full replacement |
| **Node discovery** | IDs plus discriminators, TypeScript types | Keyword search, docs, property search |
| **Credentials** | `list_credentials` (read-only), `explore_node_resources` | Full CRUD, schema discovery, usage scan |
| **Versions** | History, diff, restore (n8n's own) | `n8n_workflow_versions` (local snapshots, or `source: "native"`) |
| **Data tables** | Rows, tables and columns | `n8n_manage_datatable` |
| **Agents** | 15 tools | `n8n_manage_agents` |
| **Templates, security audit** | Not available | Templates, `n8n_audit_instance`, `n8n_autofix_workflow` |
| **Execution** | `execute_workflow`, `test_workflow` | `n8n_test_workflow` (HTTP trigger, or via the instance MCP), `n8n_executions` |

Use **native** for SDK-built workflows, type-safe configuration, publish lifecycle and Agents. Use **external** for templates, security audit, credential management, autofix and quick JSON-level edits. The two run side by side; a workflow created through one is editable through the other.

---

## Example: full workflow creation

A webhook that processes data and sends a Slack message.

1. `get_workflow_sdk_reference(section: "patterns")` — basic structure, how to define and connect nodes.
2. `get_workflow_best_practices(technique: "notification")`.
3. `search_nodes(queries: ["webhook", "slack", "set", "if"])` — returns `n8n-nodes-base.webhook`, `n8n-nodes-base.slack` (resource `message`, operation `send`), `n8n-nodes-base.set`, `n8n-nodes-base.if`.
4. `get_node_types(nodeIds: [{ "nodeId": "n8n-nodes-base.webhook" }, { "nodeId": "n8n-nodes-base.slack", "resource": "message", "operation": "send" }, { "nodeId": "n8n-nodes-base.set" }, { "nodeId": "n8n-nodes-base.if" }])`.
5. `list_credentials(type: "slackApi")` — use the real credential, or `newCredential('Slack Bot')` in the code when none exists yet.
6. **Write the code** from the SDK patterns and the exact parameter names. **Follow every `@builderHint`** in the type definitions — for example the recommended model default for an LLM node. The hint reflects current best practice, so take model names from it, not from memory.
7. `validate_workflow(code: "<your SDK code>")` — fix and repeat until clean.
8. `create_workflow_from_code(code, name, description, versionName)` — report `targetProject` / `targetFolder`.
9. `prepare_workflow_pin_data` → `test_workflow`, or `execute_workflow(executionMode: "manual", ...)` — then `get_workflow_execution` for the result.
10. `publish_workflow(workflowId)` — only when the user wants it live.

---

## Best practices

### Always follow the sequence

1. **`get_workflow_sdk_reference` first** — the SDK has specific patterns; skipping it produces invalid code.
2. **`get_node_types` before writing code** — wrong parameter names are the main cause of validation failures.
3. **`validate_workflow` before creating** — it catches missing imports, invalid parameter names, type mismatches and missing required fields.

### Workflow naming and placement

- Descriptive names ("Webhook to Slack Alert"), and always a `description`.
- Always a `versionName` on `create_workflow_from_code` and `update_workflow`.
- Resolve a named project or folder with `search_projects` / `search_folders`; pass `projectId` (and `folderId`) explicitly.

### Execution safety

- `executionMode: "manual"` for all testing; `"production"` only for a verified, published workflow the user wants run.
- `execute_workflow` returns immediately — check the result with `get_workflow_execution`.
- `test_workflow` and `execute_workflow` both run real nodes; ask before testing anything that writes.

### Updating workflows

- Edit with `update_workflow` operations; each call is atomic, so a failed operation leaves the workflow untouched.
- One changed node: `updateNodeParameters` or `setNodeParameter`. A whole new design: create a new workflow.
- Before a risky edit note the current version (`get_workflow_history`) so `restore_workflow_version` can undo it.

### IF / Switch node metadata

Filter-based nodes (IF v2.2+, Switch v3.2+) require a `conditions.options` metadata object — without it, the workflow saves via native MCP but fails when edited via external MCP or the n8n UI. Always include it:

```javascript
const checkCondition = ifElse({
  version: 2.3,
  config: {
    name: 'Is Active?',
    parameters: {
      conditions: {
        options: { version: 2, leftValue: '', caseSensitive: true, typeValidation: 'strict' },
        conditions: [
          {
            leftValue: expr('={{ $json.status }}'),
            operator: { type: 'string', operation: 'equals' },
            rightValue: 'active'
          }
        ]
      }
    }
  }
});
```

For unary operators (`empty`, `notEmpty`, `true`, `false`), add `singleValue: true` to the operator object and omit `rightValue`.

### Error handling

- Read `validate_workflow` errors carefully — they include line numbers. Common causes: wrong import path, missing discriminator in the node config, incorrect parameter name.
- If stuck, call `get_workflow_sdk_reference(section: "rules")` and re-run `get_node_types` — you may need different discriminators.
- A refused call on a workflow that exists usually means its **Available in MCP** switch is off (or the workflow is not published with an eligible trigger); ask the user to fix that rather than working around it.
