Skip to content
IsoKron

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

Error
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

Error
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 (.)

Source: MCP specification 2026-07-28: Tools

How to fix it

Replace other characters with underscores, for example "create issue" becomes "create_issue".

  1. Replace spaces, slashes and other characters with underscores: "create issue" becomes create_issue.
  2. Prefer underscores to dots if the server must work in Claude, whose pattern has no dot.
  3. Keep the human-readable form in the title field instead.

TypeScript SDK

TypeScript
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

Python
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.

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