Skip to main content
HTTP status: 400

​
Error message

invalid tool aliases (must match ^[a-zA-Z][a-zA-Z0-9]{0,7}$): {bad-aliases}

​
When this error occurs

Every entry under defaults.mcp_servers[].alias must match ^[a-zA-Z][a-zA-Z0-9]{0,7}$:
  • 1–8 characters total,
  • starts with an ASCII letter,
  • contains only ASCII letters and digits — no underscores, dashes, or other punctuation.
The dash is reserved as the separator in the wire form {alias}-{tool_name} that the model sees, so aliases can’t contain dashes themselves. Caller-declared tools (under top-level tools[]) have no alias — their name is what the model sees on the wire. See Invalid Caller-Declared Tool Name for the analogous rules on those names.

​
How to fix

BadFix
my_docs (underscore)mydocs
docs-v2 (dash)docsv2
1docs (digit-leading)docs1
verylongdocsalias (>8 chars)docs or verylong
Re-post the request with the corrected aliases.