{"record":{"id":"5bf0f707210f30ce","repo":"n8n-io/n8n","slug":"mcp-tool-name-collision-the-following-tool-names","errorCode":null,"errorMessage":"MCP tool name collision — the following tool names resolve to duplicates: ${collisions.join(', ')}","messagePattern":"MCP tool name collision — the following tool names resolve to duplicates: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@n8n/agents/src/sdk/agent.ts","lineNumber":1034,"sourceCode":"\t\t\t\tstaticNames.has(tool.name) ||\n\t\t\t\treservedDeferredToolNames.has(tool.name) ||\n\t\t\t\tdeferredNames.has(tool.name)\n\t\t\t) {\n\t\t\t\tdeferredCollisions.push(tool.name);\n\t\t\t}\n\t\t\tdeferredNames.add(tool.name);\n\t\t}\n\t\tif (deferredCollisions.length > 0) {\n\t\t\tthrow new Error(\n\t\t\t\t`Deferred tool name collision — the following tool names resolve to duplicates or reserved tools: ${deferredCollisions.join(', ')}`,\n\t\t\t);\n\t\t}\n\n\t\tconst collisions = mcpTools\n\t\t\t.filter((t) => staticNames.has(t.name) || deferredNames.has(t.name))\n\t\t\t.map((t) => t.name);\n\t\tif (collisions.length > 0) {\n\t\t\tthrow new Error(\n\t\t\t\t`MCP tool name collision — the following tool names resolve to duplicates: ${collisions.join(', ')}`,\n\t\t\t);\n\t\t}\n\n\t\tlet allTools = [...finalStaticTools, ...mcpTools];\n\n\t\t// Validate checkpoint again after discovering actual MCP tools\n\t\t// (catches the case where MCP tools have suspendSchema after listing).\n\t\tconst allNeedCheckpoint =\n\t\t\tallTools.some((t) => t.suspendSchema) || finalDeferredTools.some((t) => t.suspendSchema);\n\t\tif (allNeedCheckpoint && !this.checkpointStore) {\n\t\t\tthrow new Error(\n\t\t\t\t`Agent \"${this.name}\" has tools requiring approval or suspend/resume but no checkpoint storage. ` +\n\t\t\t\t\t\"Add .checkpoint('memory') for in-process storage, \" +\n\t\t\t\t\t'or pass a persistent store (e.g. LibSQLStore, PgStore).',\n\t\t\t);\n\t\t}\n","sourceCodeStart":1016,"sourceCodeEnd":1052,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/agents/src/sdk/agent.ts#L1016-L1052","documentation":"Thrown by Agent.build() after listing MCP server tools, when an MCP tool's name matches a name already in the static or deferred tool set. MCP tools are discovered at build time via listTools(), so this collision is detected after the static/deferred checks. Duplicate names between MCP and local tools make tool dispatch ambiguous.","triggerScenarios":"An MCP server exposes a tool whose name matches a locally-registered static or deferred tool. For example, an MCP server provides 'search' and the agent also has a local tool named 'search'. Also triggered by two MCP servers exposing tools with the same name (though ensureUniqueMcpToolNames may handle intra-MCP dedup first).","commonSituations":"Connecting to a third-party MCP server that provides generic-named tools (search, fetch, get) that overlap with custom local tools. Using multiple MCP servers with overlapping functionality. An MCP server updating its tool list to include a name that now conflicts.","solutions":["Rename the local static or deferred tool to avoid the collision with the MCP-provided name.","Configure the MCP client to filter or rename tools if it supports tool name remapping.","Remove the conflicting local tool if the MCP version is sufficient.","Inspect the error message for the specific colliding names and resolve each."],"exampleFix":"// before\nagent.tools([{ name: 'search', ... }])\n     .mcp(myMcpClient); // MCP also exposes 'search'\n// after\nagent.tools([{ name: 'local_search', ... }])\n     .mcp(myMcpClient);","handlingStrategy":"validation","validationCode":"function findMcpCollisions(localNames: Set<string>, mcpTools: { name: string }[]): string[] {\n  return mcpTools.filter((t) => localNames.has(t.name)).map((t) => t.name);\n}\n// After listing MCP tools, check before build:\nconst localNames = new Set([...staticTools, ...deferredTools].map((t) => t.name));\nconst collisions = findMcpCollisions(localNames, mcpTools);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Rename local tools that conflict with MCP-provided tool names.","Use MCP client filtering or name remapping if supported.","Audit MCP server tool lists when adding new local tools."],"tags":["mcp","tools","naming","collision","configuration","agent"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}