Eight MCP servers in one claude_desktop_config.json. No error on boot. No warning on tool registration. Six days of using the agent before I noticed that "search" was sometimes hitting Brave and sometimes hitting my local filesystem, and "create_issue" had silently routed every issue I created that week into Linear when I thought I was filing them on GitHub.
It turns out MCP, as of the 2026-03 spec, has no built-in namespace for tool names. Two servers can register list_files and the client (Claude in my case) will use whatever map it built last. There is no collision detection. There is no warning. There is a registry that quietly overwrites.
This post is what I found when I sat down and audited the 8-server registration on day six, what each silent collision actually did, and the three-line config change that has kept me at zero collisions for six weeks since.
The 8 servers and why each one was there
For context, this is not a stunt setup. Each server earned its slot for a real task I run weekly.
-
brave-search— web search for fact-checking -
filesystem— read/write inside an Obsidian vault -
github— issue and PR ops on my own repos -
linear— issue and project ops on a client repo -
s3— read access to a private logs bucket -
freee— tax/expense ops (Japanese accounting service) -
slack— read-only on two channels for catch-up summaries -
postgres— read-only on a personal analytics DB
Eight servers, totalling 87 tools when Claude finished registering them. Around 4,400 tokens of tool descriptions in the system prompt, which is its own problem (separate post). The thing I want to talk about is the names.
The three collisions
When I dumped the registered tool list and grouped by name, three pairs had collided. Two of them I could have predicted in retrospect. The third I would not have, and it is the one that scared me.
Collision 1: search. Both brave-search and filesystem registered a tool named search. The Brave one takes a query and returns web results. The filesystem one takes a query and greps the Obsidian vault. They have completely different argument schemas. Claude was choosing based on which definition got loaded last on boot, which in turn depended on file order in the config (alphabetical, then filesystem won). When I asked "search for the latest Anthropic safety paper," Claude ran a regex over my Obsidian vault and confidently told me there was no result. That was the bug that started the audit.
Collision 2: create_issue. Both github and linear registered create_issue. Same name, same overall shape (title, body, labels), incompatible everything else (linear wants a teamId, github wants owner and repo). When I asked Claude to "open an issue about the asyncpg regression," it called the second-loaded one, which was Linear. The issue went into a client project where it did not belong, with a body that mentioned my private Postgres schema. I closed it quickly. The fact that I had to is the point.
Collision 3: list_files. Both filesystem and s3 registered list_files. When I asked Claude to "list the files in the inbox folder," it ran the s3 version, listed every object in the bucket prefix inbox/, and stuffed about 31,000 tokens of file metadata into the context. The session was effectively burned. I had to start a new one. The bucket has roughly 40k objects in it. The local inbox/ directory has 12.
None of these throw an error. The MCP client (Claude Desktop / Claude Code) sees a flat tool registry. Last write wins. Period.
Why the spec lets this happen
I went and re-read the Model Context Protocol spec (2026-03-26 revision) to confirm I was not missing something. I was not. The tools/list response from a server returns tool names as flat strings. There is no namespace field. There is no server_id qualifier. The client is expected to flatten the tool lists from all servers into a single map. The spec does not say what to do on collision because, in the spec's mental model, a collision is a configuration problem.
That is technically correct and operationally insufficient. Anyone wiring more than two MCP servers will hit a collision eventually because the names that show up are exactly the names you would pick yourself: search, list, get, create, delete. They are not safe by accident.
There is a pending proposal (#287) to add namespace prefixes server-side, dated around early 2026, but as of writing it has not landed and the client implementations have not picked it up. So this is an "until further notice" problem.
What I added
Three lines in my agent config. Not pretty. Effective.
{
"mcpServers": {
"brave-search": { "command": "...", "tool_prefix": "brave_" },
"filesystem": { "command": "...", "tool_prefix": "fs_" },
"github": { "command": "...", "tool_prefix": "gh_" },
"linear": { "command": "...", "tool_prefix": "linear_" },
"s3": { "command": "...", "tool_prefix": "s3_" },
"freee": { "command": "...", "tool_prefix": "freee_" },
"slack": { "command": "...", "tool_prefix": "slack_" },
"postgres": { "command": "...", "tool_prefix": "pg_" }
}
}
tool_prefix is a client-side feature in the build of Claude Code I am running (added in the 2026-04 release; check your version). It rewrites every tool name from a server to {prefix}{tool_name} before registering. Now search becomes brave_search and fs_search, create_issue becomes gh_create_issue and linear_create_issue, and the registry has 87 unique names.
If your client does not have this feature, the same thing works at the server side: fork the server, prefix the names at the source. Uglier, same result.
What I measure now
I added two checks to my agent boot:
Collision scan. On startup, after all servers register, walk the tool list and assert no duplicates. Fail the boot if a duplicate exists. Three lines of code. It would have caught my problem on day one.
Tool-call attribution log. Every tool call gets logged with
{server_name, tool_name, args_summary}. When something feels wrong, I can grep one day of transcripts and see whethersearchcalls went to Brave or filesystem. This is also what I used to measure the 22% wrong-server rate before the prefix change. Without attribution logging, you cannot know whether you have this problem.
The attribution log lives in ~/.claude/agent-tool-calls.jsonl for me. Six weeks of it is about 14 MB and has caught one other subtle bug (a freee server returning data for the wrong fiscal year) that had nothing to do with name collisions. The investment paid for itself twice in six weeks.
What I do not do
I do not run any MCP server with a generic tool name like search or list un-prefixed, ever, even if it is the only server registered. The cost of prefixing is around 4 tokens per tool in the description. The cost of a silent collision when you add a second server six months later is one production-shaped incident.
I also do not trust client implementations to add collision warnings on my behalf. The MCP client market is moving fast. Today's "the client warns you on duplicate" feature is tomorrow's "we removed that warning because it was too noisy in this other workflow." The boot-time assertion lives in my repo. It will outlast any specific client.
The lesson, if there is one, is the same as it always is with protocols that started as Just Wire Two Things Together: as soon as you have eight of anything, the assumptions the protocol made when there were two are the things that quietly bite.
The longer version of this story (the OWASP MCP Top 10 in production, the file-upload workaround chain, the 55k-token system-prompt diet I am running on the same 8-server config) is in Practical MCP Security. Chapter 6 is the auth and tool-registration audit playbook I run on every new server now.
Top comments (11)
Tool-name collisions are one of those boring problems that become serious once agents act automatically. Names need namespaces, ownership, and intent. Otherwise the model sees two plausible tools and the wrong one can still look semantically correct.
Yeah, intent is the part the prefix doesn't actually fix. The tool_prefix config killed the name clash, but it just turned one ambiguous "search" into two valid options. The model still has to know fs_search is the vault and brave_search is the web. If the descriptions are vague, you've basically moved the collision from the name to the reasoning step.
What helped more than the prefix was rewriting the descriptions to say where each tool acts, not just what it does. "Searches the local Obsidian vault" vs "Searches the public web." The prefix stops the silent overwrite, the description is what stops the wrong-but-plausible call.
Yes, exactly. Names solve routing only at the first layer. The model still needs semantic boundaries: local vs web, read-only vs mutating, private vs public. I think the best tool descriptions are almost permission labels, not marketing copy.
Awesome write-up, Ken! That create_issue glitch—where your private Postgres data accidentally went into a client’s Linear account—is a perfect example of the hidden security risks in MCP right now.
Using tool_prefix is a great temporary fix for a local setup. However, as soon as teams start sharing MCP servers or using them across a whole company, managing all those different files and prefixes by hand becomes a full-time job.
This exact mess is why I’ve been building vectoralix.com. We are creating a platform to host and manage MCP servers. It handles things like namespacing and server discovery automatically. That way, you don't have to waste time manually changing tool names or worrying about your system prompts getting way too long.
I'm really looking forward to your next post on MCP security—we definitely need more practical guides like this!
Thanks Eugene! Yeah, prefix-per-config is really just a personal-grade workaround. Once two people edit the same config, the manual side scales badly.
Curious how vectoralix handles collisions when two upstream servers ship the same tool name. Does one win, or do both stay exposed with disambiguated names?
Thank you for asking. Let me explain that in a few words:
Vectoralix isn't an aggregating MCP client, so there are no "upstream servers" whose tools get merged.
Each Vectoralix McpServer exposes only the tools explicitly bound to it via the mcp server tool pivot. A client hitting /mcp/{serverUid} sees that one server's tools, not a union across servers.
Basically responsibility on naming and tool description is on the user. More clear name of the tool will be - better experience user will have with his data and llm processing.
Got it, that makes sense. Single endpoint, single namespace, naming on the user is a clean model for that scope. The collision I wrote about really only bites once you flatten several servers into one agent, which sounds like a different layer from what Vectoralix targets. Thanks for walking through it, and good luck with the build.
This is gold. The silent collision problem is exactly the kind of issue you only discover after week 2 of running multi-server setups. We hit something similar in our multi-agent Hermes setup — two agents registering overlapping tool names and quietly clobbering each other.
Your routing table approach is clever but feels like a workaround for something the MCP spec should address. Did you consider prefixing tool names at the server level (e.g. github_list_files, fs_list_files) vs the client-side routing?
Yeah, that was my first instinct too. The catch: I don't own the GitHub or Postgres servers, so renaming their tools means forking and maintaining a patch forever. Client-side routing was the only layer I actually control. Agree the spec should handle namespacing, not me.
This seems even more worrying to me than a hard error! Having writes land on the wrong system is wild.
Namespacing feels like a smart way to wrangle our multi-tool setups. Love it!
Exactly. A hard error at least pages you. The create_issue one scared me most because nothing failed: the write went through fine, just into the wrong tenant. By the time you notice, the data's already sitting in someone else's project.