n8n-node-configuration

n8n Node Configuration

Expert guidance for operation-aware node configuration with property dependencies.

---

Configuration Philosophy

Progressive disclosure: Start minimal, add complexity as needed

Configuration best practices:

• get_node with detail: "standard" is the most used discovery pattern
• 56 seconds average between configuration edits
• Covers 95% of use cases with 1-2K tokens response

Key insight: Most configurations need only standard detail, not full schema!

---

Core Concepts

1. Operation-Aware Configuration

Not all fields are always required - it depends on operation!

Example: Slack node

// For operation='post'
{
  "resource": "message",
  "operation": "post",
  "channel": "#general",  // Required for post
  "text": "Hello!"        // Required for post
}

// For operation='update'
{
  "resource": "message",
  "operation": "update",
  "messageId": "123",     // Required for update (different!)
  "text": "Updated!"      // Required for update
  // channel NOT required for update
}

Key: Resource + operation determine which fields are required!

2. Property Dependencies

Fields appear/disappear based on other field values

Example: HTTP Request node

// When method='GET'
{
  "method": "GET",
  "url": "https://api.example.com"
  // sendBody not shown (GET doesn't have body)
}

// When method='POST'
{
  "method": "POST",
  "url": "https://api.example.com",
  "sendBody": true,       // Now visible!
  "body": {               // Required when sendBody=true
    "contentType": "json",
    "content": {...}
  }
}

Mechanism: displayOptions control field visibility

3. Progressive Discovery

Use the right detail level:

1. get_node({detail: "standard"}) - DEFAULT

   • Quick overview (~1-2K tokens)
   • Required fields + common options
   • Use first - covers 95% of needs

2. get_node({mode: "search_properties", propertyQuery: "..."}) (for finding specific fields)

   • Find properties by name
   • Use when looking for auth, body, headers, etc.

3. get_node({detail: "full"}) (complete schema)

   • All properties (~3-8K tokens)
   • Use only when standard detail is insufficient

---

Configuration Workflow

Standard Process

1. Identify node type and operation.
2. Use get_node (standard detail is default).
3. Configure required fields.
4. Validate configuration.
5. If a field is unclear → get_node({mode: "search_properties"}).
6. Add optional fields as needed.
7. Validate again.
8. Deploy.

Example: Configuring HTTP Request

The validate-driven loop in practice: start minimal (method, url, authentication), then let each validate_node error surface the next required field (sendBody for POST → body when sendBody=true) until valid. Full step-by-step walkthrough in OPERATION_PATTERNS.md.

---

get_node Detail Levels

Standard Detail (DEFAULT - Use This!)

✅ Starting configuration

get_node({
  nodeType: "nodes-base.slack"
});
// detail="standard" is the default

Returns (~1-2K tokens):

• Required fields
• Common options
• Operation list
• Metadata

Use: 95% of configuration needs

Full Detail (Use Sparingly)

✅ When standard isn't enough

get_node({
  nodeType: "nodes-base.slack",
  detail: "full"
});

Returns (~3-8K tokens):

• Complete schema
• All properties
• All nested options

Warning: Large response, use only when standard insufficient

Search Properties Mode

✅ Looking for specific field

get_node({
  nodeType: "nodes-base.httpRequest",
  mode: "search_properties",
  propertyQuery: "auth"
});

Use: Find authentication, headers, body fields, etc.

Decision Tree

1. Starting a new node config → get_node (standard).
2. Standard has what you need → configure with it. Otherwise continue.
3. Looking for a specific field → search_properties mode. Otherwise continue.
4. Still need more → get_node({detail: "full"}).

Dynamic properties: when standard detail marks a property with dynamicOptions: {methodName, methodType, dependsOn}, its real values come from a live loadOptions/listSearch method, not from bundled docs — don't guess an ID for it. Resolve it with n8n_explore_node_resources (needs N8N_MCP_ACCESS_TOKEN, n8n 2.34+) and put the returned value in the config; name is display text only.

All six parameters are required and none are inferred from each other:

n8n_explore_node_resources({
  nodeType: "n8n-nodes-base.googleSheets",  // LONG form
  version: 4.5,                              // the node typeVersion the method belongs to
  methodName: "getSheets",                   // copied verbatim from dynamicOptions
  methodType: "listSearch",                  // "listSearch" for resource locators, "loadOptions" for plain dropdowns
  credentialType: "googleSheetsOAuth2Api",
  credentialId: "c2",                        // from n8n_manage_credentials({action: "list"})
  currentNodeParameters: {                   // whatever dependsOn names, in its real shape
    documentId: {__rl: true, mode: "id", value: "1AbC…"}
  }
})

