{
  "slug": "mcp-server-registry-publishing-playbook",
  "title": "How to Publish an MCP Server to the Official Registry",
  "description": "A step-by-step walkthrough of the mcp-publisher CLI and the server.json manifest for publishing an MCP server to registry.modelcontextprotocol.io, how to republish after a version bump, and how the registry relates to aggregators, marketplaces, and direct distribution.",
  "kind": "sub",
  "order": 7,
  "target_query": "how to publish an MCP server to the official registry",
  "secondary_queries": [
    "server.json manifest fields for the MCP registry",
    "mcp-publisher CLI walkthrough",
    "updating a published MCP registry listing",
    "submitting an MCP server to PulseMCP Smithery Glama MCP.so"
  ],
  "tags": [
    "mcp",
    "registry",
    "publishing",
    "distribution",
    "agents",
    "production"
  ],
  "published": "2026-08-15",
  "updated": "2026-08-15",
  "words": 1214,
  "premium": false,
  "license": "https://changegamer.ai/license.xml",
  "canonical": "https://changegamer.ai/articles/mcp-server-registry-publishing-playbook",
  "markdown": "https://changegamer.ai/articles/mcp-server-registry-publishing-playbook.md",
  "takeaways": [
    "Publishing an MCP server to the official registry runs through four mcp-publisher CLI steps — init, editing the generated server.json, mcp-publisher login github, and mcp-publisher publish — and none of them uploads the server package itself, which has to already exist on npm, PyPI, or another artifact registry first.",
    "A server.json manifest for the MCP registry states at minimum the server's name, version, transport type, and endpoint URL, validated against the schema at https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json; the schema defines further fields beyond those four, so consult it directly rather than assuming a field name this article has not stated.",
    "Updating a registry listing after a new release starts outside the registry entirely: the new package version has to reach npm, PyPI, or wherever it lives first, because the registry stores metadata only and never hosts the package itself.",
    "The official MCP registry remained in preview as of mid-2026, roughly a year after its September 2025 preview launch backed by Anthropic, GitHub, PulseMCP, and Microsoft.",
    "Community aggregators such as PulseMCP, Smithery, Glama, and MCP.so vary considerably in how rigorously they vet listings, so a server's presence on one is worth treating as a lead to investigate rather than an endorsement of its safety."
  ],
  "outline": [
    {
      "depth": 2,
      "text": "The mcp-publisher CLI walkthrough",
      "anchor": "the-mcp-publisher-cli-walkthrough",
      "url": "https://changegamer.ai/articles/mcp-server-registry-publishing-playbook#the-mcp-publisher-cli-walkthrough"
    },
    {
      "depth": 2,
      "text": "What goes into the server.json manifest?",
      "anchor": "what-goes-into-the-server-json-manifest",
      "url": "https://changegamer.ai/articles/mcp-server-registry-publishing-playbook#what-goes-into-the-server-json-manifest"
    },
    {
      "depth": 2,
      "text": "How do you update a registry listing after a new release?",
      "anchor": "how-do-you-update-a-registry-listing-after-a-new-release",
      "url": "https://changegamer.ai/articles/mcp-server-registry-publishing-playbook#how-do-you-update-a-registry-listing-after-a-new-release"
    },
    {
      "depth": 2,
      "text": "Aggregators, marketplaces, and direct distribution after you publish",
      "anchor": "aggregators-marketplaces-and-direct-distribution-after-you-publish",
      "url": "https://changegamer.ai/articles/mcp-server-registry-publishing-playbook#aggregators-marketplaces-and-direct-distribution-after-you-publish"
    },
    {
      "depth": 2,
      "text": "Where this leaves you",
      "anchor": "where-this-leaves-you",
      "url": "https://changegamer.ai/articles/mcp-server-registry-publishing-playbook#where-this-leaves-you"
    }
  ],
  "faq": [
    {
      "question": "What does mcp-publisher init actually do?",
      "answer": "Running mcp-publisher init generates a starter server.json manifest inside your project directory, which you then edit by hand to describe your server's name, version, transport type, and endpoint URL before you attempt to publish it. It does not touch the official registry itself — that only happens once you run mcp-publisher publish after logging in."
    },
    {
      "question": "Do I need to publish my package to npm before publishing to the MCP registry?",
      "answer": "Yes — the MCP registry stores metadata only, so the actual server package must already be published to npm, PyPI, or another artifact registry before mcp-publisher can point a registry listing at it. Attempting to publish a server.json that references a package that is not yet live at its artifact registry has no documented success path in the corpus behind this article."
    },
    {
      "question": "How do I update my MCP server's registry listing after shipping a new version?",
      "answer": "Publish the new package version to its artifact registry first, then bump the version field in your server.json to match it and re-run the same mcp-publisher publish command you used the first time. No corpus source for this article documents a separate update subcommand or a registry versioning API, so this sequence is a reasoned inference from the registry being metadata-only, not a confirmed CLI reference — verify current mcp-publisher flags before relying on it for anything beyond a routine version bump."
    },
    {
      "question": "Should I also submit my MCP server to PulseMCP, Smithery, Glama, or MCP.so?",
      "answer": "Submitting to community aggregators after registry publication is a reasonable next step for visibility, but treat any resulting listing as a lead worth investigating rather than a safety endorsement, since these directories vary considerably in how rigorously they review what they list. This article's source material does not document specific submission forms, review timelines, or listing fees for any of the four, so nothing beyond that general caution is verified."
    }
  ],
  "body": "The pillar's [distribution section](/articles/mcp-server-in-production) names all four channels an MCP server reaches users through — registry, aggregators, marketplaces, direct — and ranks the registry as the highest-leverage first move because it seeds the other three. This article is the one channel that section only summarizes: the actual publish flow, command by command, what a server.json manifest has to say, and what changes on your next release six months later.\n\n## The mcp-publisher CLI walkthrough\n\nPublishing to the official MCP registry (registry.modelcontextprotocol.io) runs through four steps with the mcp-publisher CLI, and each one does something distinct rather than being a formality on the way to the next ([Finding and Evaluating MCP Servers](/resources/mcp-server-discovery)).\n\n- **`mcp-publisher init`** scaffolds a starter server.json manifest in your project. This step does not talk to the registry at all — it just gives you a file to edit.\n- **Edit server.json by hand.** Fill in the fields the schema requires (covered in the next section) so the manifest accurately describes the server you have already built and already published as a package elsewhere.\n- **`mcp-publisher login github`** authenticates you against the registry using your GitHub identity. This is the step that ties a listing to an accountable publisher — the registry uses GitHub auth specifically, not an arbitrary username and password.\n- **`mcp-publisher publish`** submits the finished server.json to the registry, creating or updating your listing there.\n\nOne detail worth being explicit about because it changes how you sequence a release: none of these four steps uploads your server's actual code or package artifact. The registry indexes metadata — a pointer to where the real thing lives — so the package itself has to already be reachable on npm, PyPI, or another artifact registry before publish makes sense ([Building an MCP Server](/resources/building-mcp-servers)). Run mcp-publisher publish against a server.json that points at a package that does not yet exist anywhere, and there is no documented success path for that in either resource this article draws from.\n\n## What goes into the server.json manifest?\n\nA server.json manifest states, at minimum, your server's name, its version, which transport it uses, and the endpoint URL it is reachable at — those are the four fields the corpus behind this article actually verifies as required. The file is validated against a fixed schema, published at `https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json`, so pointing your editor or a CI lint step at that URL is the way to catch a malformed manifest before you run publish rather than after.\n\nEach of the four fields does a specific job in how the registry and downstream consumers use the listing:\n\n- **Name** — how your server is identified in the registry's catalog and in any search or listing UI built on top of it.\n- **Version** — the version of the package this listing points at. This is the field you bump on every release (more on that below).\n- **Transport type** — stdio or Streamable HTTP, so a client or aggregator knows how to connect before it tries.\n- **Endpoint URL** — where a remote server is actually reachable, or the equivalent reference for a stdio server distributed as a package rather than a live endpoint.\n\nThe schema almost certainly defines fields beyond these four — package metadata, repository links, and similar descriptive data are the kind of thing a registry manifest schema typically carries — but neither resource this article is grounded in enumerates that full field set, and this session has no way to fetch the schema live and verify it. Treat the four fields above as what is confirmed, and read the schema at the URL above directly before you assume any additional field name.\n\n## How do you update a registry listing after a new release?\n\nUpdating a listing after you ship a new server version starts outside the registry, because the registry stores metadata only and has nothing of its own to version — the package it points at is the thing that actually changes. The sequence that follows directly from that fact: publish the new package version to npm, PyPI, or wherever your artifact already lives first, exactly the way you published the version already listed. Only once that new version exists at its artifact registry does re-running the manifest path make sense — bump the version field in your local server.json to match, and run `mcp-publisher publish` again, the same command you used the first time.\n\nThat is a reasoned inference from \"the registry is metadata only,\" stated plainly as inference and not as a documented feature: neither resource this article draws from names a separate `mcp-publisher update` subcommand or describes a registry versioning API distinct from publish itself. If the CLI's current behavior differs — a dedicated update path, additional flags, a different flow for a version bump versus a first-time listing — that would be new information beyond what this article's sources confirm, so check the CLI's own help output or its GitHub repository (github.com/modelcontextprotocol/registry, which also hosts the server.json spec) before treating this sequence as more than a reasonable default.\n\n## Aggregators, marketplaces, and direct distribution after you publish\n\nPublishing to the official registry is what seeds the other three channels rather than replacing them, and each behaves differently once your listing exists. PulseMCP, Smithery, Glama, and MCP.so, the four community aggregators active as of mid-2026, run their own independent listing decisions, with inconsistent depth of vetting from one to the next — a listing there signals that a candidate integrator might find you, nothing more, since none of it substitutes for that integrator doing their own review. Neither resource behind this article documents specific submission forms, review timelines, or listing fees for any of the four, so this article does not state any — if you are chasing a listing on a specific aggregator, its own site is the only reliable source for how that works as of mid-2026.\n\nClient-vendor marketplaces are a second channel: AI-assistant and IDE vendors increasingly ship their own curated server lists inside their products, and how a server gets onto one is governed by that vendor's own documentation, not by anything the registry controls. Publishing from your own site or repository is the fourth channel, and once you exist across the other three it is the one worth steering an integrator toward directly, because a source you control outranks any copy of it someone else hosts; the registry listing and any aggregator presence work as pointers toward that source, not substitutes for it.\n\n## Where this leaves you\n\nTreat mcp-publisher init through publish as a four-step sequence where only the last two steps touch the registry itself, keep your server.json's four confirmed fields — name, version, transport type, endpoint URL — accurate against a package that is already live elsewhere, and republish on every version bump by updating the package first and the manifest second. The registry remains in preview as of mid-2026, but it is still the move that seeds everything downstream of it — aggregators, marketplaces, and the direct listing an integrator eventually lands on. For the full four-channel distribution picture this article sits inside, see [MCP server in production](/articles/mcp-server-in-production); for evaluating a server you are considering connecting to rather than publishing one yourself, see [Finding and Evaluating MCP Servers](/resources/mcp-server-discovery) and [Building an MCP Server](/resources/building-mcp-servers).",
  "cluster": {
    "id": "mcp-in-practice",
    "title": "MCP in practice",
    "description": "How to build, ship and run an MCP server in production — transport, auth, tool design, versioning, testing, distribution, observability, cost and failure modes.",
    "status": "complete",
    "pillar": {
      "slug": "mcp-server-in-production",
      "title": "MCP Server in Production: How to Build, Ship and Run One",
      "description": "The operator playbook for taking an MCP server past the quickstart: transport choice, OAuth 2.1 auth, tool design, versioning against a moving spec, testing across clients, distribution, observability, cost and the failure modes that show up once real clients connect.",
      "kind": "pillar",
      "order": 0,
      "html": "https://changegamer.ai/articles/mcp-server-in-production",
      "markdown": "https://changegamer.ai/articles/mcp-server-in-production.md",
      "json": "https://changegamer.ai/api/articles/mcp-server-in-production.json"
    },
    "articles": [
      {
        "slug": "mcp-stdio-vs-streamable-http",
        "title": "stdio vs. Streamable HTTP for MCP Servers: A Decision Framework",
        "description": "Which MCP transport to build against and why: the single-client-vs-shared decision rule, how state works without a session handshake under the 2026-07-28 spec, the auth-model switching cost, and what actually breaks migrating off HTTP+SSE.",
        "kind": "sub",
        "order": 1,
        "html": "https://changegamer.ai/articles/mcp-stdio-vs-streamable-http",
        "markdown": "https://changegamer.ai/articles/mcp-stdio-vs-streamable-http.md",
        "json": "https://changegamer.ai/api/articles/mcp-stdio-vs-streamable-http.json"
      },
      {
        "slug": "mcp-oauth-implementation",
        "title": "How to Implement OAuth 2.1 for an MCP Server",
        "description": "A wire-level implementation walkthrough for OAuth 2.1 on a remote MCP server: what the discovery documents actually contain, CIMD vs. Dynamic Client Registration in your server code, per-SEP detail from the 2026-07-28 hardening set, and token-validation mechanics.",
        "kind": "sub",
        "order": 2,
        "html": "https://changegamer.ai/articles/mcp-oauth-implementation",
        "markdown": "https://changegamer.ai/articles/mcp-oauth-implementation.md",
        "json": "https://changegamer.ai/api/articles/mcp-oauth-implementation.json"
      },
      {
        "slug": "mcp-tool-description-injection",
        "title": "Defending MCP Clients Against Tool Description and Output Injection",
        "description": "Two distinct MCP injection surfaces — a tool description at connect-time and a tool's return value at call-time — and the client-side architectural patterns (Dual LLM, Action-Selector, Context-Minimization) that contain each one.",
        "kind": "sub",
        "order": 3,
        "html": "https://changegamer.ai/articles/mcp-tool-description-injection",
        "markdown": "https://changegamer.ai/articles/mcp-tool-description-injection.md",
        "json": "https://changegamer.ai/api/articles/mcp-tool-description-injection.json"
      },
      {
        "slug": "testing-mcp-servers-in-ci",
        "title": "How to Test an MCP Server in CI",
        "description": "The implementation mechanics below the three-layer test pyramid: what a mocked MCP transport actually replaces, what a Streamable HTTP cassette contains, a concrete CI job/trigger shape, and how to catch spec-version drift before it reaches production.",
        "kind": "sub",
        "order": 4,
        "html": "https://changegamer.ai/articles/testing-mcp-servers-in-ci",
        "markdown": "https://changegamer.ai/articles/testing-mcp-servers-in-ci.md",
        "json": "https://changegamer.ai/api/articles/testing-mcp-servers-in-ci.json"
      },
      {
        "slug": "mcp-server-versioning-and-spec-migration",
        "title": "MCP Server Versioning and Spec Migration: An Operator Playbook",
        "description": "A migration runbook for MCP server operators: feature-detecting via capabilities instead of hard protocolVersion branching, a dual-version fleet rollout with rollback triggers, a compatibility shim for legacy clients still sending initialize, and a deprecation calendar built off the 12-month SEP-2577 floor.",
        "kind": "sub",
        "order": 5,
        "html": "https://changegamer.ai/articles/mcp-server-versioning-and-spec-migration",
        "markdown": "https://changegamer.ai/articles/mcp-server-versioning-and-spec-migration.md",
        "json": "https://changegamer.ai/api/articles/mcp-server-versioning-and-spec-migration.json"
      },
      {
        "slug": "mcp-server-observability-opentelemetry",
        "title": "MCP Server Observability with OpenTelemetry: Spans, Metrics, and Trace Correlation",
        "description": "Instrumenting an MCP server past the pillar's baseline: what to put on a tool-call span beyond gen_ai.tool.name, what replaces the deprecated Logging primitive in practice, per-tool-name latency and error-rate metrics, and how a trace ID actually survives the agent-to-upstream-API hop.",
        "kind": "sub",
        "order": 6,
        "html": "https://changegamer.ai/articles/mcp-server-observability-opentelemetry",
        "markdown": "https://changegamer.ai/articles/mcp-server-observability-opentelemetry.md",
        "json": "https://changegamer.ai/api/articles/mcp-server-observability-opentelemetry.json"
      },
      {
        "slug": "mcp-server-registry-publishing-playbook",
        "title": "How to Publish an MCP Server to the Official Registry",
        "description": "A step-by-step walkthrough of the mcp-publisher CLI and the server.json manifest for publishing an MCP server to registry.modelcontextprotocol.io, how to republish after a version bump, and how the registry relates to aggregators, marketplaces, and direct distribution.",
        "kind": "sub",
        "order": 7,
        "html": "https://changegamer.ai/articles/mcp-server-registry-publishing-playbook",
        "markdown": "https://changegamer.ai/articles/mcp-server-registry-publishing-playbook.md",
        "json": "https://changegamer.ai/api/articles/mcp-server-registry-publishing-playbook.json"
      },
      {
        "slug": "mcp-server-cost-optimization",
        "title": "MCP Server Cost Optimization: Toolset Size, Caching Hints, and Fan-Out",
        "description": "How the token cost of an MCP server's tool list, the 2026-07-28 spec's ttlMs/cacheScope caching hints, fan-out from callers you do not control, and per-tool-name cost visibility each shape what a production MCP server actually costs to run.",
        "kind": "sub",
        "order": 8,
        "html": "https://changegamer.ai/articles/mcp-server-cost-optimization",
        "markdown": "https://changegamer.ai/articles/mcp-server-cost-optimization.md",
        "json": "https://changegamer.ai/api/articles/mcp-server-cost-optimization.json"
      },
      {
        "slug": "mcp-server-failure-modes",
        "title": "Common MCP Server Failure Modes and How to Fix Them",
        "description": "A runtime playbook for the two MCP server failure modes with no dedicated deep-dive elsewhere: unrecoverable state after a mid-call crash, and malformed or hallucinated tool calls that reach the handler despite upstream validation.",
        "kind": "sub",
        "order": 9,
        "html": "https://changegamer.ai/articles/mcp-server-failure-modes",
        "markdown": "https://changegamer.ai/articles/mcp-server-failure-modes.md",
        "json": "https://changegamer.ai/api/articles/mcp-server-failure-modes.json"
      },
      {
        "slug": "mcp-resources-and-prompts-vs-tools",
        "title": "MCP Tools vs Resources vs Prompts: How to Choose the Right Primitive",
        "description": "A decision procedure for MCP's three server-side primitives — who controls each one, a worked example of what it costs to expose a Resource as a Tool by mistake, and how Sampling and Elicitation fit as the client-side counterparts.",
        "kind": "sub",
        "order": 10,
        "html": "https://changegamer.ai/articles/mcp-resources-and-prompts-vs-tools",
        "markdown": "https://changegamer.ai/articles/mcp-resources-and-prompts-vs-tools.md",
        "json": "https://changegamer.ai/api/articles/mcp-resources-and-prompts-vs-tools.json"
      },
      {
        "slug": "mcp-server-production-launch-checklist",
        "title": "The MCP Server Production Launch Checklist",
        "description": "A phase-by-phase go/no-go checklist for launching an MCP server: checkable gate conditions for transport and auth, tool design, cross-client testing, publish readiness, observability, and ongoing operation — with links to the mechanics each gate depends on.",
        "kind": "sub",
        "order": 11,
        "html": "https://changegamer.ai/articles/mcp-server-production-launch-checklist",
        "markdown": "https://changegamer.ai/articles/mcp-server-production-launch-checklist.md",
        "json": "https://changegamer.ai/api/articles/mcp-server-production-launch-checklist.json"
      },
      {
        "slug": "mcp-enterprise-sso-id-jag",
        "title": "Zero-Touch Enterprise Authorization for MCP Servers: ID-JAG and SEP-990",
        "description": "How Enterprise-Managed Authorization (SEP-990) removes the per-server OAuth consent screen for MCP servers: the ID-JAG grant mechanism, its RFC 8693/7523 building blocks, named launch adopters as of August 2026, and how it layers on top of standard OAuth 2.1 rather than replacing it.",
        "kind": "sub",
        "order": 12,
        "html": "https://changegamer.ai/articles/mcp-enterprise-sso-id-jag",
        "markdown": "https://changegamer.ai/articles/mcp-enterprise-sso-id-jag.md",
        "json": "https://changegamer.ai/api/articles/mcp-enterprise-sso-id-jag.json"
      }
    ]
  },
  "navigation": {
    "pillar": {
      "slug": "mcp-server-in-production",
      "title": "MCP Server in Production: How to Build, Ship and Run One",
      "description": "The operator playbook for taking an MCP server past the quickstart: transport choice, OAuth 2.1 auth, tool design, versioning against a moving spec, testing across clients, distribution, observability, cost and the failure modes that show up once real clients connect.",
      "kind": "pillar",
      "order": 0,
      "html": "https://changegamer.ai/articles/mcp-server-in-production",
      "markdown": "https://changegamer.ai/articles/mcp-server-in-production.md",
      "json": "https://changegamer.ai/api/articles/mcp-server-in-production.json"
    },
    "previous": {
      "slug": "mcp-server-observability-opentelemetry",
      "title": "MCP Server Observability with OpenTelemetry: Spans, Metrics, and Trace Correlation",
      "description": "Instrumenting an MCP server past the pillar's baseline: what to put on a tool-call span beyond gen_ai.tool.name, what replaces the deprecated Logging primitive in practice, per-tool-name latency and error-rate metrics, and how a trace ID actually survives the agent-to-upstream-API hop.",
      "kind": "sub",
      "order": 6,
      "html": "https://changegamer.ai/articles/mcp-server-observability-opentelemetry",
      "markdown": "https://changegamer.ai/articles/mcp-server-observability-opentelemetry.md",
      "json": "https://changegamer.ai/api/articles/mcp-server-observability-opentelemetry.json"
    },
    "next": {
      "slug": "mcp-server-cost-optimization",
      "title": "MCP Server Cost Optimization: Toolset Size, Caching Hints, and Fan-Out",
      "description": "How the token cost of an MCP server's tool list, the 2026-07-28 spec's ttlMs/cacheScope caching hints, fan-out from callers you do not control, and per-tool-name cost visibility each shape what a production MCP server actually costs to run.",
      "kind": "sub",
      "order": 8,
      "html": "https://changegamer.ai/articles/mcp-server-cost-optimization",
      "markdown": "https://changegamer.ai/articles/mcp-server-cost-optimization.md",
      "json": "https://changegamer.ai/api/articles/mcp-server-cost-optimization.json"
    }
  },
  "resources": [
    {
      "slug": "mcp-server-discovery",
      "html": "https://changegamer.ai/resources/mcp-server-discovery",
      "markdown": "https://changegamer.ai/resources/mcp-server-discovery.md",
      "json": "https://changegamer.ai/api/resources/mcp-server-discovery.json"
    },
    {
      "slug": "building-mcp-servers",
      "html": "https://changegamer.ai/resources/building-mcp-servers",
      "markdown": "https://changegamer.ai/resources/building-mcp-servers.md",
      "json": "https://changegamer.ai/api/resources/building-mcp-servers.json"
    }
  ]
}