How to set up the n8n MCP server

Governing MCP across your organization?

Speakeasy’s AI control plane connects, secures, and observes every agent and MCP server from one entry point — with SSO, RBAC, runtime guardrails, and a full audit trail.

n8n has an official MCP server built into every n8n instance, on n8n Cloud and self-hosted. Its URL is your instance’s address followed by /mcp-server/http. It lets an AI agent search your workflows, run them, and build new workflows for you.

This guide shows you how to connect the n8n MCP server to Claude Code and Codex. You’ll turn on MCP access in n8n, create an access token, choose which workflows your agent can use, and add the server to your agent.

/MCP Gateway

One URL for every MCP

Point Claude Code, Cursor, and Copilot at one URL. SSO, per-team policy, and an audit log on every tool call are already built.

Start free

Prerequisites

To follow along, you’ll need:

• An n8n instance on version 2.33 or later, on n8n Cloud or self-hosted. This guide uses n8n 2.44.5.
• The owner or admin role on that instance, to turn on MCP access
• Claude Code or Codex CLI installed

Step 1: Enable instance-level MCP in n8n

In n8n, open Settings and select Instance-level MCP. Click Enable MCP access.

The page now shows Connection details, with MCP status set to Enabled.

Step 2: Create an n8n MCP access token

Under Connection details, click Connect next to Connect your client. In the Connect a client dialog, select the API key tab.

n8n generates a personal access token the first time you open this tab, and it shows the token only once. Click the copy icon next to Access token.

The token lets your agent act as you in n8n, so keep it out of config files and code. Instead, save it as an environment variable in your shell profile:

echo 'export N8N_MCP_TOKEN="your-n8n-token"' >> ~/.zshrc

Replace your-n8n-token with the token you copied. If you use Bash, write to ~/.bashrc instead.

Open a new terminal window so the variable loads.

Also copy the Server URL from the same tab. You need it in Step 4.

When you come back to the tab later, n8n hides the token. To replace it, click the refresh icon next to the hidden value. This revokes the old token, so update your agents with the new one.

Step 3: Make workflows available in MCP

Your agent can see a preview of every workflow you have access to, but it can only run a workflow that’s available in MCP.

To make a workflow available, go to your workflows list in n8n. Click the … menu on the workflow’s card and select Enable MCP access.

The card now shows the MCP icon after its creation date. You can also turn on Available in MCP in a workflow’s Settings inside the editor. Workflows that your agent creates through MCP are available in MCP automatically.

Step 4: Connect your agent to the n8n MCP server

Follow the instructions for the agent you use: Claude Code or Codex. For any other agent, see Connect other MCP clients.

In the commands below, replace <your-n8n-url> with the start of the Server URL you copied in Step 2, for example https://your-name.app.n8n.cloud. For a local n8n instance, use http://localhost:5678.

Claude Code

Add the n8n MCP server to Claude Code:

claude mcp add --transport http --scope user n8n <your-n8n-url>/mcp-server/http --header 'Authorization: Bearer ${N8N_MCP_TOKEN}'

Keep the single quotes around the header. They tell Claude Code to save the variable name rather than the token itself, and Claude Code reads the token from your environment when it starts. The --scope user option makes the server available in all your projects.

Check that the server connects:

claude mcp list

The n8n server shows as Connected. On a local instance, the line looks like this:

n8n: http://localhost:5678/mcp-server/http (HTTP) - ✔ Connected

Start Claude Code with claude and ask it to run one of your workflows, for example:

Use my n8n Score inbound lead workflow to score this lead: Dana Lee from Northwind Logistics, 400 employees, a $45,000 budget, buying within 2 months

Replace the workflow name and details with one of your own workflows that’s available in MCP.

Claude Code asks for permission the first time it uses each n8n tool. Select Yes to let it run.

Claude Code finds the workflow, runs it with your input, and reports the result.

Codex

Add the n8n MCP server to Codex:

codex mcp add n8n --url <your-n8n-url>/mcp-server/http --bearer-token-env-var N8N_MCP_TOKEN

The --bearer-token-env-var option tells Codex to read the token from the N8N_MCP_TOKEN environment variable and send it with each request.

Check the server’s configuration:

codex mcp list

On a local instance, the n8n row looks like this:

Name    Url                                    Bearer Token Env Var  Status   Auth
n8n     http://localhost:5678/mcp-server/http  N8N_MCP_TOKEN         enabled  Bearer token

Start Codex with codex and enter /mcp. The n8n server shows as connected (50 tools).

Ask Codex to build a workflow, for example:

Create an n8n workflow that gets the weather forecast for London from the Open-Meteo API every morning at 7am

Codex asks for permission before it runs some n8n tools, such as update_workflow and execute_workflow. Select Allow to let it continue.

Codex builds the workflow, tests it, and publishes it.

The new workflow appears in n8n, published and ready to run.

Connect other MCP clients

You can connect any MCP client that supports remote (Streamable HTTP) servers and custom headers. Use these values:

Setting	Value
Server URL	<your-n8n-url>/mcp-server/http
Header	Authorization: Bearer <your n8n MCP access token>

Troubleshooting

Codex shows n8n: failed (0 tools)

If /mcp in Codex shows the n8n server as failed, press F2 to view the warning:

MCP client for `n8n` failed to start: MCP startup failed: Environment variable N8N_MCP_TOKEN for MCP server 'n8n' is not set
MCP startup incomplete (failed: n8n)

This warning means Codex started before the N8N_MCP_TOKEN variable was set. Codex runs a background process that keeps the environment it started with, so you need to restart it.

Quit Codex, then stop its background process:

pkill -f "codex app-server"; pkill -f codex-code-mode-host

Open a new terminal window, start codex, and enter /mcp again.

Next steps

You now have the n8n MCP server connected to your agent. You turned on instance-level MCP, created an access token, saved it as an environment variable, chose which workflows your agent can use, and added the server to Claude Code or Codex. Your agent can search your workflows, run them, and build new ones for you.

To keep going:

• Connect more services to your agent with the other guides in Connect popular MCP servers.
• Learn how to get better results from your agent’s tools in Best practices for using MCP tools.
• See what teams build with MCP in MCP use cases.