Allowed characters in MCP tool names
Tool names should use only A-Z, a-z, 0-9, underscore, hyphen and dot (SEP-986); spaces, slashes, commas and non-ASCII letters break clients that turn names into identifiers.
Check spec-name-charset · MCP specification 2026-07-28 · default severity: attention · rubric 2.1.0
Error message you’ll see
Tool name validation warning for "create issue":
- Tool name contains spaces, which may cause parsing issues
- Tool name contains invalid characters: " "
- Allowed characters are: A-Z, a-z, 0-9, underscore (_), dash (-), and dot (.)
Tool registration will proceed, but this may cause compatibility issues.TypeScript SDK 2.4.0 when the tool is registered (the Python SDK logs the same warnings). Where this message comes from
tools.275.FrontendRemoteMcpToolDefinition.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}$'Claude Desktop, when a connected server lists the name. Where this was reported
What fails
Spaces, commas, slashes and non-ASCII letters break clients that build identifiers from tool names, and non-ASCII letters can imitate other names.
The rule
The following SHOULD be the only allowed characters: uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), hyphen (-), and dot (.)
How to fix it
Replace other characters with underscores, for example "create issue" becomes "create_issue".
- Replace spaces, slashes and other characters with underscores: "create issue" becomes create_issue.
- Prefer underscores to dots if the server must work in Claude, whose pattern has no dot.
- Keep the human-readable form in the title field instead.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'create_issue',
{
title: 'Create issue',
description: 'Create one issue in a project. Use when the user asks to file or report something.',
inputSchema: z.strictObject({
project_id: z.string().describe('Project ID, for example PRJ-7'),
title: z.string().describe('Issue title, one line'),
}),
annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
},
async ({ project_id, title }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);Python SDK
from typing import Annotated
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
server = MCPServer("issues")
@server.tool(
title="Create issue",
annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False, openWorldHint=False),
)
def create_issue(
project_id: Annotated[str, Field(description="Project ID, for example PRJ-7")],
title: Annotated[str, Field(description="Issue title, one line")],
) -> str:
"""Create one issue in a project. Use when the user asks to file or report something."""
return "Done"Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.
Questions
Where does the "Tool name contains invalid characters" warning come from?
Both official SDKs validate names against SEP-986 when you register a tool and log this warning, followed by the list of allowed characters. The tool is still registered, but clients may refuse or rename it.
Can a tool name contain a slash, like issues/create?
No. A slash is outside the allowed set, and several clients use it as a separator. Use issues_create.
Related checks
- MCP tool name length: 1 to 128 characters
- Tool names of 64 characters or fewer
- No look-alike letters from other scripts
- All checks in MCP tool names
How this check is graded
It counts toward: MCP specification 2026-07-28. See the rubric.
Last verified against MCP specification 2026-07-28: Tools on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.
Check your tool list: paste your tools/list, nothing is sent anywhere