Resolving Tool Name Collisions When Bundling Multiple MCP Servers in the Claude Agent SDK

Implementing a Reconciler in TypeScript

The reconciler takes server tool bundles, detects collisions, renames them, and returns a bidirectional alias map.

// reconciler.ts
import type { Tool } from "@anthropic-ai/sdk/resources/messages.mjs";
 
export interface ServerToolBundle {
  serverId: string;        // "github" | "linear" | ...
  tools: Tool[];
}
 
export interface ReconciledTools {
  tools: Tool[];
  forward: Map<string, { serverId: string; original: string }>;
  reverse: Map<string, string>;
}
 
const PREFIX_SEP = "__";
const NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
 
export function reconcile(bundles: ServerToolBundle[]): ReconciledTools {
  const seen = new Map<string, string[]>();
  for (const b of bundles) {
    for (const t of b.tools) {
      const list = seen.get(t.name) ?? [];
      list.push(b.serverId);
      seen.set(t.name, list);
    }
  }
  const conflicted = new Set(
    [...seen.entries()].filter(([, ids]) => ids.length > 1).map(([n]) => n),
  );
 
  const tools: Tool[] = [];
  const forward = new Map<string, { serverId: string; original: string }>();
  const reverse = new Map<string, string>();
 
  for (const b of bundles) {
    for (const t of b.tools) {
      const needsPrefix = conflicted.has(t.name);
      const renamed = needsPrefix ? `${b.serverId}${PREFIX_SEP}${t.name}` : t.name;
      if (!NAME_RE.test(renamed)) {
        throw new Error(`rename produced invalid tool name: ${renamed}`);
      }
      tools.push({ ...t, name: renamed });
      forward.set(renamed, { serverId: b.serverId, original: t.name });
      reverse.set(`${b.serverId}:${t.name}`, renamed);
    }
  }
  return { tools, forward, reverse };
}

Three things to flag in the code. Only colliding tools get prefixed. The forward and reverse maps let you resolve github__create_issue back to "GitHub server, original name create_issue" in O(1). And the regex check raises during build if any rename produces a name that the Messages API would reject.

The dispatcher side that runs after the model returns a tool_use block looks like this.

// dispatcher.ts
import type { ToolUseBlock } from "@anthropic-ai/sdk/resources/messages.mjs";
import { reconcile, type ServerToolBundle } from "./reconciler.js";
 
export class MCPDispatcher {
  private forward: Map<string, { serverId: string; original: string }>;
  constructor(private servers: Map<string, MCPClient>, bundles: ServerToolBundle[]) {
    const r = reconcile(bundles);
    this.forward = r.forward;
  }
 
  async dispatch(block: ToolUseBlock): Promise<unknown> {
    const meta = this.forward.get(block.name);
    if (!meta) {
      return { isError: true, content: `unknown tool: ${block.name}. available: ${[...this.forward.keys()].join(", ")}` };
    }
    const server = this.servers.get(meta.serverId);
    if (!server) {
      return { isError: true, content: `server ${meta.serverId} not registered` };
    }
    return server.callTool(meta.original, block.input as Record<string, unknown>);
  }
}

One word on error handling. Throwing on unknown tool will tear down your agent loop. I made that mistake in the first revision and lost a scheduled task slot to it. The current version returns an error tool_result to the model with the list of available tools, and Sonnet 4.6 almost always corrects itself on the next turn. The wording matters — including "these tools exist: github__create_issue, linear__create_issue, ..." gives the model a runway to land on the correct name.

Normalizing descriptions with provenance tags

Renaming alone is not enough. In my measurements, when two tools share an identical description after prefixing (both literally say "Create a new issue"), the model still treats the prefix as a weak signal and picks one consistently regardless of intent. To strengthen the signal I tag descriptions by origin.

function tagDescription(serverId: string, tool: Tool): Tool {
  const labelMap: Record<string, string> = {
    github: "[GitHub]",
    linear: "[Linear]",
    jira: "[Jira]",
    slack: "[Slack]",
    notion: "[Notion]",
  };
  const tag = labelMap[serverId] ?? `[${serverId}]`;
  const orig = tool.description ?? "";
  if (orig.startsWith(tag)) return tool;
  return { ...tool, description: `${tag} ${orig}`.trim() };
}

Simple, but effective. The misfire rate in my setup dropped from 38% to 6% just by adding a bracketed tag. Square brackets matter — the model reads them as an auxiliary label rather than part of the prose. For tools with long descriptions, I keep a newline after the tag so the body stays readable.

I also learned that beefier descriptions help when names collide. [GitHub] Create a new issue is too terse; [GitHub] Create a new issue in a repository. Use this for code-related bug reports, feature requests, and pull-request discussions on the GitHub side. cuts misfires by an additional 3 points. Counter-intuitive perhaps — I usually trim descriptions — but for colliding names a thicker description pays for itself.

Rebuilding when MCP servers come and go