dependsOn names the parameters the method needs already chosen — pass them in currentNodeParameters, keeping resource-locator values in their {__rl: true, mode, value} shape, or the method returns nothing useful. methodName is case-sensitive and specific to the nodeType + version pair; a mismatch returns OFFICIAL_MCP_ERROR rather than an empty list.

---

Property Dependencies Deep Dive

Fields have displayOptions visibility rules: show/hide blocks where multiple conditions are AND'd and multiple values are OR'd (e.g. body shows when sendBody=true AND method IN (POST, PUT, PATCH)). The three recurring patterns are the boolean toggle (sendBody → body), the operation switch (post vs update show different fields), and type selection (string vs boolean conditions). To find what controls a field, use get_node({mode: "search_properties", propertyQuery: "..."}) or get_node({detail: "full"}) — especially when validation flags a field you don't see.

Mechanism details, all four dependency patterns, complex flows, nested dependencies, and troubleshooting are in DEPENDENCIES.md (quick-reference recap under Quick Reference: displayOptions and Common Dependency Patterns).

---

Common Node Patterns

Pattern 1: Resource/Operation Nodes

Examples: Slack, Google Sheets, Airtable

Structure:

{
  "resource": "<entity>",      // What type of thing
  "operation": "<action>",     // What to do with it
  // ... operation-specific fields
}

How to configure:

1. Choose resource
2. Choose operation
3. Use get_node to see operation-specific requirements
4. Configure required fields

Pattern 2: HTTP-Based Nodes

Examples: HTTP Request, Webhook

Structure:

{
  "method": "<HTTP_METHOD>",
  "url": "<endpoint>",
  "authentication": "<type>",
  // ... method-specific fields
}

Dependencies:

• POST/PUT/PATCH → sendBody available
• sendBody=true → body required
• authentication != "none" → credentials required

Critical: credentials block, node id, typeVersion

• Never set a placeholder credential ID (e.g. "id": "REPLACE_ME") — n8n's UI renders a permanently disabled credential selector for unknown IDs. Omit the credentials block when the real ID is unknown; the user then gets a normal clickable dropdown.
• Node id must be a UUID v4, not a readable slug — the frontend binds forms and the credential component to it.
• Don't hardcode old typeVersion values — verify the current version with get_node (httpRequest is 4.4+).

Pattern 3: Database Nodes

Examples: Postgres, MySQL, MongoDB

Structure:

{
  "operation": "<query|insert|update|delete>",
  // ... operation-specific fields
}

Dependencies:

• operation="executeQuery" → query required
• operation="insert" → table + values required
• operation="update" → table + values + where required

Critical: Write operations may return 0 items

• INSERT, UPDATE, DELETE can produce 0 n8n output items, depending on the node and operation (raw query execution reliably returns 0 result rows; some database nodes return the affected rows)
• Set alwaysOutputData: true on write-operation nodes to keep downstream chains alive
• Downstream nodes should use $('UpstreamNode').all() instead of $input if they need data

Pattern 4: Conditional Logic Nodes

Examples: IF, Switch, Merge

Structure:

{
  "conditions": {
    "<type>": [
      {
        "operation": "<operator>",
        "value1": "...",
        "value2": "..."  // Only for binary operators
      }
    ]
  }
}

Dependencies:

• Binary operators (equals, contains, etc.) → value1 + value2
• Unary operators (isEmpty, isNotEmpty) → value1 only + singleValue: true

---

Operation-Specific Configuration

Required fields shift with resource + operation: Slack post needs channel+text, but update needs messageId+text (channel optional) and channel/create needs name. HTTP GET uses sendQuery+queryParameters; POST needs sendBody+body. IF binary operators (equals) need value1+value2; unary (isEmpty) need only value1 plus auto-added singleValue: true. Concrete minimal configs for each in OPERATION_PATTERNS.md.

---

Handling Conditional Requirements

Some fields are required only under certain conditions: HTTP body is required when sendBody=true AND method IN (POST, PUT, PATCH, DELETE); IF singleValue should be true when the operator is unary (isEmpty, `isNotEm

---

Content truncated.