n8n-mcp addConnection Syntax: Complete Guide to Workflow Connection Operations

The addConnection operation requires type: 'addConnection' alongside required string properties source and target to create connections between nodes in n8n workflows via the MCP diff engine.

The n8n-mcp repository provides a Model Context Protocol implementation for programmatic n8n workflow management. Understanding the correct n8n-mcp addConnection syntax is essential when constructing diff operations for the n8n_update_partial_workflow tool to modify workflow topology.

Core Structure and Required Parameters

The addConnection operation is defined in src/types/workflow-diff.ts within the AddConnectionOperation interface (lines 59-70). According to the czlonkowski/n8n-mcp source code, the operation requires specific properties to establish valid node connections.

Required properties:

• type — Literal string 'addConnection' that acts as the operation discriminator
• source — String containing the name or ID of the emitting node
• target — String containing the name or ID of the receiving node

Optional properties with defaults:

• sourceOutput — String specifying the output port (default: 'main')
• targetInput — String specifying the input port (default: 'main')
• sourceIndex — Number for multi-output nodes (default: 0)
• targetIndex — Number for multi-input nodes (default: 0)

Smart parameters for conditional logic:

• branch — 'true' or 'false' for IF nodes (maps to sourceIndex values 0 or 1)
• case — Number for Switch node cases (maps to specific sourceIndex values)

Validation Rules and Error Handling

The validation logic in src/services/workflow-diff-engine.ts (lines 94-108) enforces strict syntax requirements that prevent malformed operations from modifying workflows.

Critical validation constraints:

• Legacy key rejection: The engine only accepts source and target keys; legacy identifiers sourceNodeId or targetNodeId trigger errors
• Mandatory fields: Both source and target must be present, or the engine returns "Missing required parameter" messages
• Node existence checks: Operations fail with helpful error messages listing available node names if referenced nodes do not exist
• Duplicate prevention: Attempting to create an existing connection results in "Connection already exists" errors

Practical Code Examples

Basic Connection Between Nodes

Use the minimal required syntax when connecting standard nodes with default ports:

{
  type: "addConnection",
  source: "Webhook",
  target: "HTTP Request"
}

Specifying Non-Default Ports

Explicitly define sourceOutput and targetInput when nodes use specialized ports:

{
  type: "addConnection",
  source: "IF",
  target: "Success Handler",
  sourceOutput: "true",
  targetInput: "main"
}

IF Node Branch Connections

Use the branch smart parameter to automatically map to the correct sourceIndex for conditional logic:

{
  type: "addConnection",
  source: "IF",
  target: "Error Handler",
  branch: "false"  // Automatically maps to sourceIndex = 1
}

Switch Node Case Routing

Specify case to connect specific output cases from Switch nodes:

{
  type: "addConnection",
  source: "Switch",
  target: "Handler B",
  case: 1  // Maps to sourceIndex = 1 (second case)
}

AI-Specific Channel Connections

Reference specialized output channels like ai_languageModel for AI agent workflows:

{
  type: "addConnection",
  source: "OpenAI Chat Model",
  target: "AI Agent",
  sourceOutput: "ai_languageModel"
}

Batch Operations with Mixed Diff Types

Combine addNode and addConnection operations in a single n8n_update_partial_workflow request:

{
  id: "my-workflow-id",
  operations: [
    {
      type: "addNode",
      node: { name: "Filter", type: "n8n-nodes-base.filter", position: [400, 300], parameters: {} }
    },
    {
      type: "addNode",
      node: { name: "Transform", type: "n8n-nodes-base.set", position: [600, 300], parameters: {} }
    },
    {
      type: "addConnection",
      source: "Filter",
      target: "Transform"
    }
  ]
}

Key Implementation Files

Understanding the source structure helps debug syntax errors and understand the operation lifecycle:

• src/types/workflow-diff.ts — Contains the TypeScript AddConnectionOperation interface definition (lines 59-70) that establishes the exact contract for type checking
• src/services/workflow-diff-engine.ts — Implements runtime validation and error messaging (lines 94-108) that enforce the syntax rules at execution time
• src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts — Provides user-facing documentation (lines 42-48) describing operation patterns for the MCP tool interface
• src/mcp/tools-n8n-manager.ts — Registers the tool and adds addConnection to the supported operations list exposed via the MCP API

Summary

• Primary requirement: The addConnection operation must include type: 'addConnection', source, and target properties to validate successfully
• Smart parameters: Use branch for IF nodes and case for Switch nodes instead of manual sourceIndex calculations when possible
• Validation location: Syntax errors originate from src/services/workflow-diff-engine.ts, which enforces node existence and prevents duplicate connections
• Legacy incompatibility: Never use sourceNodeId or targetNodeId; the engine strictly requires source and target as implemented in the czlonkowski/n8n-mcp codebase
• Batch capability: Combine multiple operations including connections within a single operations array in n8n_update_partial_workflow calls

Frequently Asked Questions

What are the minimum required parameters for the addConnection operation?

The operation requires three properties: type set to the literal string 'addConnection', plus source and target strings identifying the nodes to connect. According to the validation logic in src/services/workflow-diff-engine.ts, omitting either node identifier returns a "Missing required parameter" error.

How do I connect the true or false branch of an IF node?

Use the branch property with values 'true' or 'false' rather than calculating sourceIndex manually. The diff engine automatically maps branch: 'true' to sourceIndex: 0 and branch: 'false' to sourceIndex: 1, simplifying conditional workflow construction.

What happens if I use the legacy sourceNodeId parameter name?

The validation engine in src/services/workflow-diff-engine.ts explicitly rejects legacy keys like sourceNodeId or targetNodeId. Only the modern source and target property names are accepted; using deprecated names causes immediate operation failures with clear error messages.

Can I create multiple connections in a single workflow update request?

Yes. The operations array in the n8n_update_partial_workflow tool accepts multiple diff operations, allowing you to batch addConnection requests with addNode or other modifications. The engine processes these atomically, ensuring all operations validate before applying changes to the workflow.

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