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
adam jones 2e7108d366
 Big docs tidy up in preparation for launch (#364) 
## Motivation and Context
Docs currently don't have very clear organisation, and don't explain
core flows.

This fixes #89 (although we still might want to push these to
`https://modelcontextprotocol.io/docs/`), based on the plan there.

One minor change from that plan is that I merged tutorials and guides,
because they ended up basically being duplicates which I thought would
be annoying for us to keep in sync. Additionally in the Diátaxis
framework, tutorials and guides are separated by whether they are
focused on acquisition of skills (e.g. in a learning environment) or
application of skills (e.g. in a work environment). I expect the
registry to be something that will be used occasionally in a work
environment, rather than a fundamental 'learnable' skill so I think it's
reasonable not to have tutorials and fold these into guides.

## How Has This Been Tested?
- Read through all these updated docs
- Unit and integration tests (that previously used examples.md and use
the schema) working
- Ran `npx markdown-link-check .` to check all the links work

## Breaking Changes
Links to old docs will break, but I don't think there are any. All
internal links have been checked and updated.

## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] 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
2025-09-07 10:44:42 +01:00

178 lines
8.2 KiB
Markdown
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](https://github.com/modelcontextprotocol/registry/discussions).
## 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](./api/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](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 feature X?
See [roadmap.md](../explanations/roadmap.md).
## Publishing Servers
### How do I publish my MCP server?
See the [publisher README](../../cmd/publisher/README.md)
### 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)
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](../explanations/versioning.md) 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](https://github.com/modelcontextprotocol/registry/issues/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](https://github.com/modelcontextprotocol/registry/issues/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](https://github.com/modelcontextprotocol/registry/issues/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](https://github.com/modelcontextprotocol/.github/blob/main/SECURITY.md).
Reference in a new issue View git blame Copy permalink