--- title: "4. Versioning" description: "MCP Description specification v0.9.0-rc.3 — 4. Versioning." source: "https://mcpdesc.org/docs/specification/0.9.0-rc.3/versioning/" --- ### 4.1 The `mcpdesc` Field [](/docs/rules/0.9.0-rc.3/mcpdesc/document-schema#required-by "This requirement is part of rule: mcpdesc.document.schema") Every MCP Description document MUST include a `mcpdesc` property at the root level. This property declares which version of this specification the document conforms to. ```json { "mcpdesc": "0.9.0" } ``` ### 4.2 Version Format [](/docs/rules/0.9.0-rc.3/mcpdesc/document-schema#required-by "This requirement is part of rule: mcpdesc.document.schema") The `mcpdesc` value MUST identify the specification version against which conformance is assessed. This community working draft uses `"0.9.0"` and is not a stable release. The specification uses [Semantic Versioning](https://semver.org/) for its own version numbers. Before 1.0.0, a minor release MAY contain breaking changes; after 1.0.0, ordinary Semantic Versioning compatibility rules apply. * **Major** version changes indicate breaking changes to the document structure * **Minor** version changes add features and, before 1.0.0, MAY include breaking changes * **Patch** version changes address errata or clarifications without structural changes ### 4.3 Identifier Roles The root `$schema` property, when present, identifies the JSON Schema resource against which the document’s normalized JSON-compatible data model can be structurally validated. It does not replace the instance format discriminator. ```yaml $schema: https://mcpdesc.org/schema/mcp-description/0.9.0.json mcpdesc: 0.9.0 ``` The root `$schema` property remains optional. When present, it SHOULD identify the exact stable version or public draft snapshot used to produce or validate the document. Omitting `$schema` does not make an otherwise conforming document invalid; a validator MAY select an applicable bundled schema through its API, surrounding metadata, or explicit user configuration. The schema document’s root `$id` identifies that schema resource and establishes its base URI for JSON Schema reference resolution. The `$schema` value does not change the MCP Description conformance version: community working draft documents remain `mcpdesc: 0.9.0`. ```yaml $schema: https://mcpdesc.org/schema/mcp-description/0.9.0-rc.3.json mcpdesc: 0.9.0 ``` The schema document’s own `$schema` property identifies the JSON Schema dialect used to interpret the schema. MCP Description 0.9.0 schemas use `https://json-schema.org/draft/2020-12/schema`. ### 4.4 Canonical Schema URI Families The project controls canonical schema URIs under: ```text https://mcpdesc.org/schema//.json ``` This specification assigns `mcp-description` as the MCP Description format family. A stable release uses its semantic version, for example `https://mcpdesc.org/schema/mcp-description/0.8.0.json`. A public prerelease uses the target version followed by its prerelease identifier, for example `https://mcpdesc.org/schema/mcp-description/0.9.0-rc.3.json`. Assigning a new format family requires an accepted specification decision. Similar repository paths, redirects, or aliases do not create canonical format authority. ### 4.5 Unique and Immutable Schema Resources Every canonical schema URI MUST identify exactly one immutable sequence of schema bytes. A schema published at a canonical URI MUST declare that exact URI as its root `$id`. Once publicly published, a canonical schema resource MUST NOT be replaced with different bytes, even to correct an error or non-normative description. Every byte change requires a new stable version, draft snapshot, or separately versioned errata resource according to the governing format’s compatibility policy. Every public prerelease of this version MUST use a prerelease-specific root `$id`. The stable 0.9.0 schema MUST use `https://mcpdesc.org/schema/mcp-description/0.9.0.json` and MUST NOT reuse a prerelease URI. ### 4.6 Live Publication and Aliases A canonical mcpdesc.org schema URI MUST use HTTPS, return HTTP 200 for `GET`, serve the exact immutable schema bytes directly without redirect, and return a syntactically valid JSON Schema document rather than an HTML fallback. The response MUST declare the request URI as the root `$id` and MUST be retrievable cross-origin for browser-hosted editors and tools. Canonical responses MUST return a JSON-compatible media type and SHOULD use `application/schema+json`. They MUST return `Cache-Control` including `public`, `max-age=31536000`, and `immutable`, and SHOULD include a strong `ETag`. The project MAY also publish mutable convenience aliases such as `https://mcpdesc.org/schema/mcp-description/latest.json` for the latest stable release and `https://mcpdesc.org/schema/mcp-description/draft.json` for the active community draft. An alias SHOULD redirect to its selected immutable canonical resource. An alias MUST NOT be declared as a schema `$id`, and normative examples SHOULD use immutable canonical URIs instead. The repository file `schemas/latest.json` and, when an active draft exists, `schemas/draft.json` are version-status manifests rather than MCP Description JSON Schemas. They identify released or active-draft status for repository workflows and MUST NOT be treated as public schema identities. ### 4.7 Retrieval and Security Boundary MCP Description conformance MUST NOT require network retrieval. A validator MAY bundle known schema resources and resolve their canonical URIs locally. Consumers MUST NOT automatically retrieve an arbitrary `$schema` URI from an untrusted document without an explicit network policy. Implementations that permit retrieval SHOULD restrict schemes and destinations, bound redirects and response sizes, validate media type and schema structure, and mitigate SSRF and cache-poisoning risks. The `$schema` property assists structural schema selection and editor integration. It does not make a structurally valid document semantically conforming and does not supersede protocol-version or cross-object validation. ### 4.8 Version Compatibility Implementations MAY support multiple MCP Description versions. An implementation claiming support for a version MUST process its `mcpdesc` discriminator according to that version’s requirements. [](/docs/rules/0.9.0-rc.3/mcpdesc/document-schema#required-by "This requirement is part of rule: mcpdesc.document.schema") When processing a document, implementations MUST check the `mcpdesc` value and: * Accept documents with a recognized `mcpdesc` version * Reject documents with an unrecognized `mcpdesc` version or provide a clear warning ### 4.9 MCP Protocol Coverage The root `protocolVersions` array identifies the MCP protocol versions described by the document. [](/docs/rules/0.9.0-rc.3/mcpdesc/protocol-versions-values#required-by "This requirement is part of rule: mcpdesc.protocol-versions.values") It MUST be non-empty, MUST contain unique values, and every value MUST be one of: * `2024-11-05` * `2025-03-26` * `2025-06-18` * `2025-11-25` * `2026-07-28` An unknown or later MCP protocol version is invalid under mcpdesc 0.9.0 because this specification cannot validate its semantics. Supporting a later protocol version requires a later mcpdesc specification version. Root coverage states which protocol versions the document describes. It does not prove that the server supports no other protocol versions. ### 4.10 Protocol Scopes and Inheritance Transports, Capabilities Objects, Tools, Resources, Resource Templates, and Prompts MAY declare `protocolVersions`. The root Info Object is unscoped, document-wide MCP Description metadata. [](/docs/rules/0.9.0-rc.3/mcpdesc/info-members#required-by "This requirement is part of rule: mcpdesc.info.members") Its properties are valid independently of root `protocolVersions` and MUST NOT be treated as protocol-scoped declarations. For root version set `R`, a top-level declaration’s effective scope is its explicit `protocolVersions` when present and `R` otherwise. [](/docs/rules/0.9.0-rc.3/mcpdesc/protocol-scope-consistency#required-by "This requirement is part of rule: mcpdesc.protocol-scope.consistency") An explicit scope MUST be a non-empty subset of `R`. For a nested scoped declaration, the effective scope is its explicit `protocolVersions` when present and its parent’s effective scope otherwise. [](/docs/rules/0.9.0-rc.3/mcpdesc/protocol-scope-consistency#required-by "This requirement is part of rule: mcpdesc.protocol-scope.consistency") An explicit child scope MUST be a non-empty subset of its parent’s effective scope. Omission therefore means the complete effective parent scope; it does not mean unknown applicability. [](/docs/rules/0.9.0-rc.3/mcp/capabilities-tasks-protocol-version#required-by "This requirement is part of rule: mcp.capabilities.tasks.protocol-version"), [](/docs/rules/0.9.0-rc.3/mcp/declaration-field-protocol-version#required-by "This requirement is part of rule: mcp.declaration.field.protocol-version"), [](/docs/rules/0.9.0-rc.3/mcp/tool-output-schema-protocol-version#required-by "This requirement is part of rule: mcp.tool.output-schema.protocol-version") As a consequence, a field that this specification marks as available since an MCP protocol version, or for one MCP protocol version only, MUST NOT appear in a declaration whose effective scope includes a protocol version outside that range. ### 4.11 Relationship Between Version Fields The `mcpdesc` version identifies this description format. Root and declaration-level `protocolVersions` identify MCP protocol applicability. The optional root `$schema` identifies a structural validation schema resource. These version dimensions are independent. ### 4.12 Effective Protocol Views and Projection For protocol version `V`, the Effective Protocol View `P_V(D)` of document `D` contains each scoped declaration whose effective scope includes `V` and excludes every other scoped declaration. It preserves the complete Info Object unchanged. [](/docs/rules/0.9.0-rc.3/mcpdesc/view-projection#required-by "This requirement is part of rule: mcpdesc.view.projection") A conforming single-version projection tool MUST: 1. validate the source document; 2. require `V` to occur in root `protocolVersions`; 3. set root `protocolVersions` to `[V]`; 4. retain applicable transports, capabilities, primitives, and nested declarations; 5. remove `protocolVersions` from retained declarations because applicability is unambiguous; 6. preserve semantically significant empty values and inheritance, including security declarations; 7. omit every ordinary declaration collection from which projection removes the last entry; and 8. validate the projected document structurally and semantically for `V`. Projection produces an ordinary conforming MCP Description document, not a second format. [](/docs/rules/0.9.0-rc.3/mcpdesc/view-projection#required-by "This requirement is part of rule: mcpdesc.view.projection") It MUST NOT materialize transport-dependent inherited values onto a primitive unless the operation also selects a transport and defines that resolution. ### 4.13 Merge A merge tool MAY construct an aggregate from single-version or multi-version descriptions. [](/docs/rules/0.9.0-rc.3/mcpdesc/view-merge#required-by "This requirement is part of rule: mcpdesc.view.merge") It MUST validate every input and MUST report a conflict rather than guess when inputs cannot be represented faithfully. [](/docs/rules/0.9.0-rc.3/mcpdesc/view-merge#required-by "This requirement is part of rule: mcpdesc.view.merge") A conforming merge algorithm SHOULD project inputs into individual protocol views, require compatible logical server identity and unscoped metadata, union root protocol sets, collapse equivalent declarations by unioning their scopes, retain differing declarations as disjoint scoped variants, and validate the aggregate result. [](/docs/rules/0.9.0-rc.3/mcpdesc/view-merge#required-by "This requirement is part of rule: mcpdesc.view.merge") When inputs cover the same protocol version, their Effective Protocol Views MUST be semantically equivalent or merge MUST fail. Conflicting `info`, `instructions`, root extension values, security declarations, or other unscoped values also cause failure. For every merged source view `D_V`, this round-trip invariant applies: ```text P_V(merge(D_1, ..., D_n)) is semantically equivalent to D_V ``` Semantic equivalence need not preserve property order, redundant scopes, array order where semantically insignificant, or the original choice between an omitted scope and an explicit full-parent scope. [](/docs/rules/0.9.0-rc.3/mcpdesc/view-merge#required-by "This requirement is part of rule: mcpdesc.view.merge") Merge tools MUST preserve the distinction among omitted `security`, `security: []`, and `security: [{}]`. Omission contributes no entries to an ordinary declaration collection during merge. [](/docs/rules/0.9.0-rc.3/mcpdesc/view-merge#required-by "This requirement is part of rule: mcpdesc.view.merge") A merge result MUST omit an ordinary declaration collection when it has no entries. Merge output MUST satisfy transport protocol coverage whenever it contains `transports`. ### 4.14 Native MCP Projection Native projection produces the MCP values that a server returns from `tools/list`, `resources/list`, `resources/templates/list`, and `prompts/list` for one MCP protocol version. Unlike the Effective Protocol View (Section 4.12), its result is not an MCP Description document. Native projection `N_V(D, k, i)` takes a document `D`, an MCP protocol version `V`, a primitive kind `k` (Tool, Resource, Resource Template, or Prompt), and an identifier `i`: the Tool `name`, Resource `uri`, Resource Template `uriTemplate`, or Prompt `name`, which is unique within `P_V(D)` (Sections 9.5, 10.5, and 11.5). [](/docs/rules/0.9.0-rc.3/mcpdesc/projection-native-schema#required-by "This requirement is part of rule: mcpdesc.projection.native-schema") A conforming native projection implementation MUST: 1. [](/docs/rules/0.9.0-rc.3/mcpdesc/projection-source-valid#required-by "This requirement is part of rule: mcpdesc.projection.source-valid") validate `D` and fail with `projection-source-invalid` when validation reports an error; 2. [](/docs/rules/0.9.0-rc.3/mcpdesc/projection-source-valid#required-by "This requirement is part of rule: mcpdesc.projection.source-valid") require `V` to occur in root `protocolVersions`, otherwise fail with `projection-protocol-version-not-declared`; 3. [](/docs/rules/0.9.0-rc.3/mcpdesc/projection-declaration-applicable#required-by "This requirement is part of rule: mcpdesc.projection.declaration-applicable") select the declaration of kind `k` with identifier `i` in `P_V(D)`, otherwise fail with `projection-declaration-not-applicable`; 4. [](/docs/rules/0.9.0-rc.3/mcpdesc/projection-native-schema#required-by "This requirement is part of rule: mcpdesc.projection.native-schema") resolve every Reference Object in Tool `inputSchema` and `outputSchema` (Section 17); 5. [](/docs/rules/0.9.0-rc.3/mcpdesc/projection-native-schema#required-by "This requirement is part of rule: mcpdesc.projection.native-schema") build the value from the declaration fields that the MCP type of `k` defines in `V`, copying each value unchanged, where Prompt `arguments` entries and `icons` entries keep only the fields that MCP `PromptArgument` and `Icon` define in `V`; and 6. [](/docs/rules/0.9.0-rc.3/mcpdesc/projection-native-schema#required-by "This requirement is part of rule: mcpdesc.projection.native-schema") validate the value against the definition of that MCP type in the pinned MCP `schema.json` of `V`, and fail with `projection-postcondition-failed`, without returning the value, when it does not validate. Because validation already rejects fields that `V` does not define, step 5 removes only MCP Description metadata: `protocolVersions`, `examples`, `interactionExamples`, `completionExamples`, `tags`, `elicitations`, `deprecated`, `security`, `clientRequirements`, and the `x-*` specification extensions of the declaration, its Prompt arguments, and its icons. Embedded JSON Schema keywords in `inputSchema` and `outputSchema`, including `x-*` keywords and `x-mcp-header`, and `_meta` entries are copied unchanged. [](/docs/rules/0.9.0-rc.3/mcpdesc/projection-native-schema#required-by "This requirement is part of rule: mcpdesc.projection.native-schema") Native projection MUST NOT add a field that the declaration does not contain, materialize a protocol default, copy a value into another field, or rewrite a value. An absent annotation hint stays absent, `execution.taskSupport` is not set to `"forbidden"`, no `$schema` is inserted into an embedded schema, and a Prompt argument without `required` stays without it. `deprecated` has no MCP counterpart and is omitted rather than moved into `_meta` or `description`. [](/docs/rules/0.9.0-rc.3/mcpdesc/projection-native-schema#required-by "This requirement is part of rule: mcpdesc.projection.native-schema") The list projection of kind `k` for `V` is the sequence of `N_V(D, k, i)` for every declaration of kind `k` in `P_V(D)`, in document order. A failure for any declaration fails the whole list. [](/docs/rules/0.9.0-rc.3/mcpdesc/projection-native-schema#required-by "This requirement is part of rule: mcpdesc.projection.native-schema") A `projection-postcondition-failed` failure indicates a defect in this specification, its validator, or the implementation, except for a Tool and protocol version for which validation reports the warning of [Section 9.2](/docs/specification/0.9.0-rc.3/tools#req-tool-schema-native-shape): there it reflects a restriction of the MCP `Tool` type that this specification reports but does not enforce. In both cases implementations MUST NOT repair the value. The `projection-fixtures/` folder of this specification gives, for each kind and supported protocol version, the exact expected MCP value or failure, in the case format of `projection-fixtures/schema/projection-case.schema.json`. Values are compared as canonical JSON.