MCP Tool Naming: Three Formats, One Gotcha

The Three Naming Formats

• **Claude Code format (double underscore)**
  • › Pattern: mcp__plugin_<plugin>_<server>__<tool>
  • › Example: mcp__plugin_dx-aem_AEM__getNodeContent
  • › Project-level servers skip the plugin prefix: mcp__ado__wit_work_item
• **Copilot CLI, VS Code Chat and Codex CLI (bare name)**
  • › Pattern: tool
  • › Example: getNodeContent, wit_work_item
  • › No server prefix at all. Codex constrains tool names to letters, digits, underscore and hyphen, so a dotted prefix is not even legal there.
• **Gemini CLI format (single underscore)**
  • › Pattern: mcp_<server>_<tool>, lowercased
  • › Example: mcp_aem_getnodecontent
  • › The server name must not contain an underscore. If two servers expose the same tool name, Gemini promotes it to serverAlias__tool with a double underscore.
• **The gotcha** — Write the Claude Code prefixed name and stop there. In an agent or skill file these names are prose hints to the model, not literal function calls, so the LLM maps a prefixed name onto whatever is registered locally. Listing a second format is redundant, and a stale one is worse than nothing.

Cross-Platform Survival Guide

1. 1 **Write one format: the Claude Code prefix**
   • › In skill and agent files: mcp__plugin_dx-aem_AEM__getNodeContent
   • › Other platforms resolve it from the tools and mcpServers declarations — adding a new MCP server needs no per-platform edit
2. 2 **Debugging in Claude Code** — Use ToolSearch("+AEM") to find the real prefixed name. If a tool 'doesn't exist,' the naming format is the first thing to check.
3. 3 **Debugging in Copilot CLI** — MCP tools appear under their bare name in tool lists, with no server prefix. Compare against what your agent file references.
4. 4 **Comparison test** — Look at a Claude Code agent file vs a .github/agents/ file side by side. The naming difference becomes immediately obvious.