Match the MCP Description document schema

The document root has the required mcpdesc, info, and protocolVersions members, only the members of Section 3.2, and non-empty ordinary collections. Failures inside a root member belong to the rule that owns that member’s schema location; this rule reports root-level failures.

Requirement

A document validates against the JSON Schema for its declared mcpdesc version. This rule owns the document root and generic JSON values; every other schema location belongs to a more specific rule.

Details

Rule ID: mcpdesc.document.schema
Owner: mcpdesc
Surface: Document
Kind: structural
Requirement level: Not specified in the rule record
Protocol versions: independent of the MCP protocol version
Document schema locations: #, #/$defs/jsonValue, #/$defs/specificationExtensionValue
Status: internal · Enforcement: internal

Required by

• MCP Description 0.9.0, Section 16.1, item 7
  • 16. Conformance: req-document-schema
  • 3. Document Structure: req-root-fields
  • 3. Document Structure: req-closed-objects
  • 9. Tools: req-tool-input-schema-required
  • 3. Document Structure: req-ordinary-collections-non-empty
  • 3. Document Structure: req-ordinary-collections-omitted
  • 4. Versioning: req-mcpdesc-required
  • 4. Versioning: req-mcpdesc-version
  • 4. Versioning: req-version-check
  • 5. Info Object: req-info-required
  • 6. Transports: req-transports-non-empty
  • 8. Capabilities: req-capabilities-non-empty
  • 13. Tags: req-tags-non-empty
  • 13. Tags: req-tags-omitted
  • 16. Conformance: req-conforming-document
  • 14. Specification Extensions: req-extension-names
  • 14. Specification Extensions: req-extension-unknown-accepted
  • 15. Serialization: req-serialization-empty-collections

Notes

The optional root $schema does not select the schema used for validation: optional-schema-omitted.json omits it and validates against the schema for its mcpdesc version.

Examples

Valid example

Source: expected-valid/optional-schema-omitted.json · Selected: whole document

Show whole fixture

{
  "mcpdesc": "0.9.0",
  "info": {
    "name": "schema-omitted",
    "version": "1.0.0"
  },
  "protocolVersions": [
    "2026-07-28"
  ]
}

Invalid example

Source: expected-invalid/empty-ordinary-root-collections.json · Selected: /capabilities

[]

Invalid example

Source: expected-invalid/empty-tag-catalog-reference.json · Selected: /tags

[]

Rule Source Code

document.yaml at immutable tag v0.9.0-rc.3.