Model Context Protocol (MCP)
Relevant source files
The following files were used as context for generating this wiki page:
- packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts
- packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md
- packages/quality/testing/playwright/tests/e2e/mcp/mcp-service.spec.ts
- packages/@n8n/mcp-browser/spec/browser-mcp.md
- packages/frontend/@n8n/design-system/src/components/N8nSettingsLayout/Examples.stories.ts
- packages/@n8n/instance-ai/src/agent/system-prompt.ts
- packages/@n8n/instance-ai/src/agent/tests/sanitize-mcp-descriptions.test.ts
Model Context Protocol (MCP) is an open standard that allows AI assistants and IDEs to connect to n8n. It enables external models to discover and execute n8n workflows, manage resources, and control browser environments. n8n implements MCP through an instance-level server and specialized trigger nodes.
Sources: packages/frontend/@n8n/design-system/src/components/N8nSettingsLayout/Examples.stories.ts, packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md:1-10
Architecture and Layers
The MCP implementation follows a modular architecture. It separates concerns into four distinct layers coordinated by a central facade.
This diagram illustrates the high-level request flow from a client through the modular layers of the MCP server.
1. Protocol Layer
The Protocol layer translates raw HTTP requests into typed MCP data structures. It uses JSONRPC 2.0 as the wire protocol.
- MessageParser: Validates raw JSON and identifies request types like tool calls or list-tools.
- MessageFormatter: Converts tool execution results or errors into the standard MCP format.
Sources: packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md:140-165
2. Session Layer
The Session layer manages client connections and their state.
- SessionManager: Tracks connected clients and associates them with specific transports and tools.
- SessionStore: Provides pluggable storage for session IDs. It supports
InMemorySessionStorefor single instances andRedisSessionStorefor multi-instance deployments.
Sources: packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md:250-280
3. Transport Layer
The Transport layer abstracts the communication protocol between the server and clients.
- SSE Transport: Uses Server-Sent Events for long-lived GET connections. Responses stream back on this connection while tool calls arrive via POST requests.
- Streamable HTTP Transport: A request-response protocol that supports session recreation on different server instances.
Sources: packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md:360-400
4. Execution Layer
The Execution layer implements strategies for invoking tools.
- DirectExecutionStrategy: Executes tools immediately within the main process.
- QueuedExecutionStrategy: Used in multi-instance deployments. It enqueues jobs and waits for worker responses via a
PendingCallsManager.
Sources: packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md:520-545
Server Types
n8n provides two types of MCP servers:
| Server Type | Scope | URL Endpoint |
|---|---|---|
| Instance-level | Exposes global instance workflows to clients. | /mcp-server/http |
| Workflow-level | Exposes tools for a single workflow via a trigger node. | /mcp/<path> |
Sources: packages/@n8n/instance-ai/src/agent/system-prompt.ts
Available Tools
The MCP server provides core tools for workflow management and builder tools for programmatic creation.
Core Tools
Core tools allow clients to interact with existing workflows.
search_workflows: Finds workflows available in MCP.get_workflow_details: Retrieves nodes, connections, and settings for a workflow.execute_workflow: Starts a workflow execution and returns an ID.get_workflow_execution: Fetches data and status for a specific execution.publish_workflow/unpublish_workflow: Manages workflow activation states.
Sources: packages/quality/testing/playwright/tests/e2e/mcp/mcp-service.spec.ts:15-30
Builder Tools
Builder tools enable AI models to construct workflows using the n8n Workflow SDK.
search_nodes: Searches for nodes by service name or trigger type.get_node_types: Fetches TypeScript definitions for node parameters.validate_workflow: Checks SDK code for syntax and structural errors.create_workflow_from_code: Saves validated code as a new n8n workflow.
Sources: packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts:115-150
Browser MCP
Browser MCP allows AI agents to control a Chrome browser through the n8n Browser Bridge extension.
Connection Flow
- The agent calls the
browser_connecttool. - The server launches Playwright and connects to the relay server.
- The Browser Bridge extension connects via WebSocket.
- The extension reports user-selected tabs to the relay.
This sequence shows the initialization steps required to link an AI agent to a physical browser instance.
Browser Tools
- Navigation:
browser_navigate,browser_back,browser_reload. - Interaction:
browser_click,browser_type,browser_scroll,browser_upload. - Inspection:
browser_snapshot(accessibility tree),browser_screenshot,browser_content(markdown).
Sources: packages/@n8n/mcp-browser/spec/browser-mcp.md:25-80
Security and Sanitization
Authentication
Requests to the MCP server require a Bearer token (API Key). n8n supports one active MCP API key at a time. Rotating the key invalidates the previous one.
Sources: packages/quality/testing/playwright/tests/e2e/mcp/mcp-service.spec.ts:40-60
Data Sanitization
The system sanitizes tool descriptions and JSON schema titles to prevent prompt injection or UI breakages.
- Strips invisible Unicode characters.
- Normalizes line endings and collapses excessive blank lines.
- Truncates descriptions exceeding
MCP_TOOL_DESCRIPTION_MAX_LENGTH. - Protects the prototype chain by preventing
__proto__keys from reaching the object prototype.
Sources: packages/@n8n/instance-ai/src/agent/tests/sanitize-mcp-descriptions.test.ts:10-180
Configuration Options
| Option | Type | Description |
|---|---|---|
isBuilderEnabled | Boolean | Enables or disables programmatic workflow builder tools. |
isInstanceContextEnabled | Boolean | Instructs the client to read instance-specific metadata first. |
transportType | String | Defines the protocol (sse or streamableHttp). |
authentication | String | Defines auth method (e.g., none, bearerAuth, githubOAuth2Api). |
Sources: packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts:30-60, packages/cli/src/modules/agents/tests/from-json-config.test.ts:1000-1050
MCP serves as a critical bridge between n8n's automation capabilities and the reasoning power of external AI models, facilitating both workflow execution and autonomous environment interaction.