Plugin developer guide

Publish an MCP server to the official MCP Registry

By HOL · Reviewed by Michael Kantor on

Direct answer

Describe the server in server.json, named in your namespace such as io.github.owner/server, and prove you own the package, for npm with a matching mcpName in package.json. hol-guard plugin package --runtimes mcp-registry writes server.json from the repository, or generates one for a single remote server. Then run mcp-publisher login github and mcp-publisher publish, and confirm the entry through the Registry API.

Who this is for

MCP server authors who want their server in the official registry that clients and catalogs read.

Good fit

  • An npm, PyPI or OCI packaged MCP server
  • A remote MCP server hosted from a GitHub project
  • A server that also ships as a plugin for agent runtimes

Not a fit

  • Skills, commands and hooks, which the Registry does not describe

Steps

  1. 1.Install HOL Guard

    The Plugin Kit ships inside HOL Guard. It needs Python 3.10 or newer and pipx. If Guard is already installed, upgrade it so the Kit commands below are available.

    pipx install hol-guard
pipx upgrade hol-guard
hol-guard --version

  2. 2.Check the plugin

    The check detects every manifest in the folder, lists skills and MCP servers, and reports what each runtime would reject. It exits 0 when the plugin passes, 1 when it has errors and 2 when it could not run. It reads only the folder, runs no commands and makes no network calls.

    hol-guard plugin check .

  3. 3.Write server.json

    The Kit copies the repository's own server.json, or generates one for a single remote MCP server on GitHub. mcp-publisher init also writes a template.

    hol-guard plugin package . --runtimes mcp-registry --out dist/hol-plugin

  4. 4.Prove package ownership

    For npm, add mcpName to package.json with exactly the name in server.json, such as io.github.owner/server, and publish that package version.

  5. 5.Log in and publish

    Install mcp-publisher, sign in with GitHub through the device flow and publish. GitHub sign-in grants your personal io.github.username namespace. An organization namespace needs a token with read:org or GitHub Actions OIDC, and DNS or HTTP verification grants a domain namespace.

    brew install mcp-publisher
mcp-publisher login github
mcp-publisher publish

  6. 6.Confirm the entry

    Search the Registry API for your server name and check the version you published.

    curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.owner/server"

  7. 7.Add the install block to your README

    hol-guard plugin links --block prints a README block between hol-install-block markers: one hol-guard plugin install command, how to get HOL Guard, and each runtime's own install commands for the runtimes the repository already supports. Paste it into the README; HOL finds it on its next scan and shows the install count on your listing once enough installs are reported.

    hol-guard plugin links . --block

  8. 8.Connect the repository on HOL

    Open the connect page with your repository to verify ownership and claim the listing. hol-guard plugin links prints the same link with the repository filled in.

    hol-guard plugin links .

Limitations

  • A local server.json is not a publication. hol-guard plugin links keeps the Registry step open because it cannot see the authenticated publish.
  • The Registry stores metadata; it does not host or review your package.
  • A listing, a passing check or a marketplace review is not a safety guarantee. HOL shows its scan evidence on the listing so users can judge for themselves.

Questions

Do I need a package to publish?

No. A remote server can be published with a remotes entry instead of packages.

Can I use my own domain as the namespace?

Yes. Verify the domain with a DNS TXT record or a file at /.well-known/mcp-registry-auth, then name the server in reverse-DNS form, such as com.example/server.

Sources

Related guides

List it on HOL

Connect the repository to verify ownership and claim the listing. New plugins can be submitted for free.

Connect your plugin repository