Dotted tool names violate Anthropic API regex `^[a-zA-Z0-9_-]{1,64}$` — breaks Claude Desktop and any Anthropic-API client

[borisbauer-digital]

Summary

Every tool exposed by @automatelab/citation-intelligence uses a dot in its name (citations.predict, domain.am_i_cited, audit.schema, etc.). The Anthropic API enforces a tool name pattern of ^[a-zA-Z0-9_-]{1,64}$ — letters, digits, hyphens, underscores only, no dots. When any Anthropic-API-based MCP client (Claude Desktop, Claude Code, etc.) forwards this server's tool list to the API, the API returns HTTP 400 and the model can't be invoked.

The server itself starts cleanly and the JSON-RPC handshake succeeds — failure happens later, at message time, on the API side. From the user's perspective the MCP appears to install and load correctly, then errors the moment a tool is invoked.

Steps to reproduce

1. Install per the README in Claude Desktop:

   "citation-intelligence": {
     "command": "npx",
     "args": ["-y", "@automatelab/citation-intelligence"],
     "env": { "ANTHROPIC_API_KEY": "...", "GEMINI_API_KEY": "...", "SERPAPI_KEY": "..." }
   }

2. Restart Claude Desktop. MCP loads successfully — all 24 tools register.
3. Ask Claude to use any tool (e.g. citations.predict on a URL).
4. Claude Desktop surfaces an API error and the tool never runs.

Actual behavior

Error returned by Claude Desktop on tool invocation:

tools.209.FrontendRemoteMcpToolDefinition.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}$'

The MCP server log confirms it served the tools list correctly and the failure is not server-side:

[citation-intelligence] info: server ready on stdio {"version":"0.9.3","tools":["citations.check","citations.predict",...]}

Root cause

Anthropic's tool name pattern is ^[a-zA-Z0-9_-]{1,64}$. Dots are not in the character class. Every one of this server's 24 tools fails:

citations.check          citations.predict        citations.trend
citations.provenance     citations.evidence       citations.freshness
domain.am_i_cited        domain.cited_for         domain.cited_for_diff
panel.track              panel.run
competitors.compare      competitors.compete      competitors.canonical_set
signals.ai_overview      signals.answer_box       signals.wikipedia        signals.gsc_gap
audit.sitemap            audit.sitemap_map        audit.crawler_access
audit.schema             audit.llms_txt           audit.structured_data

Prompt names have the same problem: audit.citation_readiness, audit.competitor_snapshot, audit.crawler_checkup, audit.gap_analysis, audit.sitemap_coverage.

Expected behavior

Tools usable in any Anthropic-API-based MCP client without error.

Suggested fix

Rename dots to underscores in the name field returned by the server: citations.predict → citations_predict, domain.am_i_cited → domain_am_i_cited. The namespace grouping for human readability can be preserved in the README, tool descriptions, and any client-facing documentation — only the wire-level name value needs to change. This is the convention used by most published MCP servers (github_create_issue, slack_send_message, etc.) and satisfies Anthropic's pattern without changing tool semantics.

Affected clients

Anything that forwards tool definitions to the Anthropic API:

• Claude Desktop — this report
• Claude Code — [BUG] MCP server name containing dot causes API error anthropics/claude-code#1538
• Zed — AI: Cant use ZED at all since Anthropic API Error Sting should match pattern all the time zed-industries/zed#40928
• Home Assistant — Anthropic with MCP erroring: 'error': {'type': 'invalid_request_error', 'message': "tools.0.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,128}$'"} home-assistant/core#147760
• Any custom client using the Anthropic Messages API with tool use

Clients that don't go through Anthropic's API (Cursor with OpenAI models, Open WebUI with non-Anthropic backends, etc.) are unaffected — the dotted names work fine in those.

Environment

• @automatelab/citation-intelligence 0.9.3
• Claude Desktop (Windows)
• Node v22.21.1
• npm 10.9.4