> 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/connect/connect-to-n8n-mcp-server.md).
# Connect to n8n MCP server
n8n's built-in MCP server lets supported clients, such as Lovable or Claude Desktop, connect securely to your 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 (n8n 2.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 is `search_workflows`, which can access every workflow the current user has permission to view, but only returns previews, not 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
{% hint style="info" %}
**Feature availability**
The settings layout described below (**Connection details**, **Access**, **Connected clients**), the **Connect a client** dialog, and **Allowed callback URLs** are available from n8n 2.33.0. These replace the previous single-page MCP settings screen. On older versions, this page shows a simpler layout without per-client setup steps.
{% endhint %}
### For Cloud and self-hosted instances
1. Navigate to **Settings > Instance-level MCP**.
2. Select **Enable MCP access** (requires instance owner or admin permissions).
Once enabled, the page groups settings into three sections:
* **Connection details**: shows the **MCP status** and a **Connect** button that opens setup steps for your MCP client.
* **Access**: shows how many workflows (and, if your instance has the agents feature, agents) are exposed to MCP clients, see [Exposing workflows to MCP clients](#exposing-workflows-to-mcp-clients) and [Exposing agents to MCP clients](#exposing-agents-to-mcp-clients). Instance owners and admins also see **Allowed callback URLs** here, see [Restricting OAuth callback URLs](#restricting-oauth-callback-urls).
* **Connected clients**: shows how many clients currently have access, each with its own granted permissions. Select **View all** to review or revoke access for individual clients, see [Reviewing and revoking client access](#revoking-client-access).
**To disable:** In **Connection details**, select the **MCP status** control and choose **Disable**. n8n asks you to confirm, since disabling disconnects every connected client and revokes its access. You can turn MCP access back on later.
{% 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.
## Connecting MCP clients
{% hint style="info" %}
**Feature availability**
Per-client connection setup steps are available from n8n 2.33.0. Earlier versions don't show these steps. Use the manual instructions in [MCP client connection examples](/connect/connect-to-n8n-mcp-server/mcp-client-examples.md) to configure your client instead.
{% endhint %}
In **Connection details**, select **Connect** to open the **Connect a client** dialog, then choose an authentication method: [OAuth (recommended)](#using-oauth2) or [API key](#using-access-token).
### Using OAuth (recommended)
1. Navigate to **Settings > Instance-level MCP**.
2. In **Connection details**, select **Connect** to open the **Connect a client** dialog.
3. Make sure the **OAuth (recommended)** tab is selected.
4. In the **Your client** dropdown, pick your AI assistant, IDE, or CLI. n8n groups clients into **CLI** (Claude Code, Codex, Gemini CLI), **Web** (Claude.ai, ChatGPT), and **IDE** (Cursor, VS Code, Windsurf), and shows setup steps tailored to your choice.
5. Follow the steps shown for your client type:
* **Web clients**: select **One-click setup** to add n8n to the client directly, or copy the **Server URL** and paste it into the client's own connector settings yourself.
* **CLI clients**: run the install command shown, or add the manual configuration snippet to the client's configuration file instead. Either way, finish with the **Authenticate** step to complete the OAuth sign-in (see the [Claude Code](/connect/connect-to-n8n-mcp-server/mcp-client-examples.md#connecting-claude-code-to-n8n-mcp-server) and [Codex](/connect/connect-to-n8n-mcp-server/mcp-client-examples.md#connecting-codex-cli-to-n8n-mcp-server) examples for the exact commands).
* **IDE clients**: select the one-click install link (where the editor supports one), or copy the **Server URL** and add the manual configuration snippet to the editor yourself.
6. When the client redirects you to n8n, approve access to finish connecting it.
#### Reviewing and revoking client access
Each connected client only has the permissions you granted it when it connected, for example reading workflows without being able to create or run them. To review or revoke a client's access:
1. Navigate to **Settings > Instance-level MCP**.
2. In **Connected clients**, select **View all**. You should see a table of connected OAuth clients, their access level, and when they connected. Clients using an API key don't appear here, since they authenticate with a bearer token rather than an OAuth connection.
3. Select a client's row to open its details and see every permission you granted it, or select **Revoke access** directly on the row to skip straight to revoking.
4. Confirm the revocation. n8n disconnects the client at once; it must reconnect and sign in again to regain access.
### Using API key
1. Navigate to **Settings > Instance-level MCP**.
2. In **Connection details**, select **Connect** to open the **Connect a client** dialog.
3. Switch to the **API key** tab. n8n automatically generates a personal access token tied to your user account the first time you open it.
4. Copy what you need: the **Configuration JSON** block, already filled in with your server URL and an `Authorization: Bearer` header carrying your token, or the individual **Server URL** and access token values if your client doesn't use that JSON format (for example, Codex's TOML config). Once you leave this tab, n8n only shows a redacted token value, and you won't be able to copy it again unless you [rotate it](#rotating-your-token).
5. Paste what you copied into your MCP client's configuration: drop the **Configuration JSON** straight in for clients that accept an `mcpServers` JSON snippet, or use the individual **Server URL** and token for clients that need a different format. This tab isn't client-specific, so the same values work no matter which client you're setting up (see [MCP client connection examples](/connect/connect-to-n8n-mcp-server/mcp-client-examples.md) for client-specific formats).
#### Rotating your access token
If you lose your token or need to rotate it:
1. Navigate to **Settings > Instance-level MCP**.
2. In **Connection details**, select **Connect** to open the **Connect a client** dialog.
3. Switch to the **API key** tab.
4. Generate a new token using the button next to the redacted 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.
{% hint style="info" %}
**Workflow eligibility**
Only workflows that are published, and that contain a webhook, form, schedule, or chat trigger node, can be enabled for MCP access.
{% endhint %}
### Enabling access for individual workflows
#### Option 1: From the Workflows exposed page (available from n8n 2.2.0)
1. Navigate to **Settings > Instance-level MCP**.
2. Select **Workflows exposed**.
3. Click the **Enable workflows** button (in the workflows table header or in the table's empty state).
4. Search for the desired workflow (by name or description) and select it from the list.
5. Click **Enable** 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" %}
**Feature availability**
Project and folder-level MCP access control is available from n8n 2.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 **Workflows exposed** page (**Access > Workflows exposed**) 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 2.2.0)
### Workflow descriptions
To help MCP clients identify workflows, you can add free-text descriptions as follows:
1. Option 1: From the **Workflows exposed** page
1. Navigate to **Settings > Instance-level MCP**.
2. Select **Workflows exposed**.
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**.
## Exposing agents to MCP clients
{% hint style="info" %}
**Feature availability**
Agents are available from n8n 2.34.0 and are a separate feature from workflows. See [Build and manage agents](/build/build-and-manage-agents.md) for details. This section only applies if agents are enabled on your instance.
{% endhint %}
{% hint style="info" %}
**Feature availability**
Agents are in preview and may change in future releases. Avoid relying on them in production workflows.
{% endhint %}
If your instance has the agents feature, the **Access** section also shows **Agents exposed**. As with workflows, MCP clients can't read or manage an agent unless you explicitly enable MCP access for it.
### Enabling access for individual agents
#### Option 1: From the MCP settings page
1. Navigate to **Settings > Instance-level MCP**.
2. Select **Agents exposed**.
3. Select **Enable agents**.
4. Search for the desired agent by name and select it from the list.
5. Select **Enable** to confirm.
#### Option 2: From the agent builder
1. Open the agent in the agent builder.
2. Open its MCP settings.
3. Toggle **Available in MCP**.
### Managing agent access
The **Agents exposed** page shows every agent enabled for MCP clients to access, with its name and its project or folder location. From this list you can:
* Open an agent or its project directly.
* Remove access for a single agent from its row, or select multiple agents and remove access for all of them at once.
* Enable access for more agents using the **Enable agents** button.
## Restricting OAuth callback URLs
Instance owners and admins can restrict which URLs an OAuth client can redirect to after it signs in. By default, n8n allows any callback URL, which is less secure.
1. Navigate to **Settings > Instance-level MCP**.
2. In **Access**, select **Allowed callback URLs**.
3. Choose a mode:
* **All callback URLs**: any URL can complete an OAuth sign-in.
* **Only trusted URLs**: only the URLs you list can complete an OAuth sign-in.
4. If you chose **Only trusted URLs**, add each URL you trust, then select **Save**.
## 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, agent management, 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).
## n8n Skills for coding agents
When you connect a coding agent to the n8n MCP server, the agent can build and edit workflows, but it doesn't automatically know n8n's conventions for expressions, node configuration, error handling, and other patterns. n8n Skills give the agent that knowledge so it gets workflows right the first time.
n8n Skills are a set of capability modules published in the [n8n-io/skills](https://github.com/n8n-io/skills) repository. They pair with the instance-level MCP server and include:
* **13 capability skills** covering workflow best practices, including sub-workflows, expressions, loops, AI agents, error handling, credentials, data tables, and debugging.
* **50+ reference documents and examples** with per-node guidance, decision trees, and copy-paste workflow snippets.
* **Hooks** that load the right guidance automatically, so the agent reads the relevant skill before it makes high-impact MCP calls.
A 14th meta-skill, `using-n8n-skills-official`, routes the agent to the matching capability skill for each task.
### Why use skills
Skills load guidance at the moment the agent needs it, rather than relying on the model's general knowledge. This helps the agent:
* Follow n8n best practices for the node or feature it's working with.
* Avoid common mistakes, such as incorrect expression syntax or missing error handling.
* Produce workflows that need less back-and-forth to fix.
The skills are plain Markdown, so you can read, fork, and modify them for your own conventions.
### Installing skills
The [n8n-io/skills](https://github.com/n8n-io/skills) repository has up-to-date install instructions for Claude Code, Codex, and other coding agents. Follow the steps in the repository README to add the skills to your agent.
## Examples
For exact commands and configuration to connect specific clients, including Lovable, Claude Desktop, Claude Code, Codex, Gemini CLI, Cursor, VS Code, Windsurf, and Google ADK agents, see [MCP client connection examples](/connect/connect-to-n8n-mcp-server/mcp-client-examples.md).
## 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 (OAuth or API key) is configured correctly in your MCP client.
* Review n8n server logs for any error messages related to MCP connections.