> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/build/ways-of-building-workflows/connect-to-n8n-mcp-server.md).
# Connect to n8n MCP server
Connect supported MCP clients to your n8n workflows through n8n's built-in MCP server.
The server allows clients such as Lovable or Claude Desktop to connect securely to an n8n instance. Once connected, these clients can:
* Search for your workflows
* Interact with workflows marked as available in MCP
* Trigger and test exposed workflows
* Create and edit workflows and data tables
## Difference between instance-level MCP access and MCP Server Trigger node
Instance-level MCP access lets you create one connection per n8n instance, use centralized authentication, and choose which workflows to enable for access. Enabled workflows are easy to find and run without extra setup for each workflow.
In comparison, you configure an MCP Server Trigger node inside a single workflow. This node exposes tools only from that workflow, a useful approach when you want to craft a specific MCP server behavior within one workflow.
### Key considerations when using instance-level MCP access
* MCP supports two types of workflow interactions: running existing workflows with the workflow execution tools, and building or editing workflows (v2.13 onward).
* It doesn’t provide blanket exposure to all workflows in your instance. You must enable MCP at the instance level and then enable each workflow individually. The only exception here is the `search_workflows` tool, which is able to access all workflows current user has access to but it will only be able to surface previews, not the full workflow data.
* It's not scoped to each MCP client. All clients you connect (for example, Claude Desktop and ChatGPT) can see all workflows you've enabled for MCP access. You can't restrict specific workflows to specific clients. On a user level, visibility remains user-scoped: users can only see MCP-enabled workflows they have access to.
* Most MCP tools work on unpublished workflows. The exception is `execute_workflow`, which defaults to production mode and runs the published version of a workflow. It also supports a `manual` execution mode to run the current (unpublished) version.
## Enabling MCP access
### For Cloud and self-hosted instances
1. Navigate to **Settings > Instance-level MCP**
2. Toggle **Enable MCP access** (requires instance owner or admin permissions).
Once enabled, you'll see:
1. List of workflows exposed to MCP clients
2. List of connected OAuth clients
3. Main MCP toggle to enable/disable instance-level access
4. *Connection details* button that shows detailed instructions for connecting MCP clients
**To disable:** Toggle the main MCP toggle off.
{% hint style="info" %}
**Environment variables (self-hosted only)**
On self-hosted instances, you can also manage MCP settings using environment variables. See [Manage instance settings using environment variables](/deploy/host-n8n/configure-n8n/manage-settings-using-environment-variables.md#mcp).
{% endhint %}
### For self-hosted: Complete disablement
To remove the feature entirely, set the environment variable:
`N8N_DISABLED_MODULES=mcp`
This action removes MCP endpoints and hides all related UI elements.
## Setting up MCP authentication
The **Connection details** popup menu provides two authentication options for MCP clients:
* **OAuth2**
* **Access Token**
### Using OAuth2
Copy your instance server URL from the **OAuth** tab and use it to configure your MCP client. After connecting, the client will redirect you to n8n to authorize access.
#### Revoking client access
To revoke access for connected MCP clients:
1. Navigate to **Settings > Instance-level MCP**.
2. Switch to the **Connected clients** tab. You should see a table of connected OAuth clients.
3. Use the action menu in each client's row to revoke access for specific clients.
### Using Access Token
Use your instance server URL and your personal MCP Access Token from the **Access Token** tab on the *Connection details* menu.
When you first visit the **MCP Access page**, n8n automatically generates a personal MCP Access Token tied to your user account.
{% hint style="info" %}
Copy your token right away. On future visits, you'll only see a redacted value and the copy button will be disabled.
{% endhint %}
#### Rotating your token
If you lose your token or need to rotate it:
1. Navigate to **Settings > Instance-level MCP**.
2. Open the *Connection details* menu by clicking the button in the top-right corner.
3. Switch to the **Access Token** tab.
4. Generate a new token using the button next to the redacted token value.
n8n revokes the previous token when you generate a new one.
5. Update all connected MCP clients with the new value.
## Exposing workflows to MCP clients
MCP clients can discover previews of all workflows the current user has access to using `search_workflows`. However, clients can't access full workflow data, nor execute or modify a workflow unless you explicitly enable MCP access for that workflow.
### Enabling access for individual workflows
#### Option 1: From MCP settings page (available from n8n v2.2.0)
1. Click the **Enable workflows** button (in the workflows table header or in the table's empty state)
2. Search for the desired workflow (by name or description) and select it from the list
3. Click **Enable** button to confirm
#### Option 2: From the workflow editor
1. Open the workflow.
2. Click the main workflow menu (`...`) in the top-right corner.
3. Select **Settings**.
4. Toggle **Available in MCP**.
#### Option 3: From the workflows list
1. Go to **Workflows**.
2. Open the menu on a workflow card.
3. Select **Enable MCP access**.
### Enabling access for projects/folders
{% hint style="info" %}
**Available from n8n v2.24.0**
{% endhint %}
You can use the **Options** menu 
in the workflow list to toggle MCP access for all workflows in the current project or folder:
1. Navigate to the desired project and select **Workflows** from the top menu, then open a subfolder if required.
2. Select the **Options** menu next to the name of the project or folder.
3. Select **Manage MCP access**, then either **Enable MCP** or **Disable MCP**.
{% hint style="info" %}
**Note**
This will toggle MCP access for all workflows that are **currently** in the selected project or folder (skipping ones that are already in the selected state). You will still need to toggle access for any workflows added in the future.
{% endhint %}
### Managing access
The **Instance-level MCP** settings page shows all workflows enabled for MCP clients to access and operate on. From this list you can:
* Open a workflow, its home project or parent folder directly
* Revoke access using the action menu (or use **Disable MCP access** from the workflow card menu)
* Update workflow description using the action menu (or use the menu in the workflow editor)
* Enable access for more workflows using the **Enable workflows** button (available from n8n v2.2.0)
### Workflow descriptions
To help MCP clients identify workflows, you can add free-text descriptions as follows:
1. Option 1: From the **Instance-level MCP** page
1. Navigate to **Settings > Instance-level MCP**.
2. Make sure you are on the **Workflows** tab.
3. Use the action menu in the desired workflow's row and select the **Edit description** action.
4. Alternatively, click the description text directly to open the edit dialog.
2. Option 2: From the workflow editor
1. Open the workflow.
2. Click the main workflow menu (`...`) in the top-right corner.
3. Select **Edit description**.
## Tools and resources
{% hint style="info" %}
Consider using coding agents (such as Claude Code or Google ADK agents) instead of chat clients as your MCP clients. Coding agents are optimized for generating and validating TypeScript code, making them ideal for building workflows programmatically.
{% endhint %}
The n8n MCP server exposes tools for workflow management, workflow building, and data tables. For a complete list of available tools and their parameters, refer to the [MCP server tools reference](/connect/connect-to-n8n-mcp-server/mcp-server-tools-reference.md).
## Examples
#### Connecting Lovable to n8n MCP server
1. Configure MCP Server in Lovable (OAuth).
* Navigate to your workspace **Settings > Integrations**.
* In the **MCP Servers** section, find **n8n** and click **Connect**.
* Enter your n8n server URL (shown on the **MCP Access** page).
* Save the connection. If successful, n8n redirects you to authorize Lovable.
2. Verify connectivity.
* Once connected, Lovable can query for workflows with MCP access enabled.
* **Example:** Asking Lovable to build a workflow UI that lists users and allows deleting them.
#### Connecting Claude Desktop to n8n MCP server
**Using OAuth2**
1. Navigate to **Settings** > **Connectors** in Claude Desktop.
2. Click on **Add custom connector**.
3. Enter the following details:
* **Name:** n8n MCP
* **Remote MCP Server URL**: Your n8n base URL (shown on the **Instance-level MCP** page)
4. Save the connector.
5. When prompted, authorize Claude Desktop to access your n8n instance.
**Using Access Token**
Add the following entry to your `claude_desktop_config.json` file:
```json
"mcpServers": {
"n8n-mcp": {
"type": "http",
"url": "https:///mcp-server/http",
"headers": {
"Authorization": "Bearer "
}
}
}
```
Here, replace:
* ``: Your n8n base URL (shown on the **Instance-level MCP** page)
#### Connecting Claude Code to n8n MCP server
**OPTION 1: Authenticate using OAuth2 (Recommended)**
Use the following CLI command:
```bash
claude mcp add --transport http n8n-mcp https:///mcp-server/http
```
Alternatively, add the following entry to your `claude.json` file:
```json
{
"mcpServers": {
"n8n-mcp": {
"type": "http",
"url": "https:///mcp-server/http"
}
}
}
```
Here, replace:
* ``: Your n8n base URL (shown on the **Instance-level MCP** page)
**OPTION 2: Authenticate using Access Token**
Use the following CLI command:
```bash
claude mcp add --transport http n8n-mcp https:///mcp-server/http \
--header "Authorization: Bearer "
```
Alternatively, add the following entry to your `claude.json` file:
```json
{
"mcpServers": {
"n8n-mcp": {
"type": "http",
"url": "https:///mcp-server/http",
"headers": {
"Authorization": "Bearer "
}
}
}
}
```
Here, replace:
* ``: Your n8n base URL (shown on the **Instance-level MCP** page)
* ``: Your generated token
### Connecting Codex CLI to n8n MCP server
**OPTION 1: Authenticate using OAuth2 (Recommended)**
Use the following CLI command:
```bash
codex mcp add n8n-mcp --url https:///mcp-server/http
```
Alternatively, add the following entry to your `~/.codex/config.toml` file:
```toml
[mcp_servers.n8n-mcp]
url = "http://localhost:5678/mcp-server/http"
```
Here, replace:
* ``: Your n8n base URL (shown on the **Instance-level MCP** page)
**OPTION 2: Authenticate using Access Token**
Add the following entry to your `~/.codex/config.toml` file:
```toml
[mcp_servers.n8n-mcp]
url = "https:///mcp-server/http"
http_headers = { "authorization" = "Bearer " }
```
Here, replace:
* ``: Your n8n base URL (shown on the **Instance-level MCP** page)
* ``: Your generated token
### Connecting Google ADK agent to n8n MCP server
Here's sample code to create an agent that connects to a remote n8n MCP server:
```python
from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPServerParams
N8N_INSTANCE_URL = "https://localhost:5678"
N8N_MCP_TOKEN = "YOUR_N8N_MCP_TOKEN"
root_agent = Agent(
model="gemini-2.5-pro",
name="n8n_agent",
instruction="Help users manage and execute workflows in n8n",
tools=[
McpToolset(
connection_params=StreamableHTTPServerParams(
url=f"{N8N_INSTANCE_URL}/mcp-server/http",
headers={
"Authorization": f"Bearer {N8N_MCP_TOKEN}",
},
),
)
],
)
```
For more details, see [Connect ADK agent to n8n](https://google.github.io/adk-docs/tools/third-party/n8n/).
## Troubleshooting
If you encounter issues connecting MCP clients to your n8n instance, consider the following:
* Ensure that your n8n instance is publicly accessible if you are using cloud-based MCP clients.
* Verify that the MCP access is enabled in n8n settings.
* Check that the workflows you want to execute or modify are marked as **Available in MCP**.
* Confirm that the authentication method (OAuth2 or Access Token) is correctly configured in your MCP client.
* Review n8n server logs for any error messages related to MCP connections.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.n8n.io/build/ways-of-building-workflows/connect-to-n8n-mcp-server.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.