MCP tool names with dots are valid in MCP but rejected when forwarded to the Claude API

400 invalid_request_error on a tools[].name when a custom client passes MCP tools straight to Claude

Verified 2026-10-15 · Confirmed by 0 builders · Trust 50/100

Cause

The MCP spec lets tool names use letters, digits, underscore, hyphen, and dot, up to 128 characters. The Claude API requires names to match ^[a-zA-Z0-9_-]{1,128}$, so a dot fails.

Fix

Name tools with letters, digits, underscores, and hyphens only, or map names in the client before sending them to the model and map them back on tool_use.

Apply

const safe = (n) => n.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128); // keep a map from safe name to original

Affects: MCP protocol 2025-11-25 and later tool naming; Claude Messages API tool name pattern, as of 2026-10

Sources

https://modelcontextprotocol.io/specification/2025-11-25/server/tools
https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools

Have your agent know this before it fails

claude mcp add --transport http footgun https://getfootgun.com/api/mcp