## Summary
The DNS and HTTP authentication guides currently run `openssl genpkey
-algorithm Ed25519 -out key.pem` without caveat. macOS ships LibreSSL as
the system `openssl` binary, and LibreSSL doesn't implement Ed25519 in
`genpkey` — so the very first command in the Ed25519 codepath errors out
with:
```
Algorithm Ed25519 not found
```
A first-time integrator on macOS hits this immediately, with no path to
a fix from the docs alone. Cost me ~5 minutes earlier today before I
figured out I needed `brew install openssl@3` and an explicit binary
path.
This PR adds a `<Note>` callout to the **DNS Authentication** section
right above the Ed25519 codepath, and a shorter cross-reference Note in
the **HTTP Authentication** section since the same `openssl genpkey
-algorithm Ed25519` commands appear there. The ECDSA P-384 codepath
works on LibreSSL, so it's untouched.
## Test plan
- [x] Verified locally that `/opt/homebrew/opt/openssl@3/bin/openssl
genpkey -algorithm Ed25519 -out key.pem` works on macOS Darwin 25.4.0
- [x] Verified the system `/usr/bin/openssl genpkey -algorithm Ed25519
-out key.pem` fails with `Algorithm Ed25519 not found` on the same
machine (LibreSSL 3.3.6)
- [x] Verified the published `ai.ravenmcp/raven-mcp` flow end-to-end
with the OpenSSL 3 binary
- [ ] Markdown rendering of the `<Note>` callouts — relying on the
existing `<Note>` pattern in this file (line 6) to validate the syntax
Co-authored-by: Radoslav Dimitrov <radoslav@stacklok.com>
## Summary
DNS auth users have repeatedly hit two failure modes that both produce
the same opaque "Ed25519 signature verification failed" error, making
them indistinguishable to debug. This PR makes both diagnosable
end-to-end without changing the auth protocol or any successful path.
The two recurring failure modes:
1. **Wrong placement** — TXT record put under a selector
(`_mcp-auth.<domain>` or `_mcp-registry.<domain>`) instead of the apex.
DKIM-style intuition, but MCP DNS auth uses SPF-style apex placement.
See #385 (PR #388 fixed the docs but the failure recurred), #1103,
#1126.
2. **Stale apex record** — old TXT record left behind after a key
rotation, silently tried first and rejected.
## Changes
**`internal/api/handlers/v0/auth/dns.go`** — when the apex has no
`v=MCPv1` record, probe `_mcp-auth.<domain>` and
`_mcp-registry.<domain>` in parallel (2s individual timeout). If a
record is found there, return a targeted error pointing the user at the
apex. Costs zero extra DNS work in the success path.
**`internal/api/handlers/v0/auth/common.go`** — when verification fails
against records that *are* present, include short fingerprints of every
key the registry tried (`ed25519:YJLsHFhu`-style 8-char prefix). A new
`ErrSignatureMismatch` sentinel keeps structural errors (wrong signature
size, unsupported algorithm) passing through unchanged via `errors.Is`,
so existing assertions on those messages still hold.
**`docs/modelcontextprotocol-io/authentication.mdx`** — anti-pattern
`<Warning>` callout in the DNS section explicitly warning against
selector placement and stale records.
**Tests** — two new tests:
- `TestDNSAuthHandler_WrongSelectorProbe` — verifies the probe surfaces
records found at `_mcp-auth.` / `_mcp-registry.` and falls through to
the standard error when nothing is found anywhere
- `TestDNSAuthHandler_StaleKeyFingerprintInError` — verifies the
fingerprint hint appears in the failure message for #1126's exact
scenario
One existing test assertion was updated from a generic `"signature
verification failed"` substring to the more specific `"invalid signature
size for ECDSA P-384"` it should always have been asserting; the new
sentinel-based logic surfaces structural errors verbatim.
## Test plan
- [x] `make lint` — clean
- [x] `make test-unit` — all auth tests pass (existing + 2 new)
- [x] Verified existing single-key and multi-key paths preserve their
original (more specific) error messages where they were already specific
- [ ] Reviewer to sanity-check the docs callout renders well in the
Mintlify theme
## Out of scope
The publisher-side preflight DNS check (cross-link in #845) is
intentionally **not** in this PR — that belongs in the broader CLI UX
work tracked by #845.
Refs #845, #385, #1103Fixes#1126
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add a `<Note>` component to all MDX files in
`docs/modelcontextprotocol-io/` informing readers that the MCP Registry
is currently in preview and that breaking changes or data resets may
occur before general availability.
The note also directs users to report issues on GitHub at
https://github.com/modelcontextprotocol/registry/issues
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This PR reorganizes and extends the existing documentation in
preparation for publishing on https://modelcontextprotocol.io/.
The current plan is for docs to remain in this repo, and be synced to
the `modelcontextprotocol/modelcontextprotocol` whenever necessary
(e.g., accompanying a release of the registry). I have included a script
in
https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1725
(`bin/pull-registry-docs.sh`) that can be run manually to perform the
sync.
If we later decide to permanently move the docs to the
`modelcontextprotocol/modelcontextprotocol` repo, that also works.
This PR puts all https://modelcontextprotocol.io/ docs into
`docs/modelcontextprotocol-io/`. Docs outside that subdirectory, such as
`docs/administration/admin-operations.md`, are intended to be accessible
solely via this repo. One major exception is the
`docs/reference/server-json/` subdirectory, which will depend on the
resolution of
https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649.
However, I think we could address that in a follow-up PR.
---------
Co-authored-by: Adam Jones <adamj+git@anthropic.com>
Co-authored-by: Claude <noreply@anthropic.com>
