Model Context Protocol (MCP)
Relevant source files
The following files were used as context for generating this wiki page:
- packages/testing/playwright/tests/e2e/mcp/mcp-service.spec.ts
- packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md
- packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts
- packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts
- packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts
- packages/cli/src/modules/instance-ai/eval/pin-data-generator.ts
The Model Context Protocol (MCP) is a system within n8n that enables external AI models and clients (such as Claude Desktop) to interact with n8n workflows and builder capabilities. It acts as a standardized interface for AI models to search for, retrieve details about, and execute n8n workflows, while also providing tools for AI-driven workflow generation.
Sources: packages/testing/playwright/tests/e2e/mcp/mcp-service.spec.ts:6-23, packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md:1-8
Architecture and Components
The MCP implementation follows a modular architecture separated into several layers, coordinated by a central McpServer facade.
System Layers
| Layer | Component | Purpose |
|---|---|---|
| Facade | McpServer | Main entry point that coordinates all subsystems using the Facade pattern. |
| Session | SessionManager, SessionStore | Manages client connections, tool registrations, and session lifecycle. |
| Transport | TransportFactory, SSETransport, StreamableHttpTransport | Handles communication via Server-Sent Events (SSE) or Streamable HTTP. |
| Execution | ExecutionCoordinator, DirectStrategy, QueuedStrategy | Executes tools either directly in-process or via a worker queue. |
| Protocol | MessageParser, MessageFormatter | Translates raw JSONRPC 2.0 messages into typed MCP structures. |
Sources: packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md:12-45
Component Relationship Diagram
The following diagram illustrates the relationship between the MCP client, the server facade, and the core layers.
Core and Builder Tools
The n8n MCP service exposes two distinct categories of tools to external clients. Access is authenticated via a Bearer token (MCP API key).
Core Tools
Core tools allow AI models to interact with existing n8n workflows.
search_workflows: Search for workflows available in MCP.get_workflow_details: Retrieve nodes, connections, and metadata for a specific workflow.execute_workflow: Trigger a workflow execution and receive the execution ID.get_execution: Poll for full execution details and result data.publish_workflow/unpublish_workflow: Activate or deactivate workflows.
Builder Tools
When enabled (via N8N_MCP_BUILDER_ENABLED), these tools assist AI agents in creating new workflows.
search_nodes: Find nodes by service name or trigger type.get_node_types: Get TypeScript definitions for n8n nodes to ensure valid configuration.validate_workflow: Validate n8n Workflow SDK code generated by the AI.create_workflow_from_code: Create an actual n8n workflow from validated code.
Sources: packages/testing/playwright/tests/e2e/mcp/mcp-service.spec.ts:11-23
Transport and Communication
MCP supports two primary communication protocols to accommodate different deployment environments.
Transport Protocols
- SSE (Server-Sent Events): A long-lived GET connection to
/ssefor streaming responses, paired with POST requests to/messagesfor client-to-server tool calls. - Streamable HTTP: A more REST-like protocol using POST requests to
/mcpwithmcp-session-idheaders, supporting stateless or load-balanced environments.
Sources: packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md:214-258
Connection Flow
The following sequence diagram represents the typical lifecycle of an MCP tool call via SSE.
Execution Strategies
The system utilizes a Strategy pattern to handle tool execution based on the instance configuration.
- Direct Execution: The
DirectExecutionStrategyinvokes the tool immediately within the same Node.js process. This is used in standard single-instance setups. - Queued Execution: In multi-instance deployments (Queue Mode), the
QueuedExecutionStrategyenqueues a job in Redis. A worker process executes the tool and publishes the result back to the main instance via anmcp-responseevent.
Sources: packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md:278-310
Queue Mode Data Flow
This diagram shows how requests are handled when n8n is running in multi-instance queue mode.
AI Workflow Generation and Discovery
MCP integrates with n8n's AI Workflow Builder to facilitate automated workflow creation. This involves specialized agents that use MCP-style tools internally.
Discovery and Planning
The Discovery Agent identifies relevant nodes and "connection-changing parameters" (parameters that alter the node's inputs or outputs, such as a Vector Store's mode or an AI Agent's hasOutputParser).
Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:161-172, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:383-408
Knowledge Base Best Practices
For AI-driven knowledge base workflows, the system enforces specific patterns:
- Ingestion vs. Query: Splitting logic into an ingestion workflow (indexing content) and a query workflow (retrieval).
- Embedding Consistency: Ensuring the same embedding model is used for both indexing and querying to prevent semantic search failure.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts:8-66
Summary
The Model Context Protocol (MCP) provides a robust, layered interface for connecting n8n to AI ecosystems. By exposing both core workflow management and advanced builder tools through standardized JSONRPC 2.0 and SSE/HTTP transports, it allows AI models to act as autonomous operators and creators within the n8n environment.