Watch

Jonathan Hefner 43d41a242e

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>

2025-11-18 17:22:31 +00:00

1.9 KiB

Raw Permalink Blame History

MCP Registry Design Principles

These are the core constraints that guide the design of the MCP Registry. They are not exhaustive, but they are the most important principles that we will use to evaluate design decisions.

1. Single Source of Truth

The registry serves as the authoritative metadata repository for publicly-available MCP servers, both locally-run and remote, open source and closed source. Server creators publish once, and all consumers (MCP clients, aggregators, etc.) reference the same canonical data.

2. Minimal Operational Burden

Design for low maintenance and operational overhead
Delegate complexity to existing services where possible (GitHub for auth, npm/PyPI/NuGet for packages)
Avoid features that require constant human intervention or moderation
Build for reasonable downtime tolerance (24h acceptable) by having consumers cache data for their end-users

3. Vendor Neutrality

No preferential treatment for specific servers or organizations
No built-in ranking, curation, or quality judgments
Let consumers (MCP clients, aggregators) make their own curation decisions

4. Meets Industry Security Standards

Leverage existing package registries (npm, PyPI, NuGet, Docker Hub, etc.) for source code distribution, obviating the need to reinvent source code security
Use mechanisms like DNS verification, OAuth to provide base layer of authentication and trust
Implement rate limiting, field validation, and blacklisting to prevent abuse

6. Reusable, Extensible Shapes; Not Infrastructure

API shapes (OpenAPI, server.json) designed for reuse
Enable private/internal registries using same formats
Don't mandate infrastructure reuse - focus on interface compatibility

7. Progressive Enhancement

Start with MVP that provides immediate value
Build foundation that supports future features
Don't over-engineer for hypothetical needs
Each milestone should be independently valuable

1.9 KiB Raw Permalink Blame History