modelcontextprotocol/registry
Watch
1
0
Fork
You've already forked registry
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
registry/docs/faq.md
adam jones 7b211a46d6
 feat: implement server versioning approach with semantic versioning support (#296) 
This implements the versioning approach agreed upon in issue #158:

## Key Changes

### Documentation
- Added comprehensive versioning guide (docs/versioning.md)
- Updated FAQ with versioning guidance and best practices 
- Enhanced schema description with SHOULD recommendations

### Schema Updates
- Added 255-character limit for version strings in schema.json
- Enhanced version field description with semantic versioning guidance

### Implementation 
- New isSemanticVersion() function for proper semver detection
- Enhanced compareSemanticVersions() with prerelease support
- Implemented compareVersions() strategy:
  * Both semver: use semantic comparison
  * Neither semver: use timestamp comparison
  * Mixed: semver versions always take precedence
- Updated publish logic to determine "latest" using new strategy
- Added version length validation (255 char max)

### Versioning Strategy
1. Version MUST be string up to 255 characters
2. SHOULD use semantic versioning for predictable ordering
3. SHOULD align with package versions to reduce confusion 
4. MAY use prerelease labels for registry-specific versions
5. Registry attempts semver parsing, falls back to timestamp ordering
6. Clients SHOULD follow same comparison logic

Resolves #158

---------

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Co-authored-by: adam jones <domdomegg@users.noreply.github.com>
2025-08-26 14:55:38 +01:00

8.1 KiB
Raw Blame History

MCP Registry FAQ

These questions come up often in discussions about the MCP Registry. If you have a question that isn't answered here, please start a discussion on the MCP Registry Discussions page.

General Questions

What is the MCP Registry?

The MCP Registry is the official centralized metadata repository for publicly-accessible MCP servers. It provides:

  • A single place for server creators to publish metadata about their servers
  • A REST API for MCP clients and aggregators to discover available servers
  • Standardized installation and configuration information
  • Namespace management through DNS verification

What is the difference between "Official MCP Registry", "MCP Registry", "MCP registry", "MCP Registry API", etc?

There are four underlying concepts:

  • "MCP Server Registry API" (or "MCP Registry API"): The OpenAPI specification defined in openapi.yaml. This is a reusable API specification that anyone building any sort of "MCP server registry" should consider adopting / aligning with.
  • "Official MCP Registry" (or "MCP Registry"): The application that lives at https://registry.modelcontextprotocol.io. This registry currently only catalogs MCP servers, but may be extended in the future to also catalog MCP client/host apps and frameworks.
  • "Official MCP Registry API": The REST API served at https://registry.modelcontextprotocol.io, which is a superset of the MCP Registry API. Its OpenAPI specification can be downloaded from https://registry.modelcontextprotocol.io/openapi.yaml
  • "MCP server registry" (or "MCP registry"): A third party, likely commercial, implementation of the MCP Server Registry API or derivative specification.

Is the MCP Registry a package registry?

No. The MCP Registry stores metadata about MCP servers and references to where they're hosted (npm, PyPI, NuGet, Docker Hub, etc.), but does not host the actual source code or packages.

Who should use the MCP Registry directly?

The registry is designed for programmatic consumption by:

  • MCP client applications (Claude Desktop, Cline, etc.)
  • Server aggregators (Smithery, PulseMCP, etc.)
  • NOT individual end-users (they should use MCP clients or aggregator UIs)

Will there be a UI for browsing servers?

A UI is planned as a future milestone after the initial API launch, but is not part of the MVP.

Publishing Servers

How do I publish my MCP server?

Servers are published by submitting a server.json file through our CLI tool. The process requires:

  1. GitHub authentication
  2. A public GitHub repository (even for closed-source servers - just for the metadata)
  3. Your server package published to a supported registry (npm, PyPI, NuGet, Docker Hub, etc.)
  4. Optional: DNS verification for custom namespacing

What namespaces are available?

  • With DNS verification: com.yourcompany/server-name (reverse DNS notation)
  • Without DNS verification: io.github.yourusername/server-name
  • DNS verification is done via TXT records and enables authoritative namespacing

Is open source required?

No. While open source code is encouraged, it is not required for either locally or remotely run servers.

What package registries are supported?

  • npm (Node.js packages)
  • PyPI (Python packages)
  • NuGet.org (.NET packages)
  • GitHub Container Registry (GHCR)

More can be added as the community desires; feel free to open an issue if you are interested in building support for another registry.

Can I publish multiple versions?

Yes, versioning is supported:

  • Each version gets its own immutable metadata
  • Version strings must be unique for each server
  • Old versions remain accessible for compatibility
  • The registry tracks which version is "latest" based on semantic version ordering when possible

How do I update my server metadata?

Submit a new server.json with a unique version string. Once published, version metadata is immutable (similar to npm).

What version format should I use?

The registry accepts any version string up to 255 characters, but we recommend:

  • SHOULD use semantic versioning (e.g., "1.0.2", "2.1.0-alpha") for predictable ordering
  • SHOULD align with package versions to reduce confusion
  • MAY use prerelease labels (e.g., "1.0.0-1") for registry-specific versions

The registry attempts to parse versions as semantic versions for proper ordering. Non-semantic versions are allowed but will be ordered by publication timestamp. See the versioning guide for detailed guidance.

Can I delete/unpublish my server?

A reverse-publication flow is planned to allow quick deletion of accidentally published data.

Security & Trust

How do I know a server is from the claimed organization?

DNS verification ensures namespace ownership. For example:

  • com.microsoft/server requires DNS verification of microsoft.com
  • io.github.username/server is tied to a GitHub account or GitHub organization

What about typosquatting?

The registry implements (or is slated to soon implement):

  • Automatic blocking of names within a certain edit distance of existing servers
  • Community reporting mechanisms

Is there security scanning?

The MVP delegates security to the underlying package registries. Future iterations may include:

  • Vulnerability scanning
  • Dependency analysis

How is spam prevented?

  • GitHub authentication requirement
  • Rate limiting (e.g., 10 new servers per user per day)
  • Character limits and regex validation on free-form fields
  • Potential AI-based spam detection
  • Community reporting and admin blacklisting capabilities

API & Integration

How often should I poll the registry?

Recommended polling frequency:

  • /servers endpoint: once per hour
  • /servers/:id endpoint: once per version (results are immutable)
  • Design assumes CDN caching between registry and consumers

Will there be webhooks?

Not in the initial MVP, but the architecture supports adding webhooks for update notifications in the future.

Can I run my own registry instance?

While the API shapes and data formats are designed for reuse, the registry implementation itself is not designed for self-hosting. Organizations needing private registries should:

  • Implement the same API shape
  • Use the same server.json format
  • Potentially mirror/filter the official registry data

Operations & Maintenance

What's the expected reliability?

  • 24-hour+ downtime tolerance is acceptable, so you shouldn't rely on the registry being always available.
  • No direct end-user impact (consumers cache data)
  • Relies on CDN for actual availability
  • Volunteer maintainer model (no formal on-call)

How are DNS records verified?

  • Initial verification via TXT records
  • Daily re-verification to catch domain transfers
  • Publishing blocked if verification fails
  • Historical packages remain available with warnings

What about GitHub repository transfers?

The registry tracks GitHub repository IDs (not just URLs) to detect transfers. Daily checks update metadata if repositories move.

How is namespace transfer handled?

Namespace transfers (e.g., when someone leaves a company) are handled through the DNS verification system and GitHub organization membership.

Future Considerations

Will download counts be tracked?

Download count tracking is being considered as a quality signal, but must be designed carefully to not impact CDN caching.

What about tags or categories?

Categorization and curation are intentionally left to consumers (MCP clients and aggregators) to avoid maintenance burden and subjective decisions.

Will there be quality metrics?

Quality assessment is explicitly out of scope for the official registry. This is delegated to:

  • MCP clients (for their specific use cases)
  • Third-party aggregators
  • Community reviews on external platforms

What about internationalization?

Internationalization is a future consideration but not part of the MVP.

Will private registries be supported?

The registry design (API shapes, data formats) is intended to be reusable for private deployments, but the official registry will only host public servers.