registry icon indicating copy to clipboard operation
registry copied to clipboard
Published 2 days ago • verified publisher icon modelcontextprotocol

Move Registry docs over to modelcontextprotocol.io

Open tadasant opened this issue 3 months ago • 2 comments

From @dsp-ant:

... I want to make sure people understand that the registry exists and how to use it, by visiting modelcontextprotocol.io ...

From @domdomegg:

I think the docs should move to modelcontextprotocol.io in the long term, or failing that then something like registry.modelcontextprotocol.io/docs.

The current state works, but is pretty janky to navigate around in the GitHub UI. And it's poor for SEO (which hurts both things like Google search, and models being able to read it).

To explain why it's there right now, for velocity we found keeping the docs together with registry code was helpful - and meant you could align code + docs changes, and don't have to get a docs maintainer stamp on each corresponding docs change. There were also concerns from theo and others I think about it being on the main docs site making it more formal, and maybe being inappropriate for a preview launch. Plus just questions about whether it should be it's own category of docs, some subpart somewhere else, whether the specs should go under the 'specification' tab and a whole bunch of other Qs that dragged it out longer and we didn't want to block on these to preview launch.

dsp-ant:

Yeah totally. I would love all docs to live in modelcontextprotocol.io or registry.modelcontextprotocol.io. Just let me know waht you prefer. Agreed on velocity and stuff. It's a bit annoying to have it in a separate repo, but oh well

domdomegg:

Yeah. Uncertain if a terrible idea that overcomplicates things (quite plausibly) but potentially one-way syncing changes from registry => modelcontextprotocol/docs might mean we get some of the benefits of being able to review code + docs changes together.

Another easier alternative is just to move docs there completely, and put them all under paths where CODEOWNERS allows registry-wg team to approve, rather than blocking on docs maintainers. And have it be a norm that when reviewing/merging the code PR you also review/merge the docs PR.

@rdimitrov:

I also think keeping the docs in the repo helps keep things in sync from both maintainer and contributor perspective 👍

That said, would it work if the sync from registry to docs happens automatically on every registry release by opening a PR against mcp/docs?

References:

  • https://discord.com/channels/1358869848138059966/1369487942862504016/1416005469230727290
  • https://discord.com/channels/1358869848138059966/1369487942862504016/1420151416332226562

Pulling this into an Issue as the full scope of achieving the final state here is likely a larger chunk of work I'm not sure exactly when we'll prioritize bringing to completion.

tadasant avatar Sep 24 '25 01:09 tadasant

I put together a rough sketch of what I think should appear under a new "Registry" tab on https://modelcontextprotocol.io/:

And then the following docs would be viewable only within this repo:

Does that align with what most people are thinking?

I also think keeping the docs in the repo helps keep things in sync from both maintainer and contributor perspective 👍

That said, would it work if the sync from registry to docs happens automatically on every registry release by opening a PR against mcp/docs?

One additional point is that the "Registry" tab would not be versioned. (Unless we want it to be?) So if there are unreleased changes to the registry and corresponding changes to the docs that we don't want to go live yet, then we would need some sort of sync process. (Perhaps a git subtree?)

jonathanhefner avatar Oct 17 '25 21:10 jonathanhefner

Thank you @jonathanhefner for fleshing this out!

Generally, agree with your direction.

[explanation] About server.json docs/reference/server-json/generic-server-json.md ...or put this under the "Specification" tab instead, as part of https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649?

This is a big unknown for me at the moment. If we assume SEP-1649 moves quickly and aligns well with server.json, then yes I think we can scrap the registry's notion of server.json and just point to the spec directly. That does mean we lose a lot of control over iterating on it (every tweak will need to be a SEP), but I think that's the right move here. cc @domdomegg @rdimitrov @toby

One additional point is that the "Registry" tab would not be versioned. (Unless we want it to be?) So if there are unreleased changes to the registry and corresponding changes to the docs that we don't want to go live yet, then we would need some sort of sync process. (Perhaps a git subtree?)

I think it'd be reasonable for us to keep it unversioned, and just open draft PRs that we land at the same time we do a release. A little clunky but I don't think we change docs that much? Especially if server.json moves in the spec. We could automate / do fancy sub-tree stuff if it becomes a pain point and we see where friction is in practice.

tadasant avatar Oct 18 '25 13:10 tadasant