Two real defects, plus the CLI reference claims that go with them.
## 1. ECDSA P-384 login instructions cannot work
Every "ECDSA P-384" tab ran the *identical* command to the Ed25519 tab.
Since `--algorithm` defaults to ed25519
([login.go:100](https://github.com/modelcontextprotocol/registry/blob/main/cmd/publisher/commands/login.go#L100)),
a 96-hex key is rejected outright. Verified against a freshly generated
P-384 key:
```
$ mcp-publisher login dns --domain=example.com --private-key=$KEY
Signing in process using key algorithm ed25519
Error: failed to get token: failed to sign timestamp: invalid seed length: expected 32 bytes, got 48
$ mcp-publisher login dns --algorithm ecdsap384 --domain=example.com --private-key=$KEY
Signing in process using key algorithm ecdsap384
Expected proof record: # works
```
`--algorithm` is registered at
[login.go:129](https://github.com/modelcontextprotocol/registry/blob/main/cmd/publisher/commands/login.go#L129)
and described correctly by the CLI's own help, but `grep -rn algorithm
docs/` had **zero** hits for it. Anyone following the ECDSA path in the
docs hit that error with nothing to tell them why.
Fixed at all four in-process ECDSA sites (2 in `authentication.mdx`, 2
in `cli/commands.md`), with a note that cloud signing providers derive
the algorithm from the key itself so the flag does not apply to them.
## 2. `mcp-publisher validate --help` was broken
```
$ mcp-publisher validate --help
Unknown command: validate
...
Use 'mcp-publisher <command> --help' for more information about a command.
```
It printed the very instruction that had just failed. `main.go`
intercepted `--help` for all subcommands and called `printCommandHelp`,
whose switch had no `validate` case — making `ValidateCommand`'s own
help block
([validate.go:120-129](https://github.com/modelcontextprotocol/registry/blob/main/cmd/publisher/commands/validate.go#L120))
unreachable.
Rather than paste a third copy of the help text, `printCommandHelp` now
returns whether it handled the command, and the caller falls through to
normal dispatch when it did not. Commands own their own `--help`, and
any future command with this shape works automatically.
| Command | Before | After |
|---|---|---|
| `validate --help` | `Unknown command`, exit 0 | prints its help, exit
0 |
| `publish --help` | works | works |
| `init -h` | works | works |
| `bogus --help` | `Unknown command`, exit 0 | `Unknown command`, **exit
1** |
## 3. CLI reference corrections
- **`--registry` is not global.** It exists only on `login`; other
commands read the URL from the stored token. `publish --registry=URL`
silently treats the flag as the `server.json` path.
`cmd/publisher/README.md` had exactly this broken example.
- **`--token` was undocumented** despite `github-actions.mdx:123`
depending on it. Now documented, noting it is `login github` only.
- **`init` takes no flags** and does not prompt; it writes `TODO:`
placeholders. The reference said `init [options]` and "Prompts for
missing required fields".
- **Refreshed the `--help` transcript** in `quickstart.mdx`, which
listed only 4 of 6 commands. Now byte-for-byte identical to real output
(diffed).
- **Added `validate`** to the command list in `cmd/publisher/README.md`.
## Verification
`go build` and `go test ./cmd/...` pass. All four help paths exercised
with exit codes checked. The 23 `goconst` findings in `validate_test.go`
are pre-existing — identical count on pristine `main`, none in
`main.go`. Quickstart transcript diffed against real output.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
## What
Two targeted additions to `docs/modelcontextprotocol-io/quickstart.mdx`:
1. A `<Note>` immediately after the tutorial's intro, telling PyPI /
NuGet / OCI / MCPB publishers that the Step 1 ownership-verification
mechanism differs for their package type and pointing them to [Package
Types](./package-types) before continuing.
2. The troubleshooting row for **"Registry validation failed for
package"** previously named only npm's `mcpName` property in
`package.json`. It now names all three current mechanisms (npm →
`mcpName` in `package.json`; PyPI / NuGet → `mcp-name: <server-name>`
line in the package README; other types → link to Package Types).
+5 / -1 lines.
## Why
The quickstart is the landing page for new publishers, but it's entirely
TypeScript / npm-flavored — the Step 1 example shows npm's `mcpName`
property and nothing else. The cross-reference to `./package-types` only
appears in the "Next Steps" footer, by which point a PyPI publisher has
already gone through every step and hit a `400 Bad Request` at
`mcp-publisher publish`:
> `registry validation failed for package 0 (<pkg>): PyPI package
'<pkg>' ownership validation failed. The server name
'io.github.<user>/<server>' must appear as 'mcp-name:
io.github.<user>/<server>' in the package README`
That specific error has tripped at least one other publisher (#531) and
was what motivated this change. The ownership mechanism is correctly
documented at `./package-types` — the fix is purely to route people
there before they publish, not to duplicate the content.
## What this change is **not**
- It does not propose changing the validation logic.
- It does not duplicate content from `package-types.mdx` into the
quickstart.
- It does not add a separate PyPI-specific tutorial. The existing
npm-flavored tutorial remains the canonical one; the note just tells
non-npm readers which step is different.
## Verification
- Change is docs-only; no build or test impact.
- Link target `./package-types` is the same shape as the one already
used in "Next Steps" of the same file.
- Anchor `#step-1-add-verification-information-to-the-package` matches
the existing heading's slug.
## Related
- #531 — same validation error hit by another PyPI publisher; closed
with a workaround but the quickstart wasn't updated.
These docs are synced to modelcontextprotocol.io which uses Mintlify for
rendering. Mintlify routes are extension-less, so links like
`./package-types.mdx` produce 404s on the live site. Dropping the `.mdx`
suffix fixes those broken links. The trade-off is that the links no
longer resolve when browsing the raw files on GitHub.
Co-authored-by: Claude Opus 4.6 (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>
- Fix `--private-key-file` to `--private-key` in `github-actions.mdx`
DNS authentication example (the CLI expects hex-encoded key data, not
a file path)
- Add missing `./` prefix to `mcp-publisher` command in PAT
authentication example
- Fix typo `verfication` to `verification` in troubleshooting table
- Remove duplicate word `authentication` in `quickstart.mdx`
prerequisites
- Fix `name` to `identifier` field in JSON examples in `versioning.mdx`
- Fix `PyPi` to `PyPI` (correct capitalization) in
`moderation-policy.mdx`
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Prepared by Claude Code, iterated and reviewed by me.
## Summary
This PR releases the server.json schema version `2025-12-11`,
incorporating URL template variables for remote servers from #570.
### What's New
- **URL Template Variables for Remote Servers** - Remote servers can now
define configurable variables in URLs using `{curly_braces}` notation,
enabling multi-tenant deployments.
### Schema Version
- `2025-10-17` → `2025-12-11`
## Release Sequence
1. ~~**First: Merge static repo PR** -
https://github.com/modelcontextprotocol/static/pull/11 (publishes schema
to versioned URL)~~
2. **Then: Merge this PR** - Updates registry code to reference the new
schema version
## Changes in This PR
- [x] Update CHANGELOG.md with release notes
- [x] Update `CurrentSchemaVersion` in `pkg/model/constants.go`
- [x] Update schema example URL in `docs/reference/api/openapi.yaml`
- [x] Update schema URL in `pkg/api/v0/types.go`
- [x] Update all documentation examples to use new schema version
- [x] Regenerate `server.schema.json`
## Test Plan
- [x] `make check` passes (lint, schema validation, example validation)
- [x] Unit tests pass for validators and publisher commands
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
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>
