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

> Master n8n-mcp addConnection syntax to effortlessly link workflow nodes. Explore the essential type, source, and target properties for seamless operation.

- Repository: [Romuald Członkowski/n8n-mcp](https://github.com/czlonkowski/n8n-mcp)
- Tags: api-reference
- Published: 2026-03-24

---

**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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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:

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

```

### Specifying Non-Default Ports

Explicitly define `sourceOutput` and `targetInput` when nodes use specialized ports:

```typescript
{
  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:

```typescript
{
  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:

```typescript
{
  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:

```typescript
{
  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:

```typescript
{
  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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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.