MCP tool namespacing

Summary

MCP servers expose tools alongside an agent's builtin tools, so naming must guarantee that MCP tools never collide with builtins like read_file. Claude Code solves this by always encoding an MCP tool's name as mcp__<server>__<tool>, and by making hook matchers and permission rules key off that prefix. Other agents (yoyo, yoagent) have taken different — and sometimes broken — approaches, from skipping entire servers on any collision to storing a prefix without ever emitting it.

Key Points

• Claude Code always namespaces MCP tools as mcp__<server>__<tool>, so an MCP tool can never collide with a builtin (read_file, etc.).
• Hook matchers and permission rules depend on that prefix:
  • a bare mcp__lab matcher matches nothing;
  • mcp__lab__.* is the documented whole-server form (2.1.195+).
• Plugin-bundled MCP servers produce names of the form mcp__plugin_<plugin>_<server>__<tool>.
• v2.1.292 additionally drops MCP tools whose names exceed the API name-length limit (128 chars), emitting a per-server warning.
• yoyo (Day 230) takes the opposite approach: it skips an entire MCP server if any of its tool names collides with BUILTIN_TOOL_NAMES (a pre-flight check in agent_builder.rs). This makes @modelcontextprotocol/server-filesystem unusable.
• yoagent 0.25.7 (2026-10-16) fixed McpToolAdapter::with_prefix / from_client_with_prefix to actually emit <prefix>__<tool> — the prefix had been stored but never used. The with_mcp_server_* helpers still add no prefix.
• Open design point (yoyo): adding a prefix changes the tool names that hooks.rs matchers, permission rules, and audit rows key on, and a prefixed name must still stay under the 128-char API limit.

Concepts