Skip to content
{mcpdesc}

Validation Rules

Validation rules explain the checks used to determine whether an MCP Description document is valid and identify issues that need attention.

What validation rules cover

Section titled “What validation rules cover”

A document is checked in three areas:

  • MCP: the described tools, resources, prompts, capabilities, or carried MCP values meet the requirements of the applicable protocol version.
  • JSON Schema: an embedded Tool input or output schema is valid under its applicable JSON Schema dialect.
  • MCP Description: complementary description fields, protocol scoping, references, and examples meet MCP Description’s requirements.

The catalog groups rules by these three owners, recorded as mcp, json-schema, and mcpdesc.

A single Tool declaration may involve rules from all three groups:

  • Its MCP fields and annotations follow MCP rules.
  • Its inputSchema and outputSchema must be valid JSON Schemas.
  • Its scopes and examples follow MCP Description rules; its example results also follow MCP’s result types for every applicable protocol version.

Why explicit validation rules?

Section titled “Why explicit validation rules?”

MCP Description provides static descriptions of MCP servers across the MCP protocol versions a specification version supports. MCP Description 0.9.0 supports MCP protocol versions 2024-11-05 through 2026-07-28.

The same field can be required in one protocol version, undefined in another, and governed by a JSON Schema dialect rather than by MCP.

A validation failure without that context does not tell an author what to fix.

For structural checks, semantic checks, and protocol scopes, read How validation works. This overview explains how to use the catalog to understand and act on the resulting diagnostics.

How to use the catalog

Section titled “How to use the catalog”

Each rule records which specification owns the requirement, which protocol versions it applies to, and where the requirement comes from.

The catalog helps users and tools identify whether a problem concerns MCP structures, embedded JSON Schema, or MCP Description semantics.

Each rule has an owner-namespaced identifier, such as mcp.tool.output-schema.object-root. Utility tools use it to identify the rule and trace provenance in a diagnostic. In pre-final 0.9.0 snapshots, identifiers are normalized to protocol-version terminology; Draft 4 retains its published IDs, while RC1 uses the migrated IDs listed in issue #109.

Each record also has a short title, a precise requirement summary, and a reader-oriented description. Titles help you scan the catalog; descriptions explain what a check means and how to address it. They do not replace the specification requirements.

A validator reports each issue with a severity, a location, and the rule it breaks. It may also report its own diagnostic codes and messages; those belong to the validator, can differ between tools, and are not part of the catalog. A validator can also report a result for every rule, so you can tell a check that ran and passed from one that never ran; see Rule results.

Each rule cites fixtures: complete example documents in the specification, with a pointer to the relevant fragment and its outcome. The outcome is passes when the rule ran there and reported nothing, error or warning for what the rule reports, or not-applicable when the rule does not run there for the protocol versions the fragment applies to. The specification’s tests check every outcome, so the fixtures show how a rule behaves.

To act on a diagnostic:

  1. Find the diagnostic’s rule identifier in the catalog.
  2. Check the diagnostic’s severity and the rule’s protocol-version applicability.
  3. Read the requirement, its source references, and the rule’s fixtures, comparing a fragment that passes with one that fails.
  4. Correct the document and validate it again.

Errors make a document invalid; warnings do not:

  • Error: a Tool has an array-rooted outputSchema but applies to MCP 2025-11-25, which requires an object root. See the worked example below.
  • Warning: an example result contains resultType: "complete" for MCP 2025-11-25. The open result type permits the field without defining its meaning. The document remains valid, and the field is preserved. The guide explains the contrast with MCP 2026-07-28, where the field is required. See rule mcp.result.additional-properties.preserve in rules/result.yaml.

Worked example

Section titled “Worked example”

The guide’s complete server description declares two lookup variants with different output schemas. To isolate one error, consider a document with the same root protocol versions, ["2025-11-25", "2026-07-28"], but only this Tool:

{
  "name": "lookup",
  "inputSchema": { "type": "object" },
  "outputSchema": { "type": "array", "items": { "type": "string" } }
}

This is a Tool fragment, not a complete document. Without its own protocolVersions, it inherits both root versions. The candidate validator reports this error (its own diagnostic code is omitted here):

{
  "severity": "error",
  "message": "tools[0].outputSchema must have type \"object\" when it applies to MCP 2025-11-25",
  "path": ["tools", 0, "outputSchema", "type"],
  "rule": "mcp.tool.output-schema.object-root",
  "protocolVersions": ["2025-11-25"]
}
  1. Find mcp.tool.output-schema.object-root in rules/tool.yaml. Its title is “Use object output schemas before MCP 2026”; its description explains the version boundary.
  2. The severity is error, so the document is invalid. The rule applies to MCP 2025-06-18 and 2025-11-25, but not 2026-07-28. This Tool inherits 2025-11-25, so the check applies.
  3. Read the requirement in Section 9.2 and the rule’s pinned MCP sources. The rule cites two fixtures: an invalid fixture whose /tools/0/outputSchema has outcome error for MCP 2025-11-25, and a valid fixture whose /tools/3/outputSchema has outcome not-applicable because that Tool is scoped to MCP 2026-07-28 only. The rule results of the invalid fixture show failed for 2025-11-25.
  4. Correct the description to match the server. If only MCP 2026-07-28 returns an array, scope that variant to ["2026-07-28"] and retain the object-output variant for 2025-11-25, as in the guide. If both versions return an object, describe that actual object shape instead. Do not change declared protocol support merely to silence an error. Validate again; the guide’s complete two-variant document produces no diagnostics.

Status and scope

Section titled “Status and scope”

The normative requirements are those of the specification sections. The rule catalog is a pilot registry implementing review-stage Proposal 0024, extended by review-stage Proposal 0030, Proposal 0033, and Proposal 0031. None of these proposals is accepted. The pilot registry documents and tests the requirements; its reader fields are informative and it is not a separate document-conformance specification.

Catalogs belong to exact MCP Description snapshots, not validator package versions. Once deployed, the catalog discovery index lists the published manifests, with separate stable and draft pointers. The Draft 3 and Draft 4 catalogs and rule formats 1.1.0 and 1.2.0, and validation result format 1.0.0, are published. Rule format 1.3.0 and validation result format 1.3.0 are RC1 publication targets until deployment is verified; this working tree does not imply they are live. See catalog publication and discovery.

Every diagnostic of this repository’s candidate validator identifies a registered rule. Published prereleases implement the registry and native MCP projection for Community Working Drafts 1 and 2 (0.9.0-draft.1 and 0.9.0-draft.2), when a selector is passed explicitly:

  • @mcpdesc/[email protected] reports the rule of each diagnostic.
  • @mcpdesc/[email protected] implements native MCP projection, tested against those drafts’ projection fixtures, and 0.8.0 to 0.9.0 conversion. It does not yet check the projection postcondition of Section 4.14, which Draft 3’s postcondition cases expect.

Both are prereleases, not stable releases. Install them by exact version: the npm next dist-tag moves to later prereleases. Support for Drafts 3 and 4 follows in later releases.

Browse by owner

Section titled “Browse by owner”
  • MCP — 46 rules.
  • JSON Schema — 1 rule.
  • mcpdesc — 38 rules.

Protocol version guidance

Section titled “Protocol version guidance”