How to Manage IF Node Multi-Output Routing Using the `branch` Parameter

Use the branch parameter with string values "true" or "false" when calling n8n_update_partial_workflow to route workflow connections to the IF node's TRUE (output 0) or FALSE (output 1) branches without manually calculating array indices.

The czlonkowski/n8n-mcp repository implements a Model Context Protocol (MCP) server that exposes n8n workflow management tools. When programmatically editing workflows containing IF nodes—which expose two distinct output ports for conditional execution paths—the branch smart parameter abstracts the low-level sourceIndex wiring required by the underlying n8n API.

Understanding IF Node Output Ports

The IF node (n8n-nodes-base.if) in n8n exposes exactly two output ports that correspond to conditional evaluation results:

• Output 0 (main[0]): The TRUE branch, executed when the node's condition evaluates to true
• Output 1 (main[1]): The FALSE branch, executed when the node's condition evaluates to false

When using the MCP partial-update API to modify workflows, you can address these ports using either the low-level sourceIndex field (0 or 1) or the higher-level branch smart parameter. According to the source code in src/services/workflow-diff-engine.ts, the system recommends using branch for improved clarity and safety.

How the branch Parameter Resolves Connections

All connection-related operations—including addConnection and rewireConnection—are processed through the WorkflowDiffEngine class, which normalizes smart parameters into explicit API fields.

The Resolution Engine

The private resolveSmartParameters method in src/services/workflow-diff-engine.ts handles the translation:

private resolveSmartParameters(
  workflow: Workflow,
  operation: AddConnectionOperation | RewireConnectionOperation
): { sourceOutput: string; sourceIndex: number } {
  // Normalization logic for explicit fields first...
}

This method checks for the presence of smart parameters and resolves them before executing the workflow diff operation.

Branch Mapping Logic

When you provide a branch parameter without specifying sourceIndex, the engine performs semantic mapping specific to IF nodes:

// src/services/workflow-diff-engine.ts (lines 777-784)
if (operation.branch !== undefined && operation.sourceIndex === undefined) {
  if (sourceNode?.type === 'n8n-nodes-base.if') {
    sourceIndex = operation.branch === 'true' ? 0 : 1;
    // sourceOutput remains 'main'
  }
}

The mapping follows this protocol:

• branch: "true" resolves to sourceIndex: 0 (TRUE branch)
• branch: "false" resolves to sourceIndex: 1 (FALSE branch)

The sourceOutput field remains fixed as "main" for both branches.

Validation Warnings

The system detects when users manually specify sourceIndex for IF nodes and issues a warning recommending the branch parameter instead. Implemented in src/services/workflow-diff-engine.ts (lines 94-101):

if (sourceNode && operation.sourceIndex !== undefined && operation.branch === undefined) {
  if (sourceNode.type === 'n8n-nodes-base.if') {
    this.warnings.push({
      message: `Connection to If node "${operation.source}" uses sourceIndex=${operation.sourceIndex}. ` +
               `Consider using branch="true" or branch="false" for better clarity. ` +
               `If node outputs: main[0]=TRUE branch, main[1]=FALSE branch.`
    });
  }
}

This validation ensures developers receive immediate feedback when bypassing the semantic abstraction layer.

Practical Implementation Examples

The following examples demonstrate how to use the branch parameter with the n8n_update_partial_workflow MCP tool. These examples reference the tool documentation in src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts.

Adding Connections to Specific Branches

Connect a success handler to the TRUE branch:

await n8n_update_partial_workflow({
  id: "wf_123",
  operations: [
    {
      type: "addConnection",
      source: "IF",
      target: "Success Handler",
      branch: "true"
    }
  ]
});

Connect an error handler to the FALSE branch:

await n8n_update_partial_workflow({
  id: "wf_123",
  operations: [
    {
      type: "addConnection",
      source: "IF",
      target: "Error Handler",
      branch: "false"
    }
  ]
});

Rewiring Existing Connections

Use the rewireConnection operation with branch to redirect the FALSE branch to a new target:

await n8n_update_partial_workflow({
  id: "wf_123",
  operations: [
    {
      type: "rewireConnection",
      source: "IF",
      from: "Error Handler",
      to: "Fallback Handler",
      branch: "false"
    }
  ]
});

Resolved API Output

Each call above is automatically transformed by resolveSmartParameters into the explicit JSON structure required by the n8n API:

{
  "type": "addConnection",
  "source": "IF",
  "target": "Success Handler",
  "sourceOutput": "main",
  "sourceIndex": 0
}

For the false branch, the system generates sourceIndex: 1.

Summary

• The branch parameter in czlonkowski/n8n-mcp accepts "true" or "false" strings to route IF node connections semantically.
• Implementation resides in src/services/workflow-diff-engine.ts, specifically within the resolveSmartParameters method.
• Mapping: "true" resolves to output index 0, while "false" resolves to index 1.
• Validation: The system warns when using raw sourceIndex values for IF nodes, encouraging adoption of the branch parameter.
• Operations: Works with both addConnection and rewireConnection operation types defined in src/types/workflow-diff.ts.

Frequently Asked Questions

What values does the branch parameter accept?

The branch parameter accepts the string literals "true" and "false" when routing from IF nodes (n8n-nodes-base.if). These values map to the node's output indices 0 and 1 respectively, as implemented in the resolveSmartParameters method.

Can I use branch and sourceIndex in the same operation?

No. The resolution logic in src/services/workflow-diff-engine.ts only processes the branch parameter when sourceIndex is undefined. If you provide both, the system prioritizes the explicit sourceIndex value and ignores the branch parameter.

Does the branch parameter work with node types other than IF?

The current implementation specifically checks for sourceNode.type === 'n8n-nodes-base.if'. While the codebase mentions a case parameter for handling Switch nodes, the branch parameter is designed exclusively for IF node conditional routing according to the source code analysis.

Where can I find unit tests for this functionality?

The test suite in tests/unit/services/workflow-diff-engine.test.ts contains unit tests verifying the correct handling of the branch parameter for IF nodes, ensuring proper resolution to sourceIndex values and validation warning generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}