This error means the workflow JSON references a node type that is not registered in your n8n instance. For the MCP client node specifically there are three usual causes: N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE is not set, the community package did not install cleanly, or you are on a recent n8n version where MCP is built in and the community node is no longer needed.
The confusing part is that the error appears even on workflows where the MCP node is not connected to anything. n8n validates every node in the workflow at load time, not just the ones on the execution path, so one orphaned node on the canvas breaks the whole workflow.
Work through the causes in order. The first one accounts for most reports, and it is a single environment variable.
Table of contents
- The missing environment variable
- Check whether you still need the community node
- When the package genuinely failed to install
- Case sensitivity and the exact node type string
- Self-hosting n8n so this stops being a recurring problem
- How this fits the rest of the stack
- FAQ
The missing environment variable
n8n will not let a community node be used as an AI agent tool unless you explicitly opt in. Without the flag, the node installs and appears in the list, and then fails to register as a tool — which surfaces as exactly this error the moment an agent references it.
N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=trueWhere you set it depends on how you run n8n. In Docker Compose:
services:
n8n:
image: n8nio/n8n
environment:
- N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
- N8N_COMMUNITY_PACKAGES_ENABLED=trueFor a bare docker run, add -e N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true. For npm installs, export it before starting the process.
Restart is required — n8n reads this at startup and will not pick it up on a workflow reload. Confirm it landed:
docker exec n8n printenv | grep COMMUNITYIf the variable is not in that output, the container is not seeing it, and nothing else you try will help.
Check whether you still need the community node
This is worth doing before debugging any further, because it makes the problem disappear entirely.
n8n added native MCP support. Recent versions ship an MCP Client Tool node in core, which means the community package n8n-nodes-mcp is redundant on those versions — and having both installed is a known source of conflicts.
Check your version:
docker exec n8n n8n --versionIf the built-in node is present in your node panel, the migration is straightforward: delete the community node from the canvas, add the core MCP Client Tool, re-enter the server URL and credentials, and reconnect it to the agent. Then uninstall the community package so the two cannot conflict.
The catch is that workflow JSON you import from elsewhere may still reference the community node type. That is the most common way people hit this error on a fresh instance — they imported a template built before MCP moved into core. In that case you are not missing a package, you are looking at a workflow that needs updating.
When the package genuinely failed to install
Community nodes install into n8n’s user folder, and a failed install often leaves the UI reporting success while the node never registers.
docker exec n8n ls ~/.n8n/nodes/node_modules/
# expect: n8n-nodes-mcpIf it is missing, or the directory is empty, reinstall it from the Settings → Community nodes panel. If installation fails there, the log usually says why:
docker logs n8n 2>&1 | grep -i -E "community|mcp|install" | tail -30Two causes are common:
- No persistent volume. If
~/.n8nis not on a volume, community nodes vanish on every container restart. This presents as a node that worked yesterday and does not today. - No outbound network at install time. The install pulls from the npm registry, and a restricted network makes it fail in ways the UI reports vaguely.
The volume issue is the one to check first on any containerised setup, because it explains the intermittent version of this problem:
volumes:
- n8n_data:/home/node/.n8nCase sensitivity and the exact node type string
The node type in the error is n8n-nodes-mcp.mcpClientTool, with a capital C and a capital T. Node type identifiers are case sensitive, and a workflow JSON that was hand-edited or produced by a script can carry a subtly wrong string.
There are also two distinct nodes in that package and people conflate them:
mcpClient— the standalone node you call directly in a workflow.mcpClientTool— the variant that attaches to an AI Agent as a tool.
An error about mcpClientTool when you only ever installed and used mcpClient usually means the workflow was built against the tool variant elsewhere.
Inspect what the workflow actually asks for, straight from the JSON:
grep -o '"type": "n8n-nodes-mcp[^"]*"' workflow.json | sort -uThat prints every MCP node type the file references, which is the fastest way to see whether you are missing a package or looking at a typo.
Self-hosting n8n so this stops being a recurring problem
Most of the causes above trace back to the same root: n8n’s state is not durable, or its environment is not reproducible. A container without a volume loses its community nodes. An environment variable set by hand on one host is missing on the next.
The fixes are unglamorous and permanent:
- Put
~/.n8non a real volume so installed nodes and credentials survive restarts. - Keep every
N8N_*variable in the deployment configuration, not in shell history. - Use Postgres rather than the default SQLite for anything beyond experimentation — SQLite is where execution history goes to become a corruption story.
- Pin the n8n image version. Automatic latest-tag upgrades are how a working instance breaks overnight when a node moves into core.
That last point is the one people learn the hard way, and it is directly relevant here — the community MCP node became redundant because of a version change, not because anything you did was wrong.
How this fits the rest of the stack
Every cause above is really the same problem wearing different clothes: n8n is stateful, and self-hosting it means being deliberate about where that state lives and what version is running. The community node registry, the credentials, the execution history and the environment all have to survive a restart, or you get errors that look like bugs and are actually amnesia.
RunxBuild runs n8n as a managed tool with its own plan, persistent state, custom domains, environment variables and logs, alongside a managed Postgres for the execution database — which removes the volume-and-restart class of failure without giving up self-hosting. n8n on a $6 Basic plan with a Postgres beside it is a fairly typical starting shape. The RunxBuild hosting calculator shows what that comes to once the database and storage are included.
Useful related references:
- n8n AI Agent Node: What It Does and When a Plain Chain Is Better
- n8n + Qdrant: A Vector Search Node for Real Workflows
- n8n HTTP Request Node: The Auth and Error Playbook
- Node services on RunxBuild
FAQ
What causes Unrecognized node type in n8n?
The workflow references a node type that is not registered in your instance. For community nodes that means the package is not installed, failed to install, or is blocked from being used as an AI tool. n8n validates every node on the canvas at load time, so even a disconnected node triggers the error.
Do I still need n8n-nodes-mcp?
Not on recent versions. n8n ships an MCP Client Tool node in core, and running the community package alongside it is a known source of conflicts. Check your node panel for the built-in node — if it is there, migrate to it and uninstall the community package.
Why does the node disappear after restarting the container?
Community nodes install into ~/.n8n/nodes, and if that path is not on a persistent volume the container loses them on every restart. Mount a named volume at /home/node/.n8n and the installs survive.
What does N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE do?
It permits community nodes to be attached to AI Agent nodes as tools. Without it the node can install and appear normally but will not register as a tool, which surfaces as an unrecognized node type error the moment an agent references it. It is read at startup, so a restart is required.
How do I see which node types a workflow needs?
Search the workflow JSON directly with something like grep -o '"type": "n8n-nodes-mcp[^"]*"' workflow.json | sort -u. That lists the exact type strings, which distinguishes a missing package from a typo or a case-sensitivity mismatch.