04 MCP Tools Expert

n8n MCP Tools Expert

Master the n8n-mcp server tools AND build MCP servers/clients with n8n nodes

Overview

This skill covers two interconnected domains:

1. n8n-mcp MCP Server - External tools for AI assistants to build n8n workflows (20+ tools)
2. n8n MCP Nodes - Native n8n nodes for creating MCP servers and consuming MCP tools

Part 1: n8n-mcp MCP Server Tools

Tool Categories (20+ Tools)

System & Documentation

Node Discovery

get_node Modes:

// Info mode (default) - Get node schema
get_node({ nodeType: "nodes-base.httpRequest", detail: "standard" })

// Docs mode - Human-readable markdown
get_node({ nodeType: "nodes-base.slack", mode: "docs" })

// Search properties - Find specific fields
get_node({ nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth" })

// Version info
get_node({ nodeType: "nodes-base.httpRequest", mode: "versions" })

Detail Levels:

Validation

Validation Profiles:

Templates (2,709+ Available)

search_templates Modes:

// Keyword search (default)
search_templates({ query: "slack notification" })

// By nodes used
search_templates({ searchMode: "by_nodes", nodeTypes: ["n8n-nodes-base.slack"] })

// By task type
search_templates({ searchMode: "by_task", task: "webhook_processing" })

// By metadata
search_templates({
  searchMode: "by_metadata",
  complexity: "simple",
  requiredService: "openai"
})

Available Tasks:

• ai_automation, data_sync, webhook_processing
• email_automation, slack_integration, api_integration
• data_transformation, file_processing, scheduling, database_operations

Workflow Management (Requires API Config)

n8n_update_partial_workflow Operations:

n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [
    { type: "addNode", node: {...} },
    { type: "removeNode", nodeId: "node-1" },
    { type: "updateNode", nodeId: "node-1", changes: {...} },
    { type: "addConnection", source: "node-1", target: "node-2", sourcePort: "main", targetPort: "main" },
    { type: "removeConnection", source: "node-1", target: "node-2", sourcePort: "main", targetPort: "main" },
    { type: "cleanStaleConnections" },
    { type: "activateWorkflow" },
    { type: "deactivateWorkflow" }
  ]
})

IF Node Multi-Output Routing:

// Route to TRUE branch
{ type: "addConnection", source: "If Node", target: "Success", sourcePort: "main", targetPort: "main", branch: "true" }

// Route to FALSE branch
{ type: "addConnection", source: "If Node", target: "Failure", sourcePort: "main", targetPort: "main", branch: "false" }

Execution Management

Part 2: Building MCP Servers with n8n

n8n MCP Nodes Overview

MCP Server Trigger Node

Purpose: Turn n8n into an MCP server that AI clients can connect to.

Configuration:

{
  "type": "@n8n/n8n-nodes-langchain.mcpTrigger",
  "typeVersion": 2,
  "parameters": {
    "path": "my-mcp-server",
    "authentication": "bearerAuth"
  }
}

Authentication Options:

URL Types:

Architecture Pattern:

MCP Server Trigger
    |
    +-- Google Calendar Tool (Get Events)
    +-- Google Calendar Tool (Create Event)
    +-- Call n8n Sub-Workflow Tool (Custom Logic)
    +-- HTTP Request Tool (External API)

MCP Client Tool Node (For AI Agents)

Purpose: Connect your n8n AI Agent to external MCP servers.

Transport Types (CRITICAL):

Why HTTP Streamable is Preferred:

• Single endpoint architecture (vs dual-endpoint SSE)
• Better connection reliability
• Secure header authentication (SSE required query string tokens)
• Standard HTTP middleware compatibility
• Future support for resumable operations

Configuration (v1.2+):

{
  "type": "@n8n/n8n-nodes-langchain.mcpClientTool",
  "typeVersion": 1.2,
  "parameters": {
    "endpointUrl": "https://mcp-server.example.com/mcp",
    "serverTransport": "httpStreamable",
    "authentication": "bearerAuth",
    "include": "all",
    "options": {
      "timeout": 60000
    }
  }
}

Authentication Options (v1.2+):

Tool Filtering:

// Include all tools
{ include: "all" }

