# 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. Last verified against MCP specification 2026-07-28: Tools on 2026-11-18.

## Error message you’ll see

```text
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: https://github.com/modelcontextprotocol/typescript-sdk/blob/951fe5603a7ec0b2dcb6a0b95d92cd86f93ad9e5/packages/core-internal/src/shared/toolNameValidation.ts#L92

```text
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: https://github.com/docker/mcp-gateway/issues/434

## 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](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#tool-names)

## 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

```ts
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"
```

## 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](https://isokron.ai/mcp-check/checks/spec-name-length)
- [Tool names of 64 characters or fewer](https://isokron.ai/mcp-check/checks/anthropic-name-length)
- [No look-alike letters from other scripts](https://isokron.ai/mcp-check/checks/sec-homoglyph)
- [MCP tool names](https://isokron.ai/mcp-check/checks/names)

Counts toward: MCP specification 2026-07-28.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
