Validation Error: Insufficient Context for Tool Name Length Constraint

[jlwainwright]

Enhancement: Improve MCP tool validation error messages with server and tool context

Issue Type

• [x] Enhancement Request
• [ ] Bug Report

Summary

Currently, when MCP tools have names exceeding 64 characters, Claude Code shows generic validation errors without context about which server or tool is problematic. This makes debugging difficult for users with many MCP servers.

Current Behavior

/dart:Create doc (MCP)
⎿ API Error: 400 
  {"type":"error","error":{"type":"invalid_request_error","message":"tools.187.custom.name: String 
  should have at most 64 characters"}}

Problems:

• No indication of which MCP server provides the tool
• No display of the actual problematic tool name
• Requires manual counting to find tool #187
• No guidance on how to fix the issue

Proposed Enhancement

Enhanced Error Message (Example)

❌ MCP Tool Validation Failed

Server: enterprise-database-management
Tool #187: mcp__enterprise-database-management__synchronize-all-customer-data-across-multiple-systems
Length: 90/64 characters (26 over limit)

💡 Suggested name: mcp__ent-db__sync-customer-data

🔧 How to fix:
• Update tool name in 'enterprise-database-management' MCP server configuration
• Use abbreviations: 'db' instead of 'database-management'  
• Remove redundant prefixes where possible

📚 Documentation: https://docs.anthropic.com/claude-code/mcp#tool-naming

Note: The above shows a hypothetical enhanced error message. The actual error only shows "tools.187.custom.name: String should have at most 64 characters" without any context about which server or tool is problematic.

Implementation Benefits

• Immediate Problem Identification: Users know exactly which server/tool is broken
• Actionable Guidance: Clear suggestions for fixing the issue
• Time Savings: No manual tool counting or configuration hunting
• Better UX: Professional error handling with helpful context

Technical Approach

1. Enhanced Validation During Tool Loading

interface ToolValidationError {
  mcpServer: string;
  toolName: string; 
  toolIndex: number;
  actualLength: number;
  maxLength: number;
  suggestedName: string;
}

2. Smart Name Suggestions

• Remove redundant prefixes (mcp__)
• Apply common abbreviations (management → mgmt)
• Truncate intelligently at word boundaries
• Preserve tool functionality clarity

3. Improved CLI Error Display

• Colored output for visibility
• Step-by-step fix instructions
• Links to relevant documentation
• Context about which server to modify

Use Cases

• Enterprise Users: Managing 50+ MCP tools across multiple servers
• Plugin Developers: Testing new MCP servers with descriptive tool names
• Support Teams: Helping users debug MCP configuration issues
• New Users: Learning MCP tool naming best practices

Environment Info

• Platform: darwin
• Terminal: vscode
• Claude Code Version: 1.0.31

Related Error Logs

[
  {
    "error": "Error: Command failed: security find-generic-password -a $USER -w -s \"Claude Code\"\nsecurity: SecKeychainSearchCopyNext: The specified item could not be found in the keychain.\n\n    at genericNodeError (node:internal/errors:983:15)\n    at wrappedFn (node:internal/errors:537:14)\n    at checkExecSyncError (node:child_process:892:11)\n    at execSync (node:child_process:964:15)\n    at NZ (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:700:3921)\n    at file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:622:9014\n    at Q (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:526:17199)\n    at GX (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:622:8160)\n    at fS (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:622:7241)\n    at R9 (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:622:11408)",
    "timestamp": "2025-06-21T11:50:41.045Z"
  },
  {
    "error": "Error: Language not supported while highlighting code, falling back to markdown: \n    at aD (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1472:1184)\n    at file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1472:912\n    at Array.map (<anonymous>)\n    at kK (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1472:903)\n    at DU2 (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1865:7514)\n    at xE (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:80:19803)\n    at mT (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:42555)\n    at gT (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:38104)\n    at qq (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:38032)\n    at eE (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:37886)",
    "timestamp": "2025-06-21T12:08:36.514Z"
  },
  {
    "error": "Error: Language not supported while highlighting code, falling back to markdown: \n    at aD (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1472:1184)\n    at file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1472:912\n    at Array.map (<anonymous>)\n    at kK (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1472:903)\n    at DU2 (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:1865:7514)\n    at xE (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:80:19803)\n    at mT (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:42555)\n    at gT (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:38104)\n    at qq (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:38032)\n    at eE (file:///[USER_PATH]/.claude/local/node_modules/@anthropic-ai/claude-code/cli.js:82:37886)",
    "timestamp": "2025-06-21T12:31:00.242Z"
  }
]

Alternatives Considered

1. Client-side name truncation: Would break tool functionality
2. Warning-only approach: Still allows broken configurations
3. Configuration validation: Doesn't help with runtime errors

Priority

Medium-High - This affects all users with complex MCP setups and significantly improves debugging experience.

Related Issues

• General MCP debugging difficulties
• User confusion about tool validation errors
• Support burden for MCP configuration issues

Additional Context

Bug report submitted via /bug command with Feedback ID: ec6ed713-c23a-46e9-9ede-cba36b616643

[startakovsky]

GitHub Official Image with Docker MCP Toolkit and Claude 1.0.31 gives me this same error pictured below. Here is another issue same pain point.

This issue is nonexistent with Claude Desktop. How can I get around this?

[CXwudi]

I found a workaround for GitHub MCP server, change the MCP server name to something shorter so that the tool name stays within 64 characters, for example, use gh instead of github:

"gh": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": ""
      },
      "type": "stdio"
    }

Then the longest tool would stay within 64 characters:

add_pull_request_review_comment_to_pending_review (gh)                                                               │
│                                                                                                                      │
│ Full name: mcp__gh__add_pull_request_review_comment_to_pending_review

can you test if the github mcp is working?

● I'll test the GitHub MCP by checking what GitHub functionality is available and then trying a simple operation.
  ⎿  {
       "login": "CXwudi",

[ww2283]

the workaround is great but defeat the purpose of using a single central maintained docker gateway mcp server approach. You have to separate the gh from the rest of the swarm.

On the other hand, I highly suggest removing of the prefix for mcp tools. I noticed that in Claude desktop, the tool calling of mcp servers are quite good, while in Claude Code, even with explicit mention of a tool name, CC often says cannot find that tool. This should be relevant to the extensive prefix added for a mcp tool.

[startakovsky]

@ww2283 IMHO this is better stated as a bug in Claude Code rather than an enhancement request by framing it as a failure for the claude mcp add-from-claude-desktop command to work in certain situations and completely freezes up claude code. I have listed this issue here: https://github.com/anthropics/claude-code/issues/2445

[ashwin-ant]

Tool names can now be up to 128 characters. Let me know if this works better!

[startakovsky]

Tool names can now be up to 128 characters. Let me know if this works better!

Yes it does now. Thank you @ashwin-ant .

[github-actions[bot]]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.