MCP Server Slug Disambiguation#

Claude Code can register the same logical MCP server under three distinct mcp_server slug namespaces, and a real archive routinely contains two or three of them as separate rows in tools/mcp-usage 1:

The mcp_server field is populated at ingest by classifyTool(), which splits the MCP naming convention mcp__<server>__<base> on the first __ separator and stores whatever raw string appears as <server>. No prefix normalization happens at the storage layer — the raw slug is the canonical identity 2.

The Collision Problem#

Prefix-stripping formatters are lossy by construction 3. A formatter that naively strips ^claude_ai_ and ^plugin_[^_]+_ will collapse dosu, claude_ai_Dosu, and any plugin variant onto a single label "Dosu". This reads to users as a duplicate-row bug rather than multiple real registrations. The problem is worst where call volumes are comparable (e.g., posthog 786 calls vs plugin_posthog_posthog 444 calls), because it looks like one server was arbitrarily split.

Two additional lossy edges in the same formatter shape 4:

• Slugs are hyphen-separated as often as underscore-separated (claude-in-chrome, linear-server), so splitting on _ alone leaves "Claude-in-chrome".
• A bare UUID mcp_server value should be preserved as-is; title-casing its segments produces ungreppable hex noise.

Set-Aware Formatting: mcpServerLabels()#

The solution is a set-aware formatter rather than a per-value one. mcpServerLabels() in src/mcp-names.ts takes an iterable of raw slugs and returns a Map<string, string> that:

1. Computes the short display name for every slug via formatMcpServer().
2. Counts how many distinct slugs produce each short name.
3. For unambiguous names (used by only one slug), returns the short name unchanged.
4. For colliding names, appends the origin from mcpServerOrigin() — e.g. "Dosu (local)" vs "Dosu (connector)" vs "Posthog (posthog plugin)".

A per-value formatMcpServer() function also exists but is explicitly documented as unsafe when sibling servers are on screen 5. It remains useful only for isolated contexts where no collision is possible.

Origin labels#

mcpServerOrigin() returns:

• "connector" — slug starts with claude_ai_
• "local" — no recognized prefix (bare .mcp.json registration)
• "plugin" — plugin-bundled where the plugin name matches the display name (avoids stutter like "Posthog (posthog plugin)")
• "<plugin> plugin" — plugin-bundled where plugin name differs from display name

UUID handling#

The regex OPAQUE_ID 6 detects UUID-shaped slugs and returns them unchanged, since title-casing hex segments produces noise rather than a meaningful name.

Layering Constraint#

Display formatters live under src/ui/ and should stay there. The file src/ui/mcp-server.ts is a thin re-export wrapper 7 that exposes formatMcpServer, mcpServerLabel, mcpServerLabels, and mcpServerOrigin to UI consumers without exposing the implementation module directly.

The server-side recommendations path (recommendations.ts) embeds the raw slug into signal titles (e.g., Heavy reliance on the "codex_apps" MCP server) and cannot use a formatter from src/ui/ without inverting the core-to-UI dependency direction. If server-side formatting is ever needed, the formatter belongs in src/tools.ts, which already owns classifyTool() and is where the mcp__<server>__<base> split happens 8. Note that src/ui/mcp-server.ts is documented as "shared with recommendations.ts" 9, meaning the naming module is already reachable from src/mcp-names.ts directly without going through the UI layer.

UI Integration#

In src/ui/main.tsx, mcpServerLabels() is called once per render across the union of all MCP servers visible in both the MCP and Tools tables 10. This ensures consistent naming across all display contexts — table cells, filter dropdowns, drilldown row labels, and the tool detail modal. Raw slugs are always preserved in title attributes, filter values, hrefs, and API payloads; only rendered text uses the formatted label 11.

Key Files#