AgentSkillsCN

04 Mcp Tools Expert

04 Mcp工具专家

SKILL.md

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

ToolPurposeWhen to Use
tools_documentationGet docs for any MCP toolSTART HERE - understand available capabilities
n8n_health_checkCheck n8n instance healthBefore operations, troubleshooting

Node Discovery

ToolPurposeWhen to Use
search_nodesFull-text search across 1,084 nodes"Find slack nodes", explore options
get_nodeUnified node info with multiple modesGet schema, docs, properties, versions

get_node Modes:

javascript
// 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:

LevelTokensUse Case
minimal~200Basic metadata only
standard~1-2KEssential properties (recommended)
full~3-8KComplete information

Validation

ToolPurposeWhen to Use
validate_nodeSingle node validationBefore building workflow
validate_workflowComplete workflow validationBefore deployment
n8n_validate_workflowValidate workflow by IDExisting workflows
n8n_autofix_workflowAuto-fix common issuesQuick fixes

Validation Profiles:

ProfileStrictnessUse Case
minimalLowestQuick check, required fields only
runtimeMediumPre-execution validation
ai-friendlyMedium-HighAI-generated workflows
strictHighestProduction deployment

Templates (2,709+ Available)

ToolPurposeWhen to Use
search_templatesMulti-mode template searchFind workflow examples
get_templateGet complete workflow JSONImport/adapt templates
n8n_deploy_templateDeploy template to n8n instanceQuick deployment

search_templates Modes:

javascript
// 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)

ToolPurposeWhen to Use
n8n_create_workflowCreate new workflowBuilding from scratch
n8n_get_workflowGet workflow by IDInspect existing
n8n_update_partial_workflowIncremental diff updatesAdd/remove nodes (efficient)
n8n_update_full_workflowComplete replacementMajor changes
n8n_list_workflowsList all workflowsOverview
n8n_delete_workflowDelete workflowCleanup
n8n_workflow_versionsVersion history/rollbackRecovery

n8n_update_partial_workflow Operations:

javascript
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:

javascript
// 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

ToolPurposeWhen to Use
n8n_test_workflowTrigger workflow executionTest webhook/chat/form triggers
n8n_executionsExecution history managementDebug/monitor

Part 2: Building MCP Servers with n8n

n8n MCP Nodes Overview

NodeTypePurpose
MCP Server TriggerTriggerExpose n8n tools as MCP endpoint
MCP Client ToolAI ToolConnect AI agent to external MCP server
MCP ClientActionStandalone MCP client (non-AI context)
Call n8n Sub-Workflow ToolAI ToolExpose workflows as callable tools

MCP Server Trigger Node

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

Configuration:

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

Authentication Options:

MethodValueDescription
NonenoneNo authentication (testing only)
Bearer AuthbearerAuthAuthorization: Bearer {token} header
Header AuthheaderAuthCustom header name/value

URL Types:

URLPurpose
Test URLDevelopment/debugging - data visible in workflow
Production URLLive usage - workflow must be active

Architecture Pattern:

code
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):

TransportValueStatusUse Case
HTTP StreamablehttpStreamableRecommendedAll new integrations
Server Sent EventssseDeprecatedLegacy compatibility only

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+):

json
{
  "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+):

MethodValueDescription
NonenoneNo authentication
Bearer AuthbearerAuthBearer token
Header AuthheaderAuthSingle custom header
MCP OAuth2mcpOAuth2ApiOAuth2 flow
Multiple HeadersmultipleHeadersAuthMultiple custom headers

Tool Filtering:

javascript
// 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:

json
{
  "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:

ModeUse Case
manualMap parameters individually via UI
jsonProvide parameters as JSON object

Call n8n Sub-Workflow Tool

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

Configuration:

json
{
  "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:

javascript
// 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.

code
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.

code
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.

code
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.

code
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):

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

For Workflow JSON:

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

For AI/LangChain Nodes:

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

Node Type Patterns

PackageMCP Tool FormatWorkflow JSON Format
Core nodesnodes-base.httpRequestn8n-nodes-base.httpRequest
AI nodesnodes-langchain.agent@n8n/n8n-nodes-langchain.agent
Communityn8n-nodes-mcp.Mcpn8n-nodes-mcp.Mcp

Part 5: Common Tool Sequences

Build New Workflow

code
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

code
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

code
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):

json
{
  "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:

json
{
  "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:

bash
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

ErrorCauseFix
Node type not foundWrong formatUse nodes-base.X not n8n-nodes-base.X
Workflow validation failedInvalid configRun n8n_autofix_workflow
Cannot connect to n8nAPI issueRun n8n_health_check
Expected string, received objectWrong addConnection syntaxUse four separate string parameters
Source node not foundCombined string formatDon't use "node-1:main:0" format
SSE connection droppedDeprecated transportSwitch to HTTP Streamable

Validation Error Patterns

Missing Required Field:

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

Fix: Add the required parameter.

Invalid Expression:

json
{
  "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)

FeatureHTTP StreamableSSE (Deprecated)
EndpointsSingle /mcpDual (POST + SSE)
Auth HeadersSecure in headersOften in query string
ConnectionStateless or statefulAlways stateful
ReliabilityBetterConnection drops
Future SupportFullLegacy only

MCP Node Quick Reference

NodeType FormatKey Parameter
MCP Server Trigger@n8n/n8n-nodes-langchain.mcpTriggerpath, authentication
MCP Client Tool@n8n/n8n-nodes-langchain.mcpClientToolendpointUrl, serverTransport
MCP Client@n8n/n8n-nodes-langchain.mcpClientendpointUrl, tool
Sub-Workflow Tool@n8n/n8n-nodes-langchain.toolWorkflowworkflowId, workflowInputs

Sources & Further Reading


Related Skills

SkillWhen to Use
01-workflow-architectStrategic planning before building
02-workflow-patternsChoose appropriate workflow pattern
03-node-configurationConfigure specific nodes
05-code-javascriptCode node logic for tools
08-validation-expertDeep-dive on validation errors