Prepare docs for modelcontextprotocol.io (#728)

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>

docs/modelcontextprotocol-io/registry-aggregators.mdx

@@ -0,0 +1,106 @@
+---
+title: MCP Registry Aggregators
+sidebarTitle: Registry Aggregators
+---
+
+Aggregators are downstream consumers of the MCP Registry that provide additional value. For example, a server marketplace that provides user ratings and security scanning.
+
+The MCP Registry provides an unauthenticated read-only REST API that aggregators can use to populate their data stores. Aggregators are expected to scrape data on a regular but infrequent basis (e.g., once per hour), and persist the data in their own data store. The MCP Registry **does not provide uptime or data durability guarantees**.
+
+## Consuming the MCP Registry REST API
+
+The base URL for the MCP Registry REST API is `https://registry.modelcontextprotocol.io`. It supports the following endpoints:
+
+- [`GET /v0.1/servers`](https://registry.modelcontextprotocol.io/docs#/operations/list-servers-v0.1) — List all servers.
+- [`GET /v0.1/servers/{serverName}/versions`](https://registry.modelcontextprotocol.io/docs#/operations/get-server-versions-v0.1) — List all versions of a server.
+- [`GET /v0.1/servers/{serverName}/versions/{version}`](https://registry.modelcontextprotocol.io/docs#/operations/get-server-version-v0.1) — Get a specific version of a server. Use the special version `latest` to get the latest version of the server.
+
+<Warning>
+
+URL path parameters such as `serverName` and `version` **must** be URL-encoded. For example, `io.modelcontextprotocol/everything` must be encoded as `io.modelcontextprotocol%2Feverything`.
+
+</Warning>
+
+Aggregators will most likely scrape the `GET /v0.1/servers` endpoint.
+
+### Pagination
+
+The `GET /v0.1/servers` endpoint supports cursor-based pagination.
+
+For example, the first page can be fetched using a `limit` query parameter:
+
+```bash
+curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100"
+```
+
+```jsonc Output highlight={5}
+{
+  "servers": [
+    /* ... */
+  ],
+  "metadata": {
+    "count": 100,
+    "nextCursor": "com.example/my-server:1.0.0",
+  },
+}
+```
+
+Then subsequent pages can be fetched by passing the `nextCursor` value as the `cursor` query parameter:
+
+```bash
+curl "https://registry.modelcontextprotocol.io/v0/servers?limit=100&cursor=com.example/my-server:1.0.0"
+```
+
+### Filtering Since
+
+The `GET /v0.1/servers` endpoint supports filtering servers that have been updated since a given timestamp.
+
+For example, servers that have been updated since 2025-10-23 can be fetched using an `updated_since` query parameter in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) date-time format:
+
+```bash
+curl "https://registry.modelcontextprotocol.io/v0.1/servers?updated_since=2025-10-23T00:00:00.000Z"
+```
+
+## Server Status
+
+Server metadata is generally immutable, except for the `status` field which may be updated to, e.g., `"deprecated"` or `"deleted"`. We recommend that aggregators keep their copy of each server's `status` up to date.
+
+The `"deleted"` status typically indicates that a server has violated our permissive [moderation policy](./moderation-policy.mdx), suggesting the server might be spam, malware, or illegal. Aggregators may prefer to remove these servers from their index.
+
+## Acting as a Subregistry
+
+A subregistry is an aggregator that also implements the [OpenAPI spec](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/openapi.yaml) defined by the MCP Registry. This allows clients, such as MCP host applications, to consume server metadata via a standardized interface.
+
+The subregistry OpenAPI spec allows subregistries to inject custom metadata via the `_meta` field. For example, a subregistry could inject user ratings, download counts, and security scan results:
+
+```json server.json highlight={17-26}
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
+  "name": "io.github.username/email-integration-mcp",
+  "title": "Email Integration",
+  "description": "Send emails and manage email accounts",
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@username/email-integration-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ],
+  "_meta": {
+    "com.example.subregistry/custom": {
+      "user_rating": 4.5,
+      "download_count": 12345,
+      "security_scan": {
+        "last_scanned": "2025-10-23T12:00:00Z",
+        "vulnerabilities_found": 0
+      }
+    }
+  }
+}
+```
+
+We recommend that custom metadata be put under a key that reflects the subregistry (e.g., `"com.example.subregistry/custom"` in the above example).