// Include only selected tools
{ include: "selected", includeTools: ["tool1", "tool2"] }

// Include all except specific tools
{ include: "except", excludeTools: ["tool3"] }

MCP Client Node (Standalone)

Purpose: Call MCP server tools directly in workflows (without AI Agent context).

Configuration:

{
  "type": "@n8n/n8n-nodes-langchain.mcpClient",
  "typeVersion": 1,
  "parameters": {
    "endpointUrl": "https://mcp-server.example.com/mcp",
    "serverTransport": "httpStreamable",
    "authentication": "bearerAuth",
    "tool": { "mode": "list", "value": "get_weather" },
    "inputMode": "manual",
    "parameters": {
      "mappingMode": "defineBelow",
      "value": { "city": "London" }
    }
  }
}

Input Modes:

Call n8n Sub-Workflow Tool

Purpose: Expose any n8n workflow as a callable tool for AI Agents or MCP Server.

Configuration:

{
  "type": "@n8n/n8n-nodes-langchain.toolWorkflow",
  "typeVersion": 2.2,
  "parameters": {
    "name": "get_customer_data",
    "description": "Retrieves customer information by ID or email",
    "source": "database",
    "workflowId": { "__rl": true, "mode": "list", "value": "workflow-id" },
    "workflowInputs": {
      "mappingMode": "defineBelow",
      "value": {
        "customer_id": "={{ $fromAI(\"customer_id\", \"The customer ID to lookup\", \"string\") }}"
      }
    }
  }
}

$fromAI() Function:

// Syntax: $fromAI(paramName, description, type)
$fromAI("customer_id", "The customer ID to lookup", "string")
$fromAI("date_range", "Date range in YYYY-MM-DD format", "string")
$fromAI("include_details", "Whether to include full details", "boolean")

Part 3: Building MCP Servers - Complete Patterns

Pattern 1: API MCP Server

Use Case: Expose any API as MCP tools for AI agents.

MCP Server Trigger (/api-mcp)
    |
    +-- HTTP Request Tool (Search Employees)
    |       - toolDescription: "Search employees by name or department"
    |       - url: https://api.example.com/employees/search
    |
    +-- HTTP Request Tool (Get Employee)
    |       - toolDescription: "Get employee details by ID"
    |       - url: https://api.example.com/employees/{{ $fromAI("id") }}
    |
    +-- HTTP Request Tool (Update Employee)
            - toolDescription: "Update employee information"
            - method: PATCH
            - url: https://api.example.com/employees/{{ $fromAI("id") }}

Pattern 2: Filesystem MCP Server (Self-Hosted Only)

Use Case: Allow AI to manage files on server.

MCP Server Trigger (/fs-mcp)
    |
    +-- Execute Command Tool (List Directories)
    |       - command: ls -la {{ $fromAI("path") }}
    |
    +-- Execute Command Tool (Search Files)
    |       - command: find {{ $fromAI("path") }} -name "{{ $fromAI("pattern") }}"
    |
    +-- Call n8n Sub-Workflow Tool (Read File)
    |       - Sub-workflow with Read Binary File node
    |
    +-- Call n8n Sub-Workflow Tool (Write File)
            - Sub-workflow with Write Binary File node

Security Note: Never allow raw command execution - parameterize inputs only.

Pattern 3: RAG + Search MCP Server

Use Case: AI agent with knowledge base and web search.

MCP Server Trigger (/rag-mcp)
    |
    +-- Call n8n Sub-Workflow Tool (Query Knowledge Base)
    |       - Vector store similarity search
    |       - Return relevant documents
    |
    +-- Call n8n Sub-Workflow Tool (Web Search)
    |       - External search API integration
    |       - Return current information
    |
    +-- Call n8n Sub-Workflow Tool (Add to Knowledge Base)
            - Embed and store new documents

Pattern 4: n8n Workflows MCP Server

Use Case: Allow AI to discover and execute existing n8n workflows.

MCP Server Trigger (/workflows-mcp)
    |
    +-- Call n8n Sub-Workflow Tool (List Available Workflows)
    |       - Query Redis/database for registered workflows
    |       - Return workflow names and descriptions
    |
    +-- Call n8n Sub-Workflow Tool (Execute Workflow)
    |       - Trigger sub-workflow by ID
    |       - Pass parameters dynamically
    |
    +-- Call n8n Sub-Workflow Tool (Register Workflow)
            - Add workflow to available list

