shareAI-lab/learn-claude-code · error · ValueError

MCP tool name is longer than 64 characters: {prefixed}

Error message

MCP tool name is longer than 64 characters: {prefixed}

What it means

When the host harness merges MCP client tools into its tool table it prefixes each name as mcp__<server>__<tool> and enforces a 64-character limit matching the model's tool-name alphabet. A longer name is rejected with ValueError at wiring time because the upstream model API would reject or truncate it later.

Source

Thrown at s15_integrated_harness/code.py:2552

            f"Discovered {len(mcp_client.tools)} tools: {', '.join(tool_names)}")


def assemble_tool_pool() -> tuple[list[dict], dict]:
    """Merge builtin tools + all MCP tools into one pool."""
    global mcp_tool_policies
    tools = list(BUILTIN_TOOLS)
    handlers = dict(BUILTIN_HANDLERS)
    policies: dict[str, str] = {}
    origins = {tool["name"]: f"built-in tool {tool['name']!r}"
               for tool in tools}
    for server_name, mcp_client in mcp_clients.items():
        safe_server = normalize_mcp_name(server_name)
        for tool_def in mcp_client.tools:
            raw_name = tool_def["name"]
            safe_tool = normalize_mcp_name(raw_name)
            prefixed = f"mcp__{safe_server}__{safe_tool}"
            if len(prefixed) > 64:
                raise ValueError(
                    f"MCP tool name is longer than 64 characters: {prefixed}"
                )
            origin = f"MCP tool {server_name!r}/{raw_name!r}"
            if prefixed in origins:
                raise ValueError(
                    "MCP tool name collision after normalization: "
                    f"{prefixed!r} maps both {origins[prefixed]} and {origin}"
                )
            schema = tool_def.get("inputSchema", {})
            if not isinstance(schema, dict) or schema.get("type", "object") != "object":
                raise ValueError(f"Invalid input schema for {origin}")
            origins[prefixed] = origin
            tools.append({
                "name": prefixed,
                "description": tool_def.get("description", ""),
                "input_schema": schema,
            })
            handlers[prefixed] = (

View on GitHub (pinned to 985456f4ad)

Solutions

1. Shorten the server alias used as the dict key when registering mcp_clients (e.g. 'docs' instead of 'documentation-service-prod')
2. Shorten the tool name in the MCP server's tool_defs
3. Compute the prefixed length in a pre-flight check before starting the harness

Example fix

# before
mcp_clients = {
    "internal_documentation_services": docs_client,  # tool 'search_all_namespaces' -> 5+29+2+20 = too long
}

# after
mcp_clients = {
    "docs": docs_client,  # mcp__docs__search_all_namespaces fits in 64
}

def fits_tool_name_budget(server: str, tool: str) -> bool:
    return len(f"mcp__{server}__{tool}") <= 64

for server_name, client in mcp_clients.items():
    for tool in client.tools:
        assert fits_tool_name_budget(server_name, tool), f"{server_name}/{tool} too long"

def is_within_mcp_name_limit(server: str, tool: str) -> bool:
    return isinstance(server, str) and isinstance(tool, str) and len(f"mcp__{server}__{tool}") <= 64

try:
    harness = build_harness(mcp_clients)
except ValueError as exc:
    if "longer than 64 characters" in str(exc):
        # shorten the server alias or tool name, then rebuild
        raise SystemExit(str(exc)) from exc
    raise

When it happens

Trigger: Registering a server with a long name (e.g. 'internal-documentation-services') plus a long tool name (e.g. 'search_across_all_namespaces') so that 5 + len(server) + 2 + len(tool) > 64. Note normalization can grow names: each disallowed character becomes '_' (1:1), but names near the limit tip over once prefixed.

Common situations: Connecting enterprise MCP servers whose names mirror hostnames or service FQDNs. Teams renaming tools descriptively (verb_object_qualifier) over time until the budget is exceeded.

Related errors

• MCP names cannot normalize to an empty string
• MCP tool name collision after normalization: {prefixed!r} ma
• Max 20 todos
• Max 20 todos allowed
• Every MCP tool needs a non-empty name

AI-assisted analysis of shareAI-lab/learn-claude-code@985456f4ad (2026-08-14). Data as JSON: /api/errors/72b9ba92b62cf7af. Report an issue: GitHub.