Real Agent SDK apps see servers come and go. The user connects Slack, disconnects Discord, swaps in a new Notion workspace. Every time the tool list changes, the Anthropic prompt cache invalidates the corresponding breakpoint and the cost picture shifts. On one AdMob automation that bundled four MCP servers, I quietly lost about 12% of my monthly cache benefit by failing to manage this transition.

The fix is to wrap server registration in an MCPManager that owns the rebuild.

// mcp-manager.ts
type Listener = (state: ReconciledTools) => void;
 
export class MCPManager {
  private bundles = new Map<string, ServerToolBundle>();
  private listeners: Listener[] = [];
  private current!: ReconciledTools;
 
  register(b: ServerToolBundle) {
    this.bundles.set(b.serverId, b);
    this.rebuild();
  }
  unregister(serverId: string) {
    this.bundles.delete(serverId);
    this.rebuild();
  }
  onChange(l: Listener) { this.listeners.push(l); }
 
  private rebuild() {
    this.current = reconcile([...this.bundles.values()]);
    for (const l of this.listeners) l(this.current);
  }
  snapshot() { return this.current; }
}

Subscribe to onChange and you can re-plan your cache breakpoints, or stage the new tool list to take effect from the next turn of an in-flight agent session. The non-negotiable rule is to never swap the tool list mid-turn. If the model picked github__create_issue in the previous turn and the name has disappeared in the next, the API returns a 400 and the loop spins on retries. Switch at turn boundaries only.

Three production failure modes

After running this in production for a while, I want to share three specific failures.

Stale alias. GitHub MCP renamed create_issue to issues_create in an update. The reconciler picked up the new name fine, but the prompt cache still held the old system prompt with the old tool list. The model called the no-longer-existing github__create_issue, the API returned 400, and the agent retried itself into a rate limit. Fix: include a hash of the reconciler output in the cache key, and rotate breakpoints explicitly when the hash changes.

Description drift. Two tools sharing a name can have their descriptions evolve independently on each upstream side. Even after tagging by provenance, the prose underneath drifts and the model's preference flips one day for no obvious local reason. I now dump the forward map's descriptions weekly to a Slack channel for eyeball review, scheduled in Cowork alongside my AdMob monthly numbers.

Schema collision. Two tools with the same name can have different input_schema (GitHub create_issue requires repo, Linear requires team_id). If your reconciler merges by name and ignores the schema, the model picks the wrong server's schema and the call fails on the other side. Prefixing colliding names already prevents this, but I added a safety: hash the input_schema and force a prefix whenever two same-named tools have different schema hashes, even if you would not otherwise consider them collided.

function schemaHash(t: Tool): string {
  return JSON.stringify(t.input_schema, Object.keys(t.input_schema).sort());
}

Two smaller things worth noting alongside the big three. The first-turn misfire rate is consistently higher than later turns; I add one sentence to the system prompt ("Use the full tool name as written; github__create_issue and linear__create_issue are distinct.") and that gap closes. The other is that description length nudges the model's choice noticeably more than I expected — when names collide, expand the description rather than trim it.

Operations notes from running six sites

I started programming in 1997 at age 16, picking up languages by trial and error on dial-up forums where the only feedback came from strangers around the world. The MCP world has the same texture — someone publishes a server, you fold it into your agent, and you read tool names to infer their intent. Designing for collisions with strangers' servers feels like a basic courtesy in that world.

In production I switched from "site-based" server IDs (claudelab, gemilab, rorklab) to "capability-based" ones (admob, slack, github). When four sites pull from the same AdMob account, write to the same Slack workspace, and commit to the same GitHub organization, capability-based IDs let you reuse one server registration across all four. The Reconciler output stays more stable too, which means a higher prompt cache hit rate.

A subtler observation: more servers means slower responses. Anthropic's API takes noticeably longer with 60 tools in the array compared to 10, and the prompt cache hit rate shifts with every change to the tool list. After reorganizing my AdMob pipeline around capability-based bundles, daily aggregation per site dropped by 14% in latency on average. Over a month, that adds up.

The takeaway is that adding more MCP servers is not free. For each agent task I now ask "which tools does this actually need", and I bundle accordingly. AdMob aggregation does not need the GitHub MCP; a PR review does not need the Slack MCP. Task-specific bundles keep the reconciler output deterministic, which keeps the cache hot.

Next steps

If you want to add a reconciler to your project, start by calling list_tools on every server you currently bundle and grouping by name to visualize the actual collisions. You'll probably find more than you expected. Next, run the reconciler above end to end with prefixing turned on for the conflicting pairs only. Description normalization comes after that.

MCP is still in the phase where multiple vendors are publishing servers with their own naming traditions, and the variance will widen before it narrows. A reconciler layer turns server churn from a code change into a configuration change, which keeps your agent code stable and your shipping pace steady.

I share more half-formed notes from this work over on my stand.fm channel when I have something worth saying. Thanks for reading this far.