Skip to content

docs(publishing): troubleshooting for DNS/HTTP auth (#845)#1268

Open
rhinocap wants to merge 1 commit intomodelcontextprotocol:mainfrom
rhinocap:rav-99-publisher-cli-auth-devex
Open

docs(publishing): troubleshooting for DNS/HTTP auth (#845)#1268
rhinocap wants to merge 1 commit intomodelcontextprotocol:mainfrom
rhinocap:rav-99-publisher-cli-auth-devex

Conversation

@rhinocap
Copy link
Copy Markdown

@rhinocap rhinocap commented May 8, 2026

Summary

Adds a Troubleshooting DNS and HTTP authentication section to the publishing authentication guide. Patterned after #1253 (my prior docs fix in the same file): docs-only, focused on the recurring failure modes that bottom out as a generic signature verification failed or no MCP public key found error.

Motivated by #845 (improve CLI/TUI experience for DNS/HTTP auth) and the recurring confusion around DNS apex/selector placement called out in #1126. The full TUI work in #845 is a larger lift; this is the docs slice that lets people self-diagnose today using the tools they already have (dig, curl).

The new section covers, in order:

  1. Comparing the CLI's "Expected proof record" against what's actually published — the most common cause of false-fail loops, especially after rotating keys.
  2. DNS: verifying the TXT record with dig before logging in — distinguishes missing / stale / misplaced records, and notes the existing misplaced-selector probe added for DNS authentication always fails: Ed25519 signature verification failed #1126 (so users know what error shape to expect).
  3. HTTP: verifying /.well-known/mcp-registry-auth with curl -i — plus the four constraints baked into the server-side fetcher in internal/api/handlers/v0/auth/http.go: HTTPS only, no redirects (the fetcher returns http.ErrUseLastResponse from CheckRedirect), MaxKeyResponseSize = 4096 byte cap, and the safeDialContext blocklist of loopback / RFC1918 / link-local / CGNAT IPs.
  4. Algorithm vs key mismatch--algorithm must match the published k= field.

Nothing new in code; the existing apex/selector <Warning> (already in the file) and the OpenSSL 3.x <Note> from #1253 are untouched.

Test plan

  • git diff --stat confirms a single-file docs change (docs/modelcontextprotocol-io/authentication.mdx, +48/-0).
  • Verified the documented HTTP constraints against internal/api/handlers/v0/auth/http.go: MaxKeyResponseSize = 4096, CheckRedirect returning ErrUseLastResponse, safeDialContext IP blocklist, https:// URL construction, strings.TrimSpace of the body.
  • Verified the documented DNS misplaced-selector behavior against internal/api/handlers/v0/auth/dns.go (commonWrongSelectors = ["_mcp-auth", "_mcp-registry"], findMisplacedSelector probe).
  • Verified the "Expected proof record" output line is what cmd/publisher/auth/common.go actually prints (PrintEd25519KeyInfo / printEcdsaKeyInfo).
  • Markdown rendering of <CodeGroup> / fenced blocks — relying on the existing patterns in this file for syntax validity, no new MDX components introduced.

Continuing the publisher-devex thread from #1253. Happy to split or trim if maintainers prefer a smaller surface area.

…ocol#845)

Add a Troubleshooting section to the publishing authentication guide
covering the most common failure modes integrators hit during DNS- and
HTTP-based publisher login. Patterned after modelcontextprotocol#1253: docs-only, no code
changes, focused on the gaps that produce a generic "signature
verification failed" error.

Covers:
- Comparing the CLI's "Expected proof record" output against what is
  actually published (the most frequent cause of false-fail loops).
- DNS: verifying TXT propagation with dig, distinguishing missing /
  stale / misplaced records, and noting the registry's misplaced-
  selector probe (modelcontextprotocol#1126).
- HTTP: verifying /.well-known/mcp-registry-auth with curl, plus the
  HTTPS-only / no-redirects / 4096-byte-cap / public-IP-only constraints
  that are enforced by the server fetcher.
- Algorithm/key mismatch when --algorithm differs from the published
  k= field.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant