`claude mcp add` fails to parse bracketed IPv6 URLs

Resolved 💬 2 comments Opened Mar 4, 2026 by shigechika Closed Mar 4, 2026

Description

claude mcp add with HTTP transport fails to parse IPv6 URLs that use standard bracket notation (RFC 2732 / RFC 6874). The CLI reports error: missing required argument 'commandOrUrl' even though the URL is valid.

Steps to Reproduce

claude mcp add --transport http my-server 'https://[2001:db8::1]:8080/mcp'
# error: missing required argument 'commandOrUrl'

Also fails with other bracket forms:

claude mcp add --transport http my-server 'https://[::1]:8080/mcp'
# error: missing required argument 'commandOrUrl'

Expected Behavior

The command should accept bracketed IPv6 URLs and add the server configuration, just as it does for IPv4 or hostname-based URLs:

# These work fine:
claude mcp add --transport http my-server 'https://example.com:8080/mcp'
claude mcp add --transport http my-server 'https://192.168.1.1:8080/mcp'

Actual Behavior

The CLI fails with error: missing required argument 'commandOrUrl'. The brackets in the IPv6 address appear to confuse the argument parser.

Workaround

Manually edit ~/.claude.json to add the server configuration:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://[2001:db8::1]:8080/mcp"
    }
  }
}

The MCP client itself handles IPv6 URLs correctly once configured — only the CLI add subcommand has the parsing issue.

Environment

  • Claude Code: latest (installed via npm)
  • macOS (both Apple Silicon and Intel)

Related

Split out from #29562, which also covers the custom headers issue tracked in #28293.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