docs(publishing): troubleshooting for DNS/HTTP auth (#845)#1268
Open
rhinocap wants to merge 1 commit intomodelcontextprotocol:mainfrom
Open
docs(publishing): troubleshooting for DNS/HTTP auth (#845)#1268rhinocap wants to merge 1 commit intomodelcontextprotocol:mainfrom
rhinocap wants to merge 1 commit intomodelcontextprotocol:mainfrom
Conversation
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 failedorno MCP public key founderror.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:
digbefore 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)./.well-known/mcp-registry-authwithcurl -i— plus the four constraints baked into the server-side fetcher ininternal/api/handlers/v0/auth/http.go: HTTPS only, no redirects (the fetcher returnshttp.ErrUseLastResponsefromCheckRedirect),MaxKeyResponseSize = 4096byte cap, and thesafeDialContextblocklist of loopback / RFC1918 / link-local / CGNAT IPs.--algorithmmust match the publishedk=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 --statconfirms a single-file docs change (docs/modelcontextprotocol-io/authentication.mdx, +48/-0).internal/api/handlers/v0/auth/http.go:MaxKeyResponseSize = 4096,CheckRedirectreturningErrUseLastResponse,safeDialContextIP blocklist,https://URL construction,strings.TrimSpaceof the body.internal/api/handlers/v0/auth/dns.go(commonWrongSelectors = ["_mcp-auth", "_mcp-registry"],findMisplacedSelectorprobe).cmd/publisher/auth/common.goactually prints (PrintEd25519KeyInfo/printEcdsaKeyInfo).<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.