Personal vs. organization namespaces  Copy Section
GitHub authentication always grants your personal namespace, io.github.<your-username>/*.
To publish under an organization namespace (io.github.<orgname>/*), you must be an Owner of that organization. Ordinary org membership is no longer sufficient: the registry checks your membership role and only grants the org namespace to admins. This prevents anyone who merely belongs to an org from publishing — or overwriting — servers under the org's name.
If you authenticate with a Personal Access Token (for example in CI), the token must let the registry read your organization role. A token that can't will still publish to your personal namespace, but org publishing will be silently unavailable. The exact requirement depends on the token type:
- Classic PAT: grant the read:org scope.
- Fine-grained PAT: grant the Organization permissions → Members → Read-only permission (the fine-grained equivalent of read:org). Without it, GitHub returns no organization membership for the token and you'll get your personal namespace only. Note that a fine-grained PAT is bound to a single resource owner, so it can only see the organization it was created for.
Either way the token needs no repository scopes — the registry never reads or writes your code.
DNS Authentication  Copy Chapter
DNS authentication is a domain-based authentication method that relies on a DNS TXT record.
<Warning>
  The TXT record must be placed on the apex of your domain (e.g. example.com), not under a selector like _mcp-auth.example.com or _mcp-registry.example.com. MCP DNS auth follows SPF-style placement (apex), not DKIM-style (selector). If you put the record under a selector, the registry will not see it and authentication will fail with a generic signature error.
  If you rotate keys, also remember to remove the previous TXT record from the apex — a stale record left behind will be tried first and cause verification to fail.
</Warning>
To perform DNS authentication using the mcp-publisher CLI tool, run the following commands in your server project directory to generate a TXT record based on a public/private key pair:
<Note>
  The Ed25519 codepath requires OpenSSL 3.0 or later. macOS ships with LibreSSL by default (the system openssl binary), which does not implement Ed25519 in genpkey and fails with Algorithm Ed25519 not found. On macOS, install OpenSSL 3 (brew install openssl@3) and invoke it explicitly — for example, replace openssl with /opt/homebrew/opt/openssl@3/bin/openssl (Apple Silicon) or /usr/local/opt/openssl@3/bin/openssl (Intel) in the commands below. The ECDSA P-384 codepath works on LibreSSL.
</Note>
<CodeGroup>

</CodeGroup>
Then add the TXT record using your DNS provider's control panel. It may take several minutes for the TXT record to propagate. After the TXT record has propagated, log in using the mcp-publisher login command:
<CodeGroup>

</CodeGroup>
HTTP Authentication  Copy Chapter
HTTP authentication is a domain-based authentication method that relies on a /.well-known/mcp-registry-auth file hosted on your domain. For example, https://example.com/.well-known/mcp-registry-auth.
To perform HTTP authentication using the mcp-publisher CLI tool, run the following commands in your server project directory to generate an mcp-registry-auth file based on a public/private key pair:
<Note>
  As with DNS authentication, the Ed25519 codepath requires OpenSSL 3.0 or later. macOS's system LibreSSL does not support Ed25519 in genpkey. See the note in the DNS Authentication section for the macOS workaround.
</Note>
<CodeGroup>

</CodeGroup>
Then host the mcp-registry-auth file at /.well-known/mcp-registry-auth on your domain. After the file is hosted, log in using the mcp-publisher login command:
<CodeGroup>

</CodeGroup>
---
Modelcontextprotocol Io/Faq  Copy Section
---
title: Frequently Asked Questions
sidebarTitle: FAQ
---
<Note>
  The MCP Registry is currently in preview. Breaking changes or data resets may occur before general availability. If you encounter any issues, please report them on GitHub.
</Note>
General  Copy Chapter
What is the difference between "Official MCP Registry", "MCP Registry", "MCP registry", "MCP Registry API", etc?  Copy Section
- "MCP Registry API" — An API that implements the OpenAPI spec defined by the MCP Registry.
- "Official MCP Registry API" — The REST API served at https://registry.modelcontextprotocol.io, which is a superset of the MCP Registry API. Its OpenAPI spec can be downloaded from https://registry.modelcontextprotocol.io/openapi.yaml.
- "MCP registry" — A third-party service that provides an MCP Registry API.
- "Official MCP Registry" (or "The MCP Registry") — The service that lives at https://registry.modelcontextprotocol.io.
Can I delete/unpublish my server?  Copy Section
Yes, you can change your server's status to deleted using the mcp-publisher status command:

Deleted servers are hidden from default API listings but can still be retrieved with include_deleted=true. You can restore a deleted server by setting its status back to active.
Note: Server metadata is never permanently removed from the registry. The deleted status hides the server from discovery but preserves the historical record.
How do I update my server metadata?  Copy Section
Submit a new server.json with a unique version string. Once published, version metadata is immutable (similar to npm).
Can I add custom metadata when publishing?  Copy Section
Yes, custom metadata under _meta.io.modelcontextprotocol.registry/publisher-provided is preserved when publishing to the registry. This allows you to include custom metadata specific to your publishing process.
<Warning>
There is a 4KB size limit (4096 bytes of JSON). Publishing will fail if this limit is exceeded.
</Warning>
Reporting Issues  Copy Chapter
What if I need to report a spam or malicious server?  Copy Section
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?  Copy Section
Follow the MCP community SECURITY.md.
---
Modelcontextprotocol Io/Github Actions  Copy Section
---
title: How to Automate Publishing with GitHub Actions
sidebarTitle: GitHub Actions
---
<Note>
  The MCP Registry is currently in preview. Breaking changes or data resets may occur before general availability. If you encounter any issues, please report them on GitHub.
</Note>
Step 1: Create a Workflow File  Copy Chapter
In your server project directory, create a .github/workflows/publish-mcp.yml file. Here is an example for npm-based local server, but the MCP Registry publishing steps are the same for all package types:
<CodeGroup>

</CodeGroup>
Step 2: Add Secrets  Copy Chapter
You may need to add a secret depending on which authentication method you choose:
- GitHub OIDC Authentication: No dedicated secret necessary.
- GitHub PAT Authentication: Add a MCP_GITHUB_TOKEN secret with a GitHub Personal Access Token. The registry only needs to read your organization role to confirm you are an Owner before granting its namespace, so grant the minimum for that and no repository scopes (the registry never reads or writes your code):
  - Classic PAT: the read:org scope (read:user is not needed; a bare token still authenticates and publishes to your personal namespace).
  - Fine-grained PAT: the Organization permissions → Members → Read-only permission (the equivalent of read:org). Without it you'll get your personal namespace only. A fine-grained PAT is scoped to one resource owner, so create it for the organization you're publishing to.
  For an organization token, store it as an Environment secret on the mcp-registry-publish environment rather than a plain repository secret — see "Securing your registry token in CI" below for why this matters and how to configure the environment.
- DNS Authentication: Add a MCP_PRIVATE_KEY secret with your Ed25519 private key.
You may also need to add secrets for your package registry. For example, the workflow above needs an NPM_TOKEN secret with your npm token.
For information about how to add secrets to a repository, see Using secrets in GitHub Actions.
Securing your registry token in CI  Copy Section
Whichever token you use to authenticate, treat it as a high-value credential. When you authenticate to an organization namespace, the resulting registry token can publish — and overwrite — any server under io.github.<org>/, not just the one in this repository. The relevant question for your threat model is therefore: who can cause code to run in a job where this secret is exposed?* By default that is every repository writer (via branch or tag pushes), not only org Owners — so a plain repo secret quietly widens publish access to everyone with write access.
GitHub gives you the tools to close that gap. We recommend, in increasing order of strength:
1. Store the token as an Environment secret, not a repository or organization secret. A job can only read an environment secret when it declares environment: (as the PAT example above does). Note that the environment: key alone protects nothing: if the environment does not exist yet, GitHub auto-creates it with no protection rules on first run, and a job that declares environment: still also receives ordinary repository and organization secrets. The protection comes from storing the token as a secret on that environment and configuring the environment (steps 2–3 below) — not from the environment: key by itself.
2. Restrict that environment to your default branch and/or release tags with a deployment branch rule, and protect that branch with required pull request reviews. Now only reviewed, maintainer-approved code can ever reach the token.
3. (Strongest) Add a required reviewer to the environment so each publish pauses for an explicit human approval.
Two pitfalls to avoid regardless of the above:
- Never publish from a pull_request_target workflow that checks out PR-head code. That trigger runs with your secrets in the base-repo context, so an untrusted fork PR could exfiltrate the token. Environment branch rules do not protect you here (the ref is still your base branch) — only required reviewers do.
- Avoid self-hosted runners for the publish job on public repositories, where fork PRs may be able to schedule jobs onto them.
By default, pull requests from forks receive no secrets and cannot push branches, so external contributors cannot reach the token without one of the misconfigurations above.
Step 3: Tag and Release  Copy Chapter
Create and push a version tag to trigger the workflow:

The workflow will run tests, build the package, publish the package to npm, and publish the server to the MCP Registry.
Troubleshooting  Copy Chapter
{/ prettier-ignore-start /}
| Error Message | Action |
| --- | --- |
| "Authentication failed" | Ensure id-token: write permission is set for OIDC, or check secrets. |
| "invalid audience" | Your mcp-publisher binary is too old for this registry deployment. Re-run the install step shown above so you pick up the latest release. |
| "Package validation failed" | Verify your package successfully published to the package registry (e.g., npm, PyPI), and that your package has the necessary verification information. |
{/ prettier-ignore-end /}
---
Modelcontextprotocol Io/Moderation Policy  Copy Section
---
title: The MCP Registry Moderation Policy
sidebarTitle: Moderation Policy
---
<Note>
  The MCP Registry is currently in preview. Breaking changes or data resets may occur before general availability. If you encounter any issues, please report them on GitHub.
</Note>
TL;DR: The MCP Registry is quite permissive! We only remove illegal content, malware, spam, and completely broken servers.
Scope  Copy Chapter
This policy applies to the official MCP Registry at registry.modelcontextprotocol.io.
Subregistries may have their own moderation policies. If you have questions about content on a specific subregistry, please contact them directly.
Disclaimer  Copy Chapter
The MCP Registry does not make guarantees about moderation, and consumers should assume minimal-to-no moderation.
The MCP Registry is a community supported project, and we have limited active moderation capabilities. We largely rely on upstream package registries (like NPM, PyPI, and Docker) or downstream subregistries (like the GitHub MCP Registry) to do more in-depth moderation.
This means there may be content in the MCP Registry that should be removed under this policy, but which we haven't yet removed. Consumers should treat scraped data accordingly.
What We Remove  Copy Chapter
We will remove servers that contain:
- Illegal content, which includes obscene content, copyright violations, and hacking tools
- Malware, regardless of intentions
- Spam, especially mass-created servers that disrupt the registry. Examples:
  - The same server being submitted multiple times under different names
  - A server that doesn't do anything but provide a fixed response with some marketing copy
  - A server with a description stuffed with marketing copy and an unrelated implementation
- Non-functioning servers
What We Don't Remove  Copy Chapter
Generally, we believe in keeping the registry open and pushing moderation to subregistries. We therefore won't remove:
- Low-quality or buggy servers
- Servers with security vulnerabilities
- Servers that do the same thing as other servers
- Servers that provide or contain adult content
How Removal Works  Copy Chapter
When we remove a server, we set the server's status to "deleted", but the server's metadata remains accessible via the MCP Registry API. Aggregators may then remove the server from their indexes.
In extreme cases, we may overwrite or erase the server's metadata. For example, if the metadata itself is unlawful.
Appeals  Copy Chapter
Think we made a mistake? Open an issue on our GitHub repository with:
- The name of the server
- Why you believe the server doesn't meet the above criteria for removal
Changes to This Policy  Copy Chapter
We're still learning how best to run the MCP Registry! As such, we might end up changing this policy in the future.
---
Modelcontextprotocol Io/Package Types  Copy Section
---
title: MCP Registry Supported Package Types
sidebarTitle: Package Types
---
<Note>
  The MCP Registry is currently in preview. Breaking changes or data resets may occur before general availability. If you encounter any issues, please report them on GitHub.
</Note>
Package Types
The MCP Registry supports several different package types, and each package type has its own verification method.
npm Packages  Copy Chapter
For npm packages, the MCP Registry currently supports the npm public registry (https://registry.npmjs.org) only.
npm packages use "registryType": "npm" in server.json. For example:

Ownership Verification  Copy Section
The MCP Registry verifies ownership of npm packages by checking mcpName in package.json. The mcpName property MUST match the server name from server.json. For example:

PyPI Packages  Copy Chapter
For PyPI packages, the MCP Registry currently supports the official PyPI registry (https://pypi.org) only.
PyPI packages use "registryType": "pypi" in server.json. For example:

Ownership Verification  Copy Section
The MCP Registry verifies ownership of PyPI packages by checking for the existence of an mcp-name: $SERVER_NAME string in the package README (which becomes the package description on PyPI). The string may be hidden in a comment, but the $SERVER_NAME portion MUST match the server name from server.json. For example:

The mcp-name: token must be followed by a boundary — a newline, whitespace, an HTML tag, or the comment close -->. Keep it on its own line or inside ; do not glue it directly to trailing characters such as a sentence-ending period (…/database-query-mcp.), which prevents the match.
NuGet Packages  Copy Chapter
For NuGet packages, the MCP Registry currently supports the official NuGet registry (https://api.nuget.org/v3/index.json) only.
NuGet packages use "registryType": "nuget" in server.json. For example:

Ownership Verification  Copy Section
The MCP Registry verifies ownership of NuGet packages by checking for the existence of an mcp-name: $SERVER_NAME string in the package README. The string may be hidden in a comment, but the $SERVER_NAME portion MUST match the server name from server.json. For example:

The mcp-name: token must be followed by a boundary — a newline, whitespace, an HTML tag, or the comment close -->. Keep it on its own line or inside ; do not glue it directly to trailing characters such as a sentence-ending period (…/azure-devops-mcp.), which prevents the match.
Cargo (Rust) Packages  Copy Chapter
For Cargo packages, the MCP Registry currently supports the official crates.io registry (https://crates.io) only.
Cargo packages use "registryType": "cargo" in server.json. For example:

Runtime Model  Copy Section
Cargo's runtime model differs from npm/PyPI/NuGet. cargo install <crate> places the compiled binary on PATH at ~/.cargo/bin, after which MCP clients invoke it directly by name. There is no per-invocation runner equivalent to npx (npm), uvx (PyPI), or dnx (NuGet, .NET 10 SDK Preview 6+) — install is one-time, execution is by binary name. The Cargo example above intentionally omits runtimeHint for this reason.
Rust MCP authors have two first-class distribution paths:
- Cargo (registryType: cargo) — source-distributed via crates.io. End users need the Rust toolchain (rustup) to run cargo install. Idiomatic for the Rust ecosystem and consistent with how Rust CLIs are typically published.
- MCPB (registryType: mcpb) — prebuilt binary distributed via GitHub or GitLab Releases. End users need no toolchain. Right choice if the priority is "no Rust toolchain required."
Both paths are supported; the choice is the author's. Cargo native support exists so Rust authors who prefer source distribution are not forced into the MCPB binary-packaging workaround.
Ownership Verification  Copy Section
The MCP Registry verifies ownership of Cargo packages by checking for the existence of an mcp-name: $SERVER_NAME string in the package README (which is rendered to HTML and served by crates.io's static CDN). The $SERVER_NAME portion MUST match the server name from server.json. For example:

The format of identifier is registry/namespace/repository:tag. For example, docker.io/user/app:1.0.0, ghcr.io/user/app:1.0.0, or quay.io/myorg/my-mcp-server:1.0.0. The tag can also be specified as a digest.
Ownership Verification  Copy Section
The MCP Registry verifies ownership of Docker/OCI images by checking for an io.modelcontextprotocol.server.name annotation. The value of the io.modelcontextprotocol.server.name annotation MUST match the server name from server.json. For example:

MCPB Packages  Copy Chapter
For MCPB packages, the MCP Registry currently supports MCPB artifacts hosted via GitHub or GitLab releases.
MCPB packages use "registryType": "mcpb" in server.json. For example:

Verification  Copy Section
The MCPB package URL (identifier in server.json) MUST contain the string "mcp". That can be as part of the .mcpb file extension or in the name of the repository.
The package metadata in server.json MUST include a fileSha256 property with a SHA-256 hash of the MCPB artifact, which can be computed using the openssl command:

The MCP Registry does not validate this hash; however, MCP clients do validate the hash before installation to ensure file integrity. Downstream registries may also implement their own validation.
---
Modelcontextprotocol Io/Quickstart  Copy Section
---
title: "Quickstart: Publish an MCP Server to the MCP Registry"
sidebarTitle: "Quickstart: Publish a Server"
---
<Note>
  The MCP Registry is currently in preview. Breaking changes or data resets may occur before general availability. If you encounter any issues, please report them on GitHub.
</Note>
This tutorial will show you how to publish an MCP server written in TypeScript to the MCP Registry using the official mcp-publisher CLI tool.
<Note>
  If you are publishing a non-npm package (PyPI, NuGet, OCI, MCPB), the overall flow is identical, but the ownership-verification step in Step 1 is different per package type. See Package Types for the verification mechanism that applies to your package, then return here and follow the remaining steps.
</Note>
Prerequisites  Copy Chapter
- Node.js — This tutorial assumes the MCP server is written in TypeScript.
- npm account — The MCP Registry only hosts metadata, not artifacts. Before publishing to the MCP Registry, we will publish the MCP server's package to npm, so you will need an npm account.
- GitHub account — The MCP Registry supports multiple authentication methods. For simplicity, this tutorial will use GitHub-based authentication, so you will need a GitHub account.
If you do not have an MCP server written in TypeScript, you can copy the weather-server-typescript server from the modelcontextprotocol/quickstart-resources repository to follow along with this tutorial:

And edit package.json to reflect your information:

Step 1: Add verification information to the package  Copy Chapter
The MCP Registry verifies that a server's underlying package matches its metadata. For npm packages, this requires adding an mcpName property to package.json:

The value of mcpName will be your server's name in the MCP Registry.
Because we will be using GitHub-based authentication, mcpName must start with io.github.my-username/.
Step 2: Publish the package  Copy Chapter
The MCP Registry only hosts metadata, not artifacts, so we must publish the package to npm before publishing the server to the MCP Registry.
Ensure the distribution files are built:

Then follow npm's publishing guide. In particular, you will probably need to run the following commands:

You can verify your package is published by visiting its npm URL, such as https://www.npmjs.com/package/@my-username/mcp-weather-server.
Step 3: Install mcp-publisher ')" title="Copy chapter prompt for LLMs"> Copy Chapter
Install the mcp-publisher CLI tool using a pre-built binary or Homebrew:
<CodeGroup>

</CodeGroup>
Verify that mcp-publisher is correctly installed by running:

You should see output like:

Step 4: Create server.json ')" title="Copy chapter prompt for LLMs"> Copy Chapter
The mcp-publisher init command can generate a server.json template file with some information derived from your project.
In your server project directory, run mcp-publisher init:

Open the generated server.json file, and you should see contents like:

Edit the contents as necessary:

The name property in server.json must match the mcpName property in package.json.
Step 5: Authenticate with the MCP Registry  Copy Chapter
For this tutorial, we will authenticate with the MCP Registry using GitHub-based authentication.
Run the mcp-publisher login command to initiate authentication:

You should see output like:

Visit the link, follow the prompts, and enter the authorization code that was printed in the terminal (e.g., ABCD-1234 in the above output). Once complete, go back to the terminal, and you should see output like:

Step 6: Publish to the MCP Registry  Copy Chapter
Finally, publish your server to the MCP Registry using the mcp-publisher publish command:

You should see output like:

You can verify that your server is published by searching for it using the MCP Registry API:

You should see your server's metadata in the search results JSON:

Troubleshooting  Copy Chapter
{/ prettier-ignore-start /}
| Error Message | Action |
| --- | --- |
|"Registry validation failed for package"|Ensure your package includes the required ownership-verification marker for its package type. For npm this is mcpName in package.json; for PyPI and NuGet it is an mcp-name: <server-name> line (or HTML comment) in the package README; for other types see Package Types.|
|"Invalid or expired Registry JWT token"|Re-authenticate by running mcp-publisher login github.|
|"You do not have permission to publish this server"|Your authentication method doesn't match your server's namespace format. With GitHub auth, your server name must start with io.github.your-username/.|
{/ prettier-ignore-end /}
Next Steps  Copy Chapter
- Learn about support for other package types.
- Learn about support for remote servers.
- Learn how to use other authentication methods, such as DNS authentication which enables custom domains for server name prefixes.
- Learn how to automate publishing with GitHub Actions.
---
Modelcontextprotocol Io/Registry Aggregators  Copy Section
---
title: MCP Registry Aggregators
sidebarTitle: Registry Aggregators
---
<Note>
  The MCP Registry is currently in preview. Breaking changes or data resets may occur before general availability. If you encounter any issues, please report them on GitHub.
</Note>
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  Copy Chapter
The base URL for the MCP Registry REST API is https://registry.modelcontextprotocol.io. It supports the following endpoints:
- GET /v0.1/servers — List all servers.
- GET /v0.1/servers/{serverName}/versions — List all versions of a server.
- GET /v0.1/servers/{serverName}/versions/{version} — 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  Copy Section
The GET /v0.1/servers endpoint supports cursor-based pagination.
For example, the first page can be fetched using a limit query parameter:

Then subsequent pages can be fetched by passing the nextCursor value as the cursor query parameter:

Filtering Since  Copy Section
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 date-time format:

Server Status  Copy Chapter
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, suggesting the server might be spam, malware, or illegal. Aggregators may prefer to remove these servers from their index.
Acting as a Subregistry  Copy Chapter
A subregistry is an aggregator that also implements the OpenAPI spec 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:

We recommend that custom metadata be put under a key that reflects the subregistry (e.g., "com.example.subregistry/custom" in the above example).
---
Modelcontextprotocol Io/Remote Servers  Copy Section
---
title: Publishing Remote Servers
sidebarTitle: Remote Servers
---
<Note>
  The MCP Registry is currently in preview. Breaking changes or data resets may occur before general availability. If you encounter any issues, please report them on GitHub.
</Note>
The MCP Registry supports remote MCP servers via the remotes property in server.json:

A remote server MUST be publicly accessible at its specified URL.
Transport Type  Copy Chapter
Remote servers can use the Streamable HTTP transport (recommended) or the SSE transport. Remote servers can also support both transports simultaneously at different URLs.
Specify the transport by setting the type property of the remotes entry to either "streamable-http" or "sse":

URL Template Variables  Copy Chapter
Remote servers can define URL template variables using {curly_braces} notation. This enables multi-tenant deployments where a single server definition can support multiple endpoints with configurable values:

When configuring this server, users provide their tenant_id value, and the URL template gets resolved to the appropriate endpoint (e.g., https://us-cell1.analytics.example.com/mcp).
Variables support additional properties like default, choices, and isSecret:

HTTP Headers  Copy Chapter
MCP clients can be instructed to send specific HTTP headers by adding the headers property to the remotes entry:

Supporting Remote and Non-remote Installation  Copy Chapter
The remotes property can coexist with the packages property in server.json in order to allow MCP host applications to choose the preferred method of installation.

---
Modelcontextprotocol Io/Terms Of Service  Copy Section
---
title: Official MCP Registry Terms of Service
sidebarTitle: Terms of Service
---
<Note>
  The MCP Registry is currently in preview. Breaking changes or data resets may occur before general availability. If you encounter any issues, please report them on GitHub.
</Note>
Effective date: 2025-09-02
Overview  Copy Chapter
These terms (“Terms”) govern your access to and use of the official MCP Registry (the service hosted at https://registry.modelcontextprotocol.io/ or a successor location) (“Registry”), including submissions or publications of MCP servers, references to MCP servers or to data about such servers and/or their developers (“Registry Data”), and related conduct. The Registry is intended to be a centralized repository of MCP servers developed by community members to facilitate easy access by AI applications.
These terms are governed by the laws of the State of California.
For All Users  Copy Chapter
1. No Warranties. The Registry is provided “as is” with no warranties of any kind. That means we don't guarantee the accuracy, completeness, safety, durability, or availability of the Registry, servers included in the registry, or Registry Data. In short, we’re also not responsible for any MCP servers or Registry Data, and we highly recommend that you evaluate each MCP server and its suitability for your intended use case(s) before deciding whether to use it.
2. Access and Use Requirements. To access or use the Registry, you must:
   1. Be at least 18 years old.
   2. Use the Registry, MCP servers in the Registry, and Registry Data only in ways that are legal under the applicable laws of the United States or other countries including the country in which you are a resident or from which you access and use the Registry, and not be barred from accessing or using the Registry under such laws. You will comply with all applicable law, regulation, and third party rights (including, without limitation, laws regarding the import or export of data or software, privacy, intellectual property, and local laws). You will not use the Registry, MCP servers, or Registry Data to encourage or promote illegal activity or the violation of third party rights or terms of service.
   3. Log in via method(s) approved by the Registry maintainers, which may involve using applications or other software owned by third parties.
3. Entity Use. If you are accessing or using the Registry on behalf of an entity, you represent and warrant that you have authority to bind that entity to these Terms. By accepting these Terms, you are doing so on behalf of that entity (and all references to “you” in these Terms refer to that entity).
4. Account Information. In order to access or use the Registry, you may be required to provide certain information (such as identification or contact details) as part of a registration process or in connection with your access or use of the Registry or MCP servers therein. Any information you give must be accurate and up-to-date, and you agree to inform us promptly of any updates. You understand that your use of the Registry may be monitored to ensure quality and verify your compliance with these Terms.
5. Feedback. You are under no obligation to provide feedback or suggestions. If you provide feedback or suggestions about the Registry or the Model Context Protocol, then we (and those we allow) may use such information without obligation to you.
6. Branding. Only use the term “Official MCP Registry” where it is clear it refers to the Registry, and does not imply affiliation, endorsement, or sponsorship. For example, you can permissibly say “Acme Inc. keeps its data up to date by automatically pulling data from the Official MCP Registry” or “This data comes from the Official MCP Registry,” but cannot say “This is the website for the Official MCP Registry,” “We’re the premier destination to view Official MCP Registry data,” or “We’ve partnered with the Official MCP Registry to provide this data.”
7. Modification. We may modify the Terms or any portion to, for example, reflect changes to the law or changes to the Model Context Protocol. We’ll post notice of modifications to the Terms to this website or a successor location. If you do not agree to the modified Terms, you should discontinue your access to and/or use of the Registry. Your continued access to and/or use of the Registry constitutes your acceptance of any modified Terms.
8. Additional Terms. Depending on your intended use case(s), you must also abide by applicable terms below.
For MCP Developers  Copy Chapter
9. Prohibitions. By accessing and using the Registry, including by submitting MCP servers and/or Registry Data, you agree not to:
   1. Share malicious or harmful content, such as malware, even in good faith or for research purposes, or perform any action with the intent of introducing any viruses, worms, defects, Trojan horses, malware, or any items of a destructive nature;
   2. Defame, abuse, harass, stalk, or threaten others;
   3. Interfere with or disrupt the Registry or any associated servers or networks;
   4. Submit data with the intent of confusing or misleading others, including but not limited to via spam, posting off-topic marketing content, posting MCP servers in a way that falsely implies affiliation with or endorsement by a third party, or repeatedly posting the same or similar MCP servers under different names;
   5. Promote or facilitate unlawful online gambling or disruptive commercial messages or advertisements;
   6. Use the Registry for any activities where the use or failure of the Registry could lead to death, personal injury, or environmental damage;
   7. Use the Registry to process or store any data that is subject to the International Traffic in Arms Regulations maintained by the U.S. Department of State.
10. License. You agree that metadata about MCP servers you submit (e.g., schema name and description, URLs, identifiers) and other Registry Data is intended to be public, and will be dedicated to the public domain under CC0 1.0 Universal. By submitting such data, you agree that you have the legal right to make this dedication (i.e., you own the copyright to these submissions or have permission from the copyright owner(s) to do so) and intend to do so. You understand that this dedication is perpetual, irrevocable, and worldwide, and you waive any moral rights you may have in your contributions to the fullest extent permitted by law. This dedication applies only to Registry Data and not to packages in third party registries that you might point to.
11. Privacy and Publicity. You understand that any MCP server metadata you publish may be made public. This includes personal data such as your GitHub username, domain name, or details from your server description. Moreover, you understand that others may process personal information included in your MCP server metadata. For example, subregistries might enrich this data by adding how many stars your GitHub repository has, or perform automated security scanning on your code. By publishing a server, you agree that others may engage in this sort of processing, and you waive rights you might have in some jurisdictions to access, rectify, erase, restrict, or object to such processing.
---
Modelcontextprotocol Io/Versioning  Copy Section
---
title: Versioning Published MCP Servers
sidebarTitle: Versioning
---
<Note>
  The MCP Registry is currently in preview. Breaking changes or data resets may occur before general availability. If you encounter any issues, please report them on GitHub.
</Note>
MCP servers MUST define a version string in server.json. For example:

The version string MUST be unique for each publication of the server. Once published, the version string (and other metadata) cannot be changed.
Version Format  Copy Chapter
The MCP Registry recommends semantic versioning, but supports any version string format. When a server is published, the MCP Registry will attempt to parse its version as a semantic version string for sorting purposes, and will mark the version as "latest" if appropriate. If parsing fails, the version will always be marked as "latest".
<Warning>
If a server uses semantic version strings but publishes a new version that does _not_ conform to semantic versioning, the new version will be marked as "latest" even if it would otherwise be sorted before the semantic version strings.
</Warning>
As an error prevention mechanism, the MCP Registry prohibits version strings that appear to refer to ranges of versions.
| Example        | Type                | Guidance                       |
| -------------- | ------------------- | ------------------------------ |
| 1.0.0        | semantic version    | Recommended                |
| 2.1.3-alpha  | semantic prerelease | Recommended                |
| 1.0.0-beta.1 | semantic prerelease | Recommended                |
| 3.0.0-rc.2   | semantic prerelease | Recommended                |
| 2025.11.25   | semantic date       | Recommended                    |
| 2025.6.18    | semantic date       | Recommended (⚠️Caution!⚠️) |
| 2025.06.18   | non-semantic date   | Allowed (⚠️Caution!⚠️)     |
| 2025-06-18   | non-semantic date   | Allowed                        |
| v1.0         | prefixed version    | Allowed                        |
| ^1.2.3       | version range       | Prohibited                     |
| ~1.2.3       | version range       | Prohibited                     |
| >=1.2.3      | version range       | Prohibited                     |
| <=1.2.3      | version range       | Prohibited                     |
| >1.2.3       | version range       | Prohibited                     |
| <1.2.3       | version range       | Prohibited                     |
| 1.x          | version range       | Prohibited                     |
| 1.2.*        | version range       | Prohibited                     |
| 1 - 2        | version range       | Prohibited                     |
| 1.2 \|\| 1.3 | version range       | Prohibited                     |
Best Practices  Copy Chapter
Use Semantic Versioning  Copy Section
Use semantic versioning for version strings.
Align Server Version with Package Version  Copy Section
For local servers, align the server version with the underlying package version in order to prevent confusion:

If there are multiple underlying packages, use the server version to indicate the overall release version:

Align Server Version with Remote API Version  Copy Section
For remote servers with an API version, the server version should align with the API version:

Use Prerelease Versions for Registry-only Updates  Copy Section
If you anticipate publishing a server multiple times _without_ changing the underlying package or remote URL — for example, to update other parts of the metadata — use semantic prerelease versions:

<Warning>
According to semantic versioning, prerelease versions such as 1.2.3-1 are sorted before regular semantic versions such as 1.2.3. Therefore, if you publish a prerelease version _after_ its corresponding regular version, the prerelease version will not be marked as "latest".
</Warning>
Aggregator Recommendations  Copy Chapter
MCP Registry aggregators SHOULD:
1. Attempt to interpret versions as semantic versions when possible
2. Use the following version comparison rules:
   - If one version is marked as "latest", treat it as later
   - If both versions are valid semantic versions, use semantic versioning comparison rules
   - If neither versions are valid semantic versions, compare published timestamp
   - If one version is a valid semantic version and the other is not, treat the semantic version as later
---
Reference/Cli/Commands  Copy Section
Publisher CLI Commands Reference
Complete command reference for the mcp-publisher CLI tool.
See the publishing guide for a walkthrough of using the CLI to publish a server.
Installation  Copy Chapter
Install via Homebrew (macOS/Linux):

Global Options  Copy Chapter
All commands support:
- --help, -h - Show command help
--registry is a flag on login only (default: https://registry.modelcontextprotocol.io). The
other commands read the registry URL from the stored login token, so passing --registry to
publish would be interpreted as the server.json path.
Commands  Copy Chapter
mcp-publisher init ')" title="Copy section prompt for LLMs"> Copy Section
Generate a server.json template with automatic detection.
Usage:

Behavior:
- Creates server.json in current directory
- Auto-detects package managers (package.json, setup.py, etc.)
- Pre-fills fields where possible
- Writes TODO: placeholders for fields it cannot detect — it is non-interactive and takes no flags
Example output:

mcp-publisher login <method> ')" title="Copy section prompt for LLMs"> Copy Section
Authenticate with the registry.
Authentication Methods:
#### GitHub Interactive

- Opens browser for GitHub OAuth flow
- Grants access to io.github.{username}/ and io.github.{org}/ namespaces
- --token supplies a GitHub Personal Access Token instead of the interactive flow, which is how
  publishing from GitHub Actions authenticates
  without a browser. This flag is accepted by login github only.
#### GitHub OIDC (CI/CD)

- Uses GitHub Actions OIDC tokens automatically
- Requires id-token: write permission in workflow
- No browser interaction needed
The CLI derives the OIDC aud claim from --registry (scheme + host, e.g.
https://registry.modelcontextprotocol.io) so tokens are bound to the specific
deployment they were minted for. Self-hosters must set
MCP_REGISTRY_GITHUB_OIDC_AUDIENCE on the registry to the matching value;
publishers running an older mcp-publisher will fail with invalid audience
and need to upgrade.
Also see the guide to publishing from GitHub Actions.
#### DNS Verification

- Verifies domain ownership via DNS TXT record
- Grants access to com.example.* namespaces
- Requires Ed25519 private key (64-character hex) or ECDSA P-384 private key (96-character hex)
  - --algorithm defaults to ed25519. For an ECDSA P-384 key you must pass --algorithm ecdsap384, otherwise the key is rejected with invalid seed length: expected 32 bytes, got 48.
  - The private key can be stored in a cloud signing provider like Google KMS or Azure Key Vault. Cloud providers derive the algorithm from the key itself, so --algorithm does not apply to them.
Setup: (for Ed25519, recommended)

Setup: (for ECDSA P-384)

Setup: (for Google KMS signing)
This requires the gcloud CLI.

Setup: (for Azure Key Vault signing)
This requires the Azure CLI.

#### HTTP Verification

- Verifies domain ownership via HTTPS endpoint  
- Grants access to com.example.* namespaces
- Requires Ed25519 private key (64-character hex) or ECDSA P-384 private key (96-character hex)
  - --algorithm defaults to ed25519. For an ECDSA P-384 key you must pass --algorithm ecdsap384.
  - The private key can be stored in a cloud signing provider like Google KMS or Azure Key Vault. Cloud providers derive the algorithm from the key itself, so --algorithm does not apply to them.
Setup: (for Ed25519, recommended)

Setup: (for ECDSA P-384)

Cloud signing is also supported for HTTP authentication, similar to the DNS examples above. Just swap out the dns positional argument for http.
#### Anonymous (Testing)

- No authentication - for local testing only
- Only works with local registry instances
mcp-publisher validate ')" title="Copy section prompt for LLMs"> Copy Section
Validate a server.json file without publishing.
Usage:

Arguments:
- file - Path to server.json file (default: ./server.json)
Behavior:
- Performs exhaustive validation, reporting all issues at once (not just the first error)
- Validates JSON syntax and schema compliance
- Runs semantic validation (business logic checks)
- Checks for deprecated schema versions and provides migration guidance
- Includes detailed error locations with JSON paths (e.g., packages[0].transport.url)
- Shows validation issue type (json, schema, semantic, linter)
- Displays severity level (error, warning, info)
- Provides schema references showing which validation rule triggered each error
Example output:

mcp-publisher publish ')" title="Copy section prompt for LLMs"> Copy Section
Publish server to the registry.
For detailed guidance on the publishing process, see the publishing guide.
Usage:

Options:
- PATH - Path to server.json (default: ./server.json)
Process:
1. Validates server.json against schema
2. Publishes the server.json to the registry server URL specified in the login token
3. Server: Verifies package ownership (see Official Registry Requirements)
4. Server: Checks namespace authentication
5. Server: Publishes to registry
Example:

mcp-publisher status ')" title="Copy section prompt for LLMs"> Copy Section
Update the lifecycle status of a published server.
Usage:

Flags:
- --status (required) - New status: active, deprecated, or deleted
- --message - Optional message explaining the status change (not allowed when status is active)
- --all-versions - Apply status change to all versions of the server
- --yes, -y - Skip confirmation prompt (only applies when using --all-versions)
Arguments:
- server-name - Full server name (e.g., io.github.user/my-server)
- version - Server version to update (required unless --all-versions is set)
Status Values:
- active - Server is active and visible in default listings
- deprecated - Server is deprecated but still visible with a warning message
- deleted - Server is hidden from default listings
Examples:

Requirements:
- Must be logged in with publish or edit permission for the server namespace
mcp-publisher logout ')" title="Copy section prompt for LLMs"> Copy Section
Clear stored authentication credentials.
Usage:

Behavior:
- Removes ~/.config/mcp-publisher/token.json
- Also cleans up legacy token files (~/.mcp_publisher_token, .mcpregistry_*)
- Does not revoke tokens on server side
Configuration  Copy Chapter
Token Storage  Copy Section

Authentication tokens are stored in ~/.config/mcp-publisher/token.json as JSON:

Note: Tokens were previously stored in ~/.mcp_publisher_token. If you are upgrading, run mcp-publisher logout followed by mcp-publisher login to migrate to the new location.
---
Reference/Api/CHANGELOG  Copy Section
Registry API Changelog
Changes to the REST API endpoints and responses.
Unreleased  Copy Chapter
Added  Copy Section
#### Server Status Management Endpoints
New endpoints for managing server lifecycle status:
- PATCH /v0/servers/{serverName}/versions/{version}/status - Update status of a specific server version
- PATCH /v0/servers/{serverName}/status - Update status of all versions of a server in a single transaction
Status values:
- active - Server is active and visible in default listings
- deprecated - Server is deprecated but still visible with a warning message
- deleted - Server is hidden from default listings
Authentication: Requires publish or edit permission for the server namespace.
#### New Response Fields
New fields added to _meta["io.modelcontextprotocol.registry/official"] (RegistryExtensions):
- statusChangedAt - Timestamp when the server status was last changed
- statusMessage - Optional message explaining status change (e.g., deprecation reason, migration guidance)
#### Server Filtering Enhancements
New include_deleted query parameter added to multiple endpoints:
- GET /v0/servers - Include deleted servers in list results (default: false, automatically true when updated_since is provided)
- GET /v0/servers/{serverName}/versions/{version} - Include deleted servers in detail results (default: false)
- GET /v0/servers/{serverName}/versions - Include deleted servers in version history (default: false)
2025-10-17  Copy Chapter
Added  Copy Section
#### API Versioning - v0.1 Introduction
Introduced /v0.1/ as a stable API version while /v0/ continues as the development version.
New version paths:
- All /v0/ endpoints are now also available at /v0.1/
- Both versions currently share identical behavior
- /v0/ will continue to evolve with additive changes (new optional fields, new endpoints)
- /v0.1/ will remain stable with only additive, backward-compatible changes
- Both versions will be maintained until a future v1.0 release
Migration guidance:
- Production applications should consider using /v0.1/ for stability
- Development and testing can continue using /v0/ for latest features
- No immediate action required - /v0/ remains fully supported
⚠️ BREAKING CHANGES  Copy Section
#### Endpoint Simplification
Removed redundant endpoint to simplify API surface and reduce implementation burden for subregistries.
Removed endpoints:
- GET /v0/servers/{serverName} - Use GET /v0/servers/{serverName}/versions/latest instead
2025-09-29  Copy Chapter
⚠️ BREAKING CHANGES  Copy Section
#### API Endpoint Restructuring
API endpoints updated to use server names instead of server IDs for better usability.
Changed endpoints:
- GET /v0/servers/{server_id} → GET /v0/servers/{serverName}
- GET /v0/servers/{server_id}/versions → GET /v0/servers/{serverName}/versions
New endpoints:
- GET /v0/servers/{serverName}/versions/{version} - Get specific server version
- PUT /v0/servers/{serverName}/versions/{version} - Edit server version (admin only)
Response format changes:
- Introduced ServerResponse schema separating server data from registry metadata
- Moved status field from server data to _meta.io.modelcontextprotocol.registry/official
- Removed io.modelcontextprotocol.registry/official metadata from ServerDetail schema
Changed  Copy Section

- OpenAPI spec version: 2025-09-16 → 2025-09-29
2025-09-16  Copy Chapter
⚠️ BREAKING CHANGES  Copy Section
#### Server ID Endpoints (#396)
API endpoints updated for consistent server identification across versions.
Problem: Each server version had a unique ID, preventing version history tracking and server renaming.
Solution: Introduced consistent server identification across versions.
Changed endpoints:
- GET /v0/servers/{id} → GET /v0/servers/{server_id}
New endpoints:
- GET /v0/servers/{server_id}/versions - List all versions of a server
- GET /v0/servers/{server_id}?version=1.0.0 - Get specific version
Changed response metadata:
- _meta..id → _meta..serverId
- Added: _meta.*.versionId
#### Migration Examples
Old Structure:

New Structure:

#### Migration Checklist for API Consumers
- [ ] Update API endpoint URLs from /v0/servers/{id} to /v0/servers/{server_id}
- [ ] Update code reading registry metadata from id to serverId/versionId
- [ ] Add support for new /v0/servers/{server_id}/versions endpoint if needed
- [ ] Update JSON parsing to expect camelCase field names
- [ ] Test with new API responses
Changed  Copy Section

- OpenAPI spec version: 2025-07-09 → 2025-09-16
2025-07-09  Copy Chapter
Initial release of the Registry API.
---
Reference/Api/Extensions  Copy Section
Registry Extensions Specification
A standardized way for registries to provide experimental or community-driven features without committing them to the core API specification.
Motivation  Copy Chapter
The core generic registry API intentionally stays minimal to ensure stability and broad adoption. Extensions provide a path for:
- Experimentation: Try new features without core API changes
- Community innovation: Anyone can implement custom extensions
- Gradual adoption: Popular extensions may inform future core API features
- Avoiding breaking changes: Failed experiments can be deprecated without API versioning churn
URL Structure  Copy Chapter
Extensions live under the /v0.1/x/ prefix:

Components:
- <namespace>: Reverse domain ownership (e.g., com.example, io.github.username)
- <extension>: Extension name (lowercase, hyphens for word separation)
- <path>: Extension-specific path structure (optional)
Examples:

Conventions  Copy Chapter
Where possible:
- Follow standard REST conventions, return simple JSON responses, and avoid special headers
- For list endpoints, use cursor-based pagination matching the core API
- Extensions requiring authentication SHOULD follow the Registry Authorization Specification
- Build open-source implementations in a composable way on top of the core APIs (e.g. as opposed to via custom database integration)
Implementation Requirements  Copy Chapter
Registries implementing extensions SHOULD namespace extensions properly to avoid conflicts.
Clients consuming extensions MUST gracefully handle missing extensions.
Example  Copy Chapter
A simple server stats extension:

Future Considerations  Copy Chapter
- Extension discovery: A potential /v0.1/x endpoint to list available extensions
- Extension metadata: Standardized metadata format for extension capabilities
- Defining common extensions: Like semantic conventions from OpenTelemetry, develop common extensions that registries can adopt (possibly under an experimental namespace)
  - Search extension for free-text search across server metadata (#389)
  - MCP server extension to expose the registry itself as an MCP server for programmatic access (#24)
---
Reference/Api/Generic Registry Api  Copy Section
Generic Registry API Specification
A standardized RESTful HTTP API for MCP registries to provide consistent endpoints for discovering and retrieving MCP servers.
Also see:
- For authentication and authorization, see the registry authorization specification.
Browse the Complete API Specification  Copy Chapter
📋 View the full API specification interactively: Open openapi.yaml in an OpenAPI viewer like Stoplight Elements.
The official registry has some more endpoints and restrictions on top of this. See the official registry API spec for details.
Quick Reference  Copy Chapter
Core Endpoints  Copy Section

- GET /v0.1/servers - List all servers with pagination
- GET /v0.1/servers/{serverName}/versions - List all versions of a server
- GET /v0.1/servers/{serverName}/versions/{version} - Get specific version of server. Use the special version latest to get the latest version.
- POST /v0.1/publish - Publish new server (optional, registry-specific authentication)
- PUT /v0.1/servers/{serverName}/versions/{version} - Update specific server version (optional; the official registry implements this as an admin endpoint)
- DELETE /v0.1/servers/{serverName}/versions/{version} - Delete specific server version (optional, not implemented by official registry)
- PATCH /v0.1/servers/{serverName}/versions/{version}/status - Update server version status (optional)
- PATCH /v0.1/servers/{serverName}/status - Update status for all versions (optional)
Server names and version strings should be URL-encoded in paths.
Authentication  Copy Section
No authentication required by default. Subregistries may optionally require authentication following the registry authorization specification.
Content Type  Copy Section

All requests and responses use application/json
Pagination  Copy Section

List endpoints use cursor-based pagination for efficient, stable results.
#### Usage
1. Initial request: Omit the cursor parameter
2. Subsequent requests: Use the nextCursor value from the previous response
3. End of results: When nextCursor is null or empty, there are no more results
Important: Always treat cursors as opaque strings. Never manually construct or modify cursor values.
Basic Example: List Servers  Copy Section

For complete endpoint documentation, view the OpenAPI specification in a schema viewer.
---
Reference/Api/Official Registry Api  Copy Section
Official MCP Registry API
This document describes the API for the official MCP Registry hosted at registry.modelcontextprotocol.io.
This API is based on the generic registry API with additional endpoints and authentication. For publishing servers using the API, see the publishing guide.
Base URLs  Copy Chapter
- Production: https://registry.modelcontextprotocol.io
- Staging: https://staging.registry.modelcontextprotocol.io
Interactive Documentation  Copy Chapter
- Live API Docs - Stoplight elements with try-it-now functionality
- OpenAPI Spec - Complete machine-readable specification
Extensions  Copy Chapter
The official registry implements the Generic Registry API with the following specific configurations and extensions:
Authentication  Copy Section
Publishing requires namespace-based authentication:
- GitHub OAuth - For io.github.* namespaces
- GitHub OIDC - For publishing from GitHub Actions  
- DNS verification - For domain-based namespaces (com.example.*)
- HTTP verification - For domain-based namespaces (com.example.*)
See Publisher Commands for authentication setup.
Package Validation  Copy Section
The official registry enforces additional package validation requirements when publishing.
Server List Filtering  Copy Section
The official registry extends the GET /v0.1/servers endpoint with additional query parameters for improved discovery and synchronization:
- updated_since - Filter servers updated after RFC3339 timestamp (e.g., 2025-08-07T13:15:04.280Z)
- search - Case-insensitive substring search on server names (e.g., filesystem)
    - This is intentionally simple. For more advanced searching and filtering, use a subregistry.
- version - Filter by version (currently supports latest for latest versions only)
- include_deleted - Include deleted servers in results (default: false, but automatically true when updated_since is provided for incremental sync)
These extensions enable efficient incremental synchronization for downstream registries and improved server discovery. Parameters can be combined and work with standard cursor-based pagination.
Example: GET /v0.1/servers?search=filesystem&updated_since=2025-08-01T00:00:00Z&version=latest
Server Detail  Copy Section
The GET /v0.1/servers/{serverName}/versions/{version} endpoint returns detailed information about a specific server version.
Path parameters:
- serverName - URL-encoded server name (e.g., io.github.user%2Fmy-server)
- version - Server version or latest for the most recent version
Query parameters:
- include_deleted - Include deleted servers in results (default: false)
Server Version History  Copy Section
The GET /v0.1/servers/{serverName}/versions endpoint returns all versions of a server.
Path parameters:
- serverName - URL-encoded server name (e.g., io.github.user%2Fmy-server)
Query parameters:
- include_deleted - Include deleted servers in results (default: false)
Additional endpoints  Copy Section
#### Auth endpoints
- POST /v0.1/auth/dns - Exchange signed DNS challenge for auth token
- POST /v0.1/auth/http - Exchange signed HTTP challenge for auth token
- POST /v0.1/auth/github-at - Exchange GitHub access token for auth token
- POST /v0.1/auth/github-oidc - Exchange GitHub OIDC token for auth token
- POST /v0.1/auth/oidc - Exchange Google OIDC token for auth token (for admins)
#### Status endpoints
##### Update Single Version Status
PATCH /v0.1/servers/{serverName}/versions/{version}/status - Update status of a specific server version.
Path parameters:
- serverName - URL-encoded server name (e.g., io.github.user%2Fmy-server)
- version - Server version to update
Request body:
- status (required) - New status: active, deprecated, or deleted
- statusMessage (optional) - Message explaining the status change (max 500 characters, not allowed when status is active)
##### Update All Versions Status
PATCH /v0.1/servers/{serverName}/status - Update status of all versions of a server in a single transaction.
Path parameters:
- serverName - URL-encoded server name (e.g., io.github.user%2Fmy-server)
Request body:
- status (required) - New status: active, deprecated, or deleted
- statusMessage (optional) - Message explaining the status change (max 500 characters, not allowed when status is active)
Status values:
- active - Server is active and visible in default listings
- deprecated - Server is deprecated but still visible with a warning message
- deleted - Server is hidden from default listings (use include_deleted=true to show)
Authentication: Requires publish or edit permission for the server namespace.
#### Validation endpoint
- POST /v0.1/validate - Validate a server.json without publishing it. Used by mcp-publisher validate.
#### Service endpoints
- GET /v0.1/ping - Liveness check
- GET /v0.1/version - Registry version information
#### Admin endpoints
- GET /metrics - Prometheus metrics endpoint
- GET /v0.1/health - Basic health check endpoint
- PUT /v0.1/servers/{serverName}/versions/{version} - Edit specific server version
Note that /v0.1/validate, /v0.1/ping, /v0.1/version and /v0.1/health are not described in
openapi.yaml, which covers the server and publish endpoints only.
---
Reference/Api/Registry Authorization  Copy Section
Registry Authorization
MCP registries wishing to implement authentication SHOULD follow the MCP Authorization Specification.
How it works  Copy Chapter
The registry acts as an OAuth 2.1 Resource Server, identical to how MCP servers work. This means:
- MCP clients can reuse their existing MCP authorization implementation without any changes
- Registries validate access tokens the same way MCP servers do
- Users get a consistent login experience across MCP servers and registries
Registry-Specific Scopes  Copy Chapter
Registries MAY use these scopes:
- mcp-registry:read - List and read server metadata
- mcp-registry:write - Publish, update, and delete servers
These are recommendations - registries may use any set of scopes they deem sensible.
Note that scopes only control what types of operations a user can perform. Registries should still apply user-level authorization to control which specific resources a user can access. For example, a user with mcp-registry:write might only be able to publish servers to namespaces they own, and may not have permissions to edit servers if the registry treats servers as immutable.
Official Registry Authentication  Copy Chapter
The official modelcontextprotocol.io registry remains public for reading. For publishing servers, it uses a custom JWT-based authentication system for legacy reasons - see its API spec. This may change in future to align with the MCP Authorization Specification.
---
Reference/Server Json/CHANGELOG  Copy Section
Server JSON Schema Changelog
Changes to the server.json schema and format.
Draft (Unreleased)  Copy Chapter
This section tracks changes that are in development and not yet released. The draft schema is available at server.schema.json in this repository.
Changed  Copy Section
#### Transport URL Pattern Now Accepts Template Variables
The url field in StreamableHttpTransport and SseTransport now accepts URLs that start with a template variable (e.g., {baseUrl}), in addition to the existing http:// and https:// prefixes.
Example:

Migration: No changes required. Existing servers continue to work unchanged.
Notes  Copy Section
When ready for release, changes in this section will be moved to a dated version section (e.g., ## 2025-XX-XX) and the schema will be published to a versioned URL.
---
2025-12-11  Copy Chapter
Changed  Copy Section
#### URL Template Variables for Remote Servers (#570)
Remote servers can now define URL template variables using {curly_braces} notation. This enables multi-tenant deployments where a single server definition can support multiple endpoints with configurable values.
Example:

Migration: No changes required. Existing servers continue to work unchanged.
---
2025-10-17  Copy Chapter
Changed  Copy Section
The version field is now optional for MCPB packages, providing flexibility for publishers.
Key Changes:
- MCPB packages can now include an optional version field - Previously rejected by validation, MCPB packages can now optionally specify a version field for clarity and metadata purposes.
- Both formats are valid:
  - MCPB packages with version field: Provides explicit version metadata
  - MCPB packages without version field: Version information is embedded in the download URL (as before)
Migration:
Publishers using MCPB packages can optionally add a version field to their package configuration. This is particularly useful when:
- The version information is not clearly visible in the download URL
- You want to provide explicit version metadata for tooling and clients
- You need consistent version tracking across different package types
Existing MCPB packages without the version field continue to work without any changes.
Example - MCPB Package with optional version:

Example - MCPB Package without version (still valid):

Schema Version  Copy Section

- Schema version: 2025-10-11 → 2025-10-17
2025-10-11  Copy Chapter
Changed  Copy Section
#### Package Format Enhancements (#634)
The Package schema has been refactored to better support different package types with dedicated handling per registry type.
Key Changes:
- version field is now optional - Previously required for all packages, now only used by npm, pypi, and nuget. OCI packages include version in the identifier (e.g., ghcr.io/owner/repo:v1.0.0), and MCPB packages use direct download URLs.
- Enhanced documentation - Added detailed comments explaining which fields are relevant for each registryType:
  - NPM/PyPI/NuGet: Use registryType, identifier (package name), version, optional registryBaseUrl
  - OCI: Use registryType, identifier (full image reference with tag)
  - MCPB: Use registryType, identifier (download URL), fileSha256 (required)
- Field clarifications:
  - identifier: Now clearly documented as package name for registries, full image reference for OCI, or download URL for MCPB
  - fileSha256: Clarified as required for MCPB packages and optional for other types
  - registryBaseUrl: Clarified as used by npm/pypi/nuget but not by oci/mcpb
Migration:
Publishers using OCI or MCPB packages can now omit the version field, as it's either embedded in the identifier (OCI) or not applicable (MCPB direct downloads). Publishers using npm, pypi, or nuget should continue to provide the version field as before.
Example - OCI Package (version in identifier):

Example - MCPB Package (no version field):

Schema Version  Copy Section

- Schema version: 2025-09-29 → 2025-10-11
2025-09-29  Copy Chapter
⚠️ BREAKING CHANGES  Copy Section
#### Schema Simplification
Removed registry-managed fields from publisher-controlled server.json schema.
Removed fields:
- status field from Server object (now managed by registry in API responses)
- io.modelcontextprotocol.registry/official from _meta (read-only, added by registry)
Migration:
Publishers should remove these fields from their server.json files. The registry will manage server status and official metadata separately.
Changed  Copy Section

- Schema version: 2025-09-16 → 2025-09-29
2025-09-16  Copy Chapter
⚠️ BREAKING CHANGES  Copy Section
#### Field Names: snake_case → camelCase (#428)
All JSON field names standardized to camelCase. All existing server.json files must be updated.
Changed fields:
- registry_type → registryType
- registry_base_url → registryBaseUrl
- file_sha256 → fileSha256
- runtime_hint → runtimeHint
- runtime_arguments → runtimeArguments
- package_arguments → packageArguments
- environment_variables → environmentVariables
- is_required → isRequired
- is_secret → isSecret
- value_hint → valueHint
- is_repeated → isRepeated
- website_url → websiteUrl
#### Migration Examples
Package Configuration:

Arguments Configuration:

Environment Variables:

#### Migration Checklist for Publishers
- [ ] Update your server.json files to use camelCase field names
- [ ] Test server publishing with new CLI version
- [ ] Update any automation scripts that reference old field names
- [ ] Update documentation referencing old field names
#### Updated Schema Reference
🔗 Current schema: https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json
Changed  Copy Section

- Schema version: 2025-07-09 → 2025-09-16
2025-07-09  Copy Chapter
Initial release of the server.json schema.
---
Reference/Server Json/CONTRIBUTING  Copy Section
Contributing to server.json Schema
This document describes the process for making and releasing changes to the server.json schema.
Making Changes  Copy Chapter
1. Modify the OpenAPI spec: Edit docs/reference/api/openapi.yaml with your schema changes. The ServerDetail component defines the server.json structure.
2. Regenerate the schema: Run make generate-schema to update server.schema.json from the OpenAPI spec.
3. Update the changelog: Add your changes to the "Draft (Unreleased)" section in CHANGELOG.md.
4. Open a PR: Submit a pull request to this repository for review.
Releasing Changes  Copy Chapter
When the draft changes are ready for release:
1. Update the changelog: Move changes from "Draft (Unreleased)" to a new dated section (e.g., ## 2025-XX-XX).
2. Update the schema URL: Change the $id in the schema and the example URL in openapi.yaml from draft to the release date (e.g., 2025-XX-XX).
3. Merge the PR: Get approval and merge the changes to main.
4. Publish to static hosting: Open a PR on modelcontextprotocol/static to add the new versioned schema file. This "locks in" the released schema at its versioned URL.
Schema Versioning  Copy Chapter
- Draft schema: https://raw.githubusercontent.com/modelcontextprotocol/registry/main/docs/reference/server-json/draft/server.schema.json - For in-progress changes, may change without notice.
- Released schemas: https://static.modelcontextprotocol.io/schemas/YYYY-MM-DD/server.schema.json - Stable, versioned by release date.
---
Reference/Server Json/Generic Server Json  Copy Section
server.json Format Specification
A server.json file is a standardized way to describe MCP servers for registry publishing, client discovery, and package management.
Also see:
- For step-by-step instructions on creating and using server.json files, see the publishing guide.
- For understanding the validation requirements when publishing to the official registry, see official registry requirements.
Browse the Complete Schema  Copy Chapter
📋 View the full specification interactively: Open server.schema.json in a schema viewer like json-schema.app.
The schema contains all field definitions, validation rules, examples, and detailed descriptions.
The official registry has some more restrictions on top of this. See the official registry requirements for details.
Extension Metadata with _meta ')" title="Copy chapter prompt for LLMs"> Copy Chapter
The optional _meta field allows publishers to include custom metadata alongside their server definitions using reverse DNS namespacing.

When publishing to the official registry, custom metadata must be placed under the key io.modelcontextprotocol.registry/publisher-provided. See the official registry requirements for detailed restrictions and examples.
Examples  Copy Chapter
Basic Server with NPM Package  Copy Section

Server in a Monorepo with Subfolder  Copy Section
For MCP servers located within a subdirectory of a larger repository (monorepo structure), use the subfolder field to specify the relative path: