modelcontextprotocol/registry
Watch
1
0
Fork
You've already forked registry
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
registry/docs/reference/faq.md
Frenchie 78c482b8d9
 feat(validators): Validate that Server versions are not ranges (#435) 
<!-- Provide a brief summary of your changes -->

Validates that server versions are not ranges.


**NB:** This also introduces `validateVersion` as a check on the
top-level `ValidateServerJSON`, as previously we were only checking
version ranges of packages via `validatePackageField` (i.e. `latest`
would have still been a valid top level server version), despite #413's
wording suggesting otherwise.

## Motivation and Context
Solves https://github.com/modelcontextprotocol/registry/issues/415

## How Has This Been Tested?

Tests added in `internal/validators/validators_test.go`

`make check` is clean.

## Breaking Changes
As per @domdomegg's comment, we should
> check nobody has done this in the existing registry data (if they
have, we should explore and understand why people have done this / if
it's valid etc.).

## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update

## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [x] I have added appropriate error handling
- [x] I have added or updated documentation as needed

## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->
2025-09-11 17:14:59 -07:00

8.4 KiB
Raw Permalink 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 primarily designed for programmatic consumption by subregistries (Smithery, PulseMCP, Docker Hub, Anthropic, GitHub, etc.). It is NOT currently intended for individual clients or end-users (they should use subregistries).

Will there be feature X?

See roadmap.md.

Publishing Servers

How do I publish my MCP server?

See the publisher README

What namespaces are available?

  • With GitHub verification: io.github.yourusername/server-name, io.github.yourorg/server-name
  • With DNS verification: com.yourcompany.*, com.yourcompany.*/*
  • With HTTP verification: com.yourcompany/*

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)
  • Docker Hub

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. Version ranges (e.g., ^1.2.3, ~1.2.3, >=1.2.3, 1.x, 1.*) are rejected; publish a specific version instead. See the versioning guide for detailed guidance.

Can I add custom metadata when publishing?

Yes, extensions under the x-publisher property are preserved when publishing to the registry. This allows you to include custom metadata specific to your publishing process.

Can I delete/unpublish my server?

At time of last update, this was open for discussion in #104.

Can I publish a private server?

Private servers are those that are only accessible to a narrow set of users. For example, servers published on a private network (like mcp.acme-corp.internal) or on private package registries (e.g. npx -y @acme/mcp --registry https://artifactory.acme-corp.internal/npm).

These are generally not supported on the official MCP registry, which is designed for publicly accessible MCP servers.

If you want to publish private servers we recommend you host your own MCP subregistry, and add them there.

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.name/server is tied to a GitHub account or GitHub organization name

Is there security scanning?

The MVP delegates security scanning to:

  • underlying package registries; and
  • subregistries

How is spam prevented?

  • Namespace authentication requirements
  • Character limits and regex validation on free-form fields
  • Manual takedown of spam or malicious servers

In future we might explore:

  • Stricter rate limiting (e.g., 10 new servers per user per day)
  • 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

Also see #291, which might mean the above can be more regular.

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?

Yes! The API shapes and data formats are intentionally designed for reuse by subregistries. Organizations needing private registries should:

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

Can I extend the registry API?

Yes, we support x-com.example style extensions in a bunch of places - see the official MCP registry API spec. This can be used to add annotations to many objects, e.g. add security scanning details, enrich package metadata, etc.

If you have a use case that can't be addressed here, raise a GitHub issue!

Can I use the code here to run my own registry instance?

The registry implementation here is not designed for self-hosting, but you're welcome to try to use it/fork it as necessary. Note that this is not an intended use, and the registry maintainers cannot provide any support for this at this time.

Operations & Maintenance

What's the expected reliability?

  • This is a community maintained project without full time staffing. You should therefore expect downtime periods of up to 1 business day. No strict guarantees are provided. (Also see discussion in #150)
  • Ideally clients should use subregistries with higher availability guarantees, to avoid direct end-user impact (as subregistries can cache data).

What if I need to report a spam or malicious server?

  1. Report it as abuse to the underlying package registry (e.g. NPM, PyPi, DockerHub, etc.); and
  2. Raise a GitHub issue on the registry repo with a title beginning Abuse report:

What if I need to report a security vulnerability in the registry itself?

Follow the MCP community SECURITY.md.