[Discussion] Tool name prefix strategy to avoid 64-character limit in Claude API

[sgaluza]

Context

When using MetaMCP with Claude Code (and potentially other MCP clients), tool names can exceed the 64-character limit enforced by Claude API for tool_reference.tool_name.

How tool names are constructed

Claude Code:  mcp__{clientServerName}__
MetaMCP:                              {serverName}__{toolName}

Example:

mcp__my-company-notion__my-company-notion__search_documents
     └── client config ┘  └─ MetaMCP prefix ┘

Problem: The server name often appears twice — once from the client config, once from MetaMCP prefix. This duplication wastes characters.

Current workaround

Users can use short aliases in their client config:

{
  "notion": {
    "url": "https://mcp.example.com/metamcp/my-company-notion/mcp"
  }
}

Result: mcp__notion__my-company-notion__search_documents (48 chars) ✅

However, this requires manual configuration on the client side.

Discussion points

1. Is the server prefix necessary?

MetaMCP adds {serverName}__ to disambiguate tools when multiple servers have tools with the same name.

Question: How common is this scenario? Should the prefix be:

• Always added (current behavior)
• Only added when there's a name collision
• Configurable per server/namespace

2. Possible solutions

Option	Description	Breaking change?
A. Tool prefix alias	Add optional toolPrefix field to MCP Server settings	No (opt-in)
B. Smart prefix	Only add prefix when tool names collide	Yes
C. Disable prefix option	Checkbox to disable prefix entirely	No (opt-in)
D. Auto-short prefix	Truncate + hash: my-company-notion → mcn_a1b2	Yes

3. Where should this be configured?

• Per MCP Server (default prefix for all namespaces)
• Per Namespace-Server mapping (different prefix per namespace)
• Global setting

Additional context

• Claude API tool_reference.tool_name limit: 64 characters (not increased to 128 like tools.custom.name)
• MCP specification (SEP-986) recommends 1-64 character tool names
• Other clients (Cursor) report 60-character limits

Related

• Claude Code issues: #2412, #2485
• MetaMCP nested tool names: [Bug] MetaMCP nested tool names no longer work after 2.4.15 #184, Fix nested MetaMCP tool name parsing #185