N8n

n8n — operate a live instance over its REST API and MCP

You already have a workflow design — the trigger→steps→error shape and the importable JSON, which is automation-flows' job and this skill does not re-teach it. This skill is the operate half: push that JSON into a running n8n, validate it, test it, flip it live, watch its executions, and tear it down safely — all without touching the UI. n8n has the richest programmatic story of the no-code platforms: a first-party REST API plus a mature MCP server, both hitting the same instance.

Connect first — REST API vs MCP

Two ways to drive the same instance. Pick by who is at the wheel.

Version reality (verify at author time — n8n moves fast):

• API base is {host}/api/v1. Self-host ships interactive Swagger at /api/v1/docs; cloud does not — on cloud, work from the docs.
• POST /workflows/{id}/execute (run-by-id) is recent (n8n PR #20234). Older instances lack it — there, the only programmatic run is POSTing to a Webhook node's URL.

.env

# host root only — you append /api/v1 for REST; n8n-mcp reads it whole
N8N_API_URL=https://your-instance.app.n8n.cloud   # or N8N_HOST for self-host, e.g. http://localhost:5678
N8N_API_KEY=n8n_api_...                            # Settings → n8n API → Create an API key

Never inline the key in a command that gets logged, and never put a node credential (Slack token, etc.) in the workflow payload — reference it by the n8n credential store id/name (see automation-flows' JSON schema). Full key-creation + self-host vs cloud + MCP install: references/auth-and-selfhost.md.

The payload you POST

The create/update body is exactly the automation-flows workflow JSON. Required top-level keys on create: name, nodes, connections, settings. Build it per ../automation-flows/references/n8n-workflow-json.md — non-empty nodes with one trigger, a wired connections map, settings.errorWorkflow, credentials referenced by store (never inlined).

Node/expression essentials (pointer, not a tutorial): node type is namespaced (n8n-nodes-base.webhook), typeVersion must match a node version installed on the target instance or activation/execution fails; field values use expressions like ={{ $json.email }} or ={{ $node["Webhook"].json.body.id }}. If you are hand-authoring nodes, let n8n-mcp's node-knowledge tools (search_nodes, get_node_essentials, validate_node_operation) fill in the exact property shapes rather than guessing — that is the single biggest reason to drive via MCP.

Dynamic lifecycle

create → validate → test → activate → manage → delete. A concrete sketch per step, curl and n8n-mcp side by side; every endpoint with pagination and scopes is in references/rest-api-cheatsheet.md.

1. Validate (do this BEFORE create)

REST has no validation endpoint — n8n only tells you at create/activate time. MCP does, so validate first when it is available:

n8n_validate_workflow   { "workflow": { …the full JSON… } }
n8n_autofix_workflow    { "workflow": { … } }   # repairs common structural errors, returns fixed JSON

2. Create

curl -sS -X POST "$N8N_API_URL/api/v1/workflows" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" -H "Content-Type: application/json" \
  -d @workflow.json          # body = { name, nodes, connections, settings }
# → returns the created workflow WITH its "id" — capture it for every step below

n8n_create_workflow     { "name": "...", "nodes": [ … ], "connections": { … }, "settings": { … } }

3. Test / dry-run

• No input needed → run by id (recent instances only): POST /workflows/{id}/execute.
• Needs input → the execute endpoint accepts none. Make the trigger a Webhook node and POST to its URL (test URL /webhook-test/<path> while "Listen for test event" is armed; production /webhook/<path> once active).

curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/execute" -H "X-N8N-API-KEY: $N8N_API_KEY"
curl -sS -X POST "$N8N_API_URL/webhook-test/my-path" -H "Content-Type: application/json" -d '{"foo":"bar"}'

n8n_test_workflow       { "id": "$ID" }

4. Activate — the step people miss

active (and tags) in the create/update body are read-only and silently ignored. Setting "active": true does nothing, which is why the workflow you just created never fires. You MUST call the separate endpoint:

curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/activate"   -H "X-N8N-API-KEY: $N8N_API_KEY"
curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/deactivate" -H "X-N8N-API-KEY: $N8N_API_KEY"

n8n-mcp deliberately does not expose activate/deactivate as tools (activation has live side effects). Check the current tool list; if absent, call the REST /activate endpoint as above.