MCP (Model Context Protocol) Integration
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/@n8n/mcp-browser/README.md
- packages/frontend/@n8n/design-system/src/components/N8nSettingsLayout/Examples.stories.ts
- packages/@n8n/instance-ai/src/agent/system-prompt.ts
The Model Context Protocol (MCP) integration allows AI agents, IDEs, and external clients to interact with n8n resources and tools through a standardized protocol. n8n implements MCP in two primary ways: an Instance-level MCP server that exposes overall platform capabilities (workflow management, execution, and building), and a Workflow-level MCP Trigger that allows specific workflows to act as MCP servers for custom tools.
This integration supports both internal n8n tools for workflow automation and specialized external servers like the Browser MCP, which grants AI agents control over local browser instances via an extension bridge.
Sources: packages/quality/testing/playwright/tests/e2e/mcp/mcp-service.spec.ts, packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md, packages/@n8n/instance-ai/src/agent/system-prompt.ts:168-175
Architectural Overview
n8n uses a modular architecture for handling MCP connections, separating the protocol logic into several core layers. This design ensures that MCP requests share a consistent session registry and execution tracking.
The McpServer class acts as a facade, coordinating subsystems to handle incoming JSON-RPC messages and manage client sessions.
Sources: packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md:14-49
Core Implementation Layers
| Layer | Purpose | Key Components |
|---|---|---|
| Protocol | Translates raw HTTP bodies into typed MCP structures. | MessageParser, MessageFormatter |
| Session | Manages connection state and tool registrations per client. | SessionManager, SessionStore (In-Memory/Redis) |
| Transport | Handles communication protocols (SSE or Streamable HTTP). | SSETransport, StreamableHttpTransport |
| Execution | Executes tool calls via direct invocation or worker queues. | ExecutionCoordinator, PendingCallsManager |
Sources: packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md:54-61
Instance-level MCP Server
The Instance-level MCP server exposes the n8n instance's workflows and building capabilities to external assistants. It requires authentication via a Bearer token (MCP API key) and can be enabled or disabled globally in the n8n settings.
Sources: packages/quality/testing/playwright/tests/e2e/mcp/mcp-service.spec.ts:31-50, packages/frontend/@n8n/design-system/src/components/N8nSettingsLayout/Examples.stories.ts:1330-1350
Available Tools
The instance server provides two sets of tools: Core tools for operating existing workflows and Builder tools for creating new ones.
| Tool Name | Type | Description |
|---|---|---|
search_workflows | Core | Search for workflows marked as available in MCP. |
execute_workflow | Core | Execute a workflow and retrieve the execution ID. |
get_workflow_details | Core | Get nodes, connections, and metadata for a workflow. |
publish_workflow | Core | Activate a specific workflow version. |
search_nodes | Builder | Search for n8n nodes by service name or trigger type. |
get_node_types | Builder | Retrieve TypeScript type definitions for node parameters. |
create_workflow_from_code | Builder | Create a new workflow using the n8n Workflow SDK. |
Sources: packages/quality/testing/playwright/tests/e2e/mcp/mcp-service.spec.ts:15-32
Multi-Instance Execution Flow
In multi-instance or queue mode deployments, n8n utilizes a QueuedExecutionStrategy to handle tool calls across different worker processes.
Browser MCP Integration
The Browser MCP is a specialized server that provides AI agents with control over a local Chrome browser via the n8n Browser Bridge extension. It uses the user's real profile, cookies, and login sessions.
Sources: packages/@n8n/mcp-browser/spec/browser-mcp.md:5-10
Browser Connection Model
- Extension Bridge: Uses a WebSocket-based relay to communicate with the Chrome extension.
- Lazy Activation: The debugger only attaches to a tab when the agent first interacts with it.
- Targeting: Tools accept an optional
pageIdto target specific tabs; otherwise, they operate on the active page.
Sources: packages/@n8n/mcp-browser/spec/browser-mcp.md:16-35
Key Browser Tools
| Category | Tools |
|---|---|
| Session | browser_connect, browser_disconnect |
| Navigation | browser_navigate, browser_back, browser_reload |
| Interaction | browser_click, browser_type, browser_hover, browser_scroll |
| Inspection | browser_snapshot, browser_screenshot, browser_evaluate |
| State | browser_cookies, browser_storage |
Sources: packages/@n8n/mcp-browser/spec/browser-mcp.md:46-95
Workflow Building via MCP
Agents use the MCP Builder tools to construct workflows programmatically using the n8n Workflow SDK. The integration provides specific instructions and best practices to ensure generated workflows are valid.
Building Sequence
- Read SDK Reference: Call
get_sdk_referenceto understand syntax. - Discover Nodes: Use
search_nodesto find required integrations. - Fetch Type Definitions: Call
get_node_typesfor exact parameter names. - Explore Resources: Use
explore_node_resourcesfor dynamic options (e.g., Slack channels). - Validate: Run
validate_workflowon the generated code. - Create: Save the workflow using
create_workflow_from_code.
Sources: packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts:114-142
MCP Credential Guardrails
To protect sensitive information, the integration includes guardrails that prevent agents from asking users to paste secrets directly into the chat. Instead, agents are instructed to ground credential setup in the official n8n UI.
Sources: packages/@n8n/instance-ai/src/agent/system-prompt.ts:176-180, packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts:153-157
Summary
MCP Integration in n8n provides a standardized interface for both platform management and custom workflow automation. By utilizing a modular facade architecture, it supports various transport protocols and execution strategies, enabling seamless connectivity for AI agents and IDEs to the n8n ecosystem.