Part 4: Node Type Formats

CRITICAL: Correct Format by Context

For MCP Tools (search_nodes, get_node):

nodes-base.slack          ✓ Correct
n8n-nodes-base.slack      ✗ Wrong

For Workflow JSON:

{
  "type": "n8n-nodes-base.slack",     // Full prefix required
  "typeVersion": 2
}

For AI/LangChain Nodes:

{
  "type": "@n8n/n8n-nodes-langchain.agent",  // @n8n prefix
  "typeVersion": 1.7
}

Node Type Patterns

Part 5: Common Tool Sequences

Build New Workflow

1. tools_documentation()              // Understand capabilities
2. search_templates({ query: "..." }) // Find similar workflows
3. search_nodes({ query: "..." })     // Find needed nodes
4. get_node({ nodeType, includeExamples: true })  // Get configurations
5. validate_node({ config, mode: "minimal" })     // Quick validation
6. n8n_create_workflow({ ... })       // Create workflow
7. validate_workflow({ ... })         // Full validation
8. n8n_autofix_workflow({ id })       // Fix if needed

Debug Existing Workflow

1. n8n_get_workflow({ id, mode: "full" })  // Get workflow details
2. n8n_validate_workflow({ id })           // Check for issues
3. n8n_executions({ action: "list", workflowId: id })  // View history
4. n8n_autofix_workflow({ id })            // Apply fixes

Deploy from Template

1. search_templates({ searchMode: "by_task", task: "webhook_processing" })
2. get_template({ templateId, mode: "full" })
3. n8n_deploy_template({ templateId, autoFix: true })
4. n8n_validate_workflow({ id })

Part 6: Environment Configuration

n8n-mcp Server Setup

For Claude Desktop (npx):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true",
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

For Docker:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "N8N_API_URL=http://host.docker.internal:5678",
        "-e", "N8N_API_KEY=your-api-key",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

n8n Instance Requirements

For Community Nodes as AI Tools:

N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true

For MCP Server Trigger (Queue Mode):

• Single webhook replica: Works normally
• Multiple replicas: Route all /mcp* to dedicated replica

Part 7: Error Handling

Common Errors and Fixes

Validation Error Patterns

Missing Required Field:

{
  "valid": false,
  "errors": [{ "path": "parameters.url", "message": "Required field missing" }]
}

Fix: Add the required parameter.

Invalid Expression:

{
  "valid": false,
  "errors": [{ "path": "parameters.value", "message": "Invalid expression syntax" }]
}

Fix: Check {{ }} syntax, use n8n_autofix_workflow.

Part 8: Best Practices

MCP Server Design

1. Authenticate production servers - Always use Bearer or Header auth
2. Parameterize inputs - Never allow raw command injection
3. Clear tool descriptions - Help AI understand when/how to use each tool
4. Audit logging - Log all operations for sensitive data access
5. Use HTTP Streamable - SSE is deprecated (as of MCP spec 2025-03-26)

MCP Client Usage

1. Prefer HTTP Streamable over SSE for all new integrations
2. Set appropriate timeouts - Default 60000ms, increase for slow operations
3. Filter tools - Only expose needed tools to reduce token usage
4. Handle connection drops - HTTP Streamable has better reliability

n8n-mcp Tool Usage

1. Start with tools_documentation() - Understand available capabilities
2. Use includeExamples - Get real-world configurations
3. Validate incrementally - minimal during dev, strict for production
4. Batch operations - Use single n8n_update_partial_workflow with multiple ops
5. Check n8n_health_check - Verify connectivity before operations

Quick Reference

Transport Comparison (MCP Spec 2025-03-26)

MCP Node Quick Reference

Sources & Further Reading

• MCP Server Trigger Documentation
• MCP Client Tool Documentation
• n8n MCP Integration Guide
• n8n-mcp GitHub Repository
• MCP Specification - Transports
• Why MCP Deprecated SSE
• MCP HTTP Streamable Security
• Build FileSystem MCP Server Template
• Build Custom API MCP Server Template
• Build MCP Server with Google Calendar

Related Skills