{ "rules": [ { "applicability": { "protocolVersions": { "2024-11-05": "not-applicable", "2025-03-26": "not-applicable", "2025-06-18": "not-applicable", "2025-11-25": "applies", "2026-07-28": "applies" }, "schemaDialects": [ "https://json-schema.org/draft/2020-12/schema", "http://json-schema.org/draft-07/schema#" ] }, "description": "Tool input and output schemas must be valid under their applicable JSON Schema dialect. Unsupported declared dialects are errors; unresolved external references warn when complete offline checking is unavailable. External schemas are not fetched automatically, and a partial check is not reported as complete.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/malformed-tool-schema.json", "pointer": "/tools/0" }, { "outcome": "error", "path": "expected-invalid/unresolved-local-tool-ref.json", "pointer": "/tools/0" }, { "outcome": "error", "path": "expected-invalid/unsupported-tool-schema-dialect.json", "pointer": "/tools/0/inputSchema" }, { "outcome": "warning", "path": "expected-warning/unresolved-external-tool-ref.json", "pointer": "/tools/0" }, { "outcome": "warning", "path": "expected-warning/unresolved-external-tool-example-ref.json", "pointer": "/tools/0" } ], "id": "json-schema.tool-schema.valid", "kind": "embedded-standard", "notes": "The declared dialect set is fixed by the specification, not by the validator: an unsupported dialect is an error, not a warning, because MCP guarantees only 2020-12 support and peers return an error for other dialects, and because Tool examples cannot be checked against a schema in an unknown dialect (maintainer decision on issue #72, 2026-10-26). Unresolved external references differ: offline validation forbids retrieving them, so they only warn. Earlier protocol versions define no embedded dialect; mcp.tool.schema.legacy-shape applies to those protocol versions instead.", "owner": "json-schema", "path": "inputSchema, outputSchema", "requirement": "must", "sources": [ { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-11-25/basic/index.mdx#L140-L186", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/basic/index.mdx#L251-L297" ], "reference": "MCP 2025-11-25 and 2026-07-28 specification, Basic, JSON Schema usage, Schema Dialect (implementations must support 2020-12 and must return an error for unsupported dialects)", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2025-11-25/schema.ts#L1257-L1265", "validation/mcp-schemas/2026-07-28/schema.ts#L1981-L1997", "validation/mcp-schemas/2025-11-25/schema.ts#L1272-L1284", "validation/mcp-schemas/2026-07-28/schema.ts#L1999-L2005" ], "reference": "MCP 2025-11-25 and 2026-07-28 schema.ts, interface Tool, inputSchema and outputSchema doc comments (default JSON Schema 2020-12 when $schema is absent)", "tier": 1 }, { "locations": [ "https://json-schema.org/draft/2020-12/json-schema-core", "https://json-schema.org/draft/2020-12/json-schema-validation", "https://json-schema.org/draft-07/json-schema-core", "https://json-schema.org/draft-07/json-schema-validation" ], "reference": "JSON Schema 2020-12 Core and Validation, and draft-07, for the declared dialect", "tier": 2 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-tool-output-schema-valid", "sections/09-tools.md#req-tool-schema-dialect-valid", "sections/09-tools.md#req-tool-schema-dialect-set", "sections/09-tools.md#req-tool-schema-external-ref" ], "reference": "MCP Description 0.9.0, Section 9.2 (declared dialects limited to 2020-12 and draft-07; never fetch external $ref targets; warn when validation is incomplete)" } ], "status": "internal", "summary": "An embedded Tool inputSchema or outputSchema is valid under its declared or default JSON Schema dialect, and a declared dialect is JSON Schema 2020-12 or draft-07.", "surface": "Tool", "title": "Validate embedded Tool schemas in their dialect" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Resource annotations exist in early MCP protocol versions, but lastModified was added in 2025-06-18. If a declaration covers an earlier version, omit lastModified or describe separate variants with disjoint scopes.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/annotations-last-modified-before-2025-06-18.json", "pointer": "/resources/0/annotations" } ], "id": "mcp.annotations.last-modified.protocol-version", "kind": "structural", "owner": "mcp", "path": "lastModified", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L815-L840", "validation/mcp-schemas/2025-03-26/schema.ts#L921-L944", "validation/mcp-schemas/2025-06-18/schema.ts#L1093-L1128", "validation/mcp-schemas/2025-11-25/schema.ts#L1700-L1735", "validation/mcp-schemas/2026-07-28/schema.ts#L2265-L2300" ], "reference": "MCP 2024-11-05 and 2025-03-26 schema.ts, annotations (audience, priority); MCP 2025-06-18 to 2026-07-28 schema.ts, interface Annotations (adds lastModified)", "tier": 1 } ], "specification": [ { "locations": [ "sections/10-resources.md#req-resource-annotations-last-modified" ], "reference": "MCP Description 0.9.0, Section 10.3" } ], "status": "internal", "summary": "Resource Annotations carry lastModified only from MCP 2025-06-18, on declarations and on content blocks.", "surface": "Annotations", "title": "Use lastModified only where MCP defines it" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Resource annotations describe audience, priority, and modification time, not Tool behavior. Unknown properties are invalid even when their names start with x-. Remove those properties and keep Tool-specific hints on Tool annotations instead.", "documentSchema": [ "#/$defs/resourceAnnotations" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/resource-annotations-unknown-property.json", "pointer": "/resources/0/annotations" }, { "outcome": "error", "path": "expected-invalid/content-annotations-unknown-property.json", "pointer": "/tools/0/examples/basic/result/content/0/annotations" }, { "outcome": "passes", "path": "expected-valid/distinct-tool-and-resource-annotations.json", "pointer": "/resources/0/annotations" } ], "id": "mcp.annotations.members", "kind": "structural", "notes": "lastModified is defined from MCP 2025-06-18; that boundary is checked separately.", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L815-L840", "validation/mcp-schemas/2025-03-26/schema.ts#L921-L944", "validation/mcp-schemas/2025-06-18/schema.ts#L1093-L1128", "validation/mcp-schemas/2025-11-25/schema.ts#L1700-L1735", "validation/mcp-schemas/2026-07-28/schema.ts#L2265-L2300" ], "reference": "MCP 2024-11-05 schema.ts, inline annotations on Resource, ResourceTemplate, and content types; MCP 2025-03-26 to 2026-07-28 schema.ts, interface Annotations (no index signature)", "tier": 1 } ], "specification": [ { "locations": [ "sections/10-resources.md#req-resource-annotations-closed", "sections/10-resources.md#req-content-annotations-distinct", "sections/15-serialization.md#req-serialization-value-formats" ], "reference": "MCP Description 0.9.0, Section 10.3" } ], "status": "internal", "summary": "Resource Annotations on resources, resource templates, and content blocks contain only audience, priority, and lastModified.", "surface": "Annotations", "title": "Resource annotations contain only MCP hints" }, { "applicability": { "protocolVersions": "independent" }, "arbitrations": [ { "authority": "MCP's schema generation configuration (--defaultNumberType integer), under which an unannotated number denotes an integer.", "behavior": "Reject a non-integer or negative ttlMs with schema-validation.", "conflict": "schema.ts declares ttlMs as number, which TypeScript cannot restrict to integers; the generated schema.json types it as integer.", "protocolVersions": [ "2026-07-28" ], "rationale": "A millisecond duration is an integer in MCP's generated schema; accepting fractions would let examples disagree with MCP's types.", "reviewTrigger": "MCP changes its generator configuration or annotates ttlMs with @TJS-type number.", "status": "active" } ], "description": "Resource example ttlMs values are non-negative integer milliseconds. This value constraint also applies when an older protocol version permits the field without defining it. Replace fractions or negative values with the intended duration rather than relying on automatic rounding.", "documentSchema": [ "#/$defs/completedReadResourceResultExample/properties/ttlMs" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/fractional-ttl-ms.json", "pointer": "/resources/0/examples/cached/result/ttlMs" }, { "outcome": "error", "path": "expected-invalid/resource-example-cache-fields.json", "pointer": "/resources/1/examples/invalid/result/ttlMs" }, { "outcome": "passes", "path": "expected-valid/named-resource-examples.json", "pointer": "/resources/1/examples/two-files/result/ttlMs" } ], "id": "mcp.cacheable-result.ttl-ms", "kind": "structural", "notes": "MCP defines ttlMs from 2026-07-28 only. In earlier protocol versions it is a field not defined by the MCP protocol version (mcp.result.additional-properties.preserve), and Section 3.6 keeps the same value constraint so that one example can serve several protocol versions.", "owner": "mcp", "path": "ttlMs", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2026-07-28/schema.ts#L1081-L1094" ], "reference": "MCP 2026-07-28 schema.ts, interface CacheableResult, ttlMs (unannotated number, @minimum 0)", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2026-07-28/schema.json#L2625-L2629" ], "reference": "MCP 2026-07-28 generated schema.json, ReadResourceResult.ttlMs typed integer", "tier": 3 }, { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/scripts/generate-schemas.ts#L95" ], "reference": "MCP scripts/generate-schemas.ts: typescript-json-schema --defaultNumberType integer", "tier": 3 } ], "specification": [ { "locations": [ "sections/03-document-structure.md#req-mcp-integer-numbers", "sections/10-resources.md#req-resource-example-result-shape" ], "reference": "MCP Description 0.9.0, Sections 3.6 and 10.4.4" }, { "locations": [ "proposal-snapshots/0029-integer-mcp-numbers.md" ], "reference": "Proposal 0029, Integer MCP Numbers" } ], "status": "arbitrated", "summary": "ttlMs in a Resource example result is a non-negative integer when present.", "surface": "CacheableResult", "title": "Express cache lifetimes as non-negative integers" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "arbitrations": [ { "authority": "MCP Description decision (Proposal 0021)", "behavior": "Accept and preserve a server extensions map for earlier protocol versions with a warning; check client requirements against each protocol version separately.", "conflict": "ServerCapabilities is closed and has no extensions member before MCP 2026-07-28, so mcp.server-capabilities.members would reject it, but deployed servers advertise extensions with a pre-standard convention.", "protocolVersions": [ "2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25" ], "rationale": "Rejecting it would make descriptions of deployed servers inaccurate. The warning keeps the departure from the type visible.", "reviewTrigger": "Retirement of the pre-standard convention, or a decision to drop support for it.", "status": "active" } ], "description": "MCP Description accepts server extension advertisements before their standardization, with a warning for the affected protocol versions. The values are preserved rather than rewritten. This exception does not make primitive clientRequirements.extensions available in those earlier versions.", "enforcement": "internal", "fixtures": [ { "outcome": "warning", "path": "expected-warning/pre-standard-extension-capabilities.json", "pointer": "/capabilities/0" } ], "id": "mcp.capabilities.extensions.protocol-version", "kind": "structural", "owner": "mcp", "path": "extensions", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L205-L248", "validation/mcp-schemas/2025-03-26/schema.ts#L225-L272", "validation/mcp-schemas/2025-06-18/schema.ts#L253-L302", "validation/mcp-schemas/2025-11-25/schema.ts#L381-L457", "validation/mcp-schemas/2026-07-28/schema.ts#L871-L882" ], "reference": "MCP 2024-11-05 to 2025-11-25 schema.ts, interface ServerCapabilities (no extensions); MCP 2026-07-28 schema.ts, ServerCapabilities extensions", "tier": 1 } ], "specification": [ { "locations": [ "sections/08-capabilities.md#req-capabilities-extensions-pre-standard", "../../proposals/0021-pre-standard-extension-capabilities.md" ], "reference": "MCP Description 0.9.0, Section 8.4; Proposal 0021 (pre-standard extension capabilities)" } ], "status": "arbitrated", "summary": "Server capabilities.extensions is defined from MCP 2026-07-28; for earlier protocol versions a pre-standard extensions map is preserved with a warning.", "surface": "ServerCapabilities", "title": "Recognize pre-standard extension advertisements" }, { "applicability": { "protocolVersions": { "2024-11-05": "not-applicable", "2025-03-26": "not-applicable", "2025-06-18": "not-applicable", "2025-11-25": "not-applicable", "2026-07-28": "applies" } }, "description": "MCP 2026-07-28 uses per-request log-level selection rather than logging/setLevel. MCP Description warns about the logging server capability for that version. Review the advertisement; the warning alone does not make the description invalid.", "enforcement": "internal", "fixtures": [ { "outcome": "warning", "path": "expected-warning/logging-deprecated-2026.json", "pointer": "/capabilities/0" } ], "id": "mcp.capabilities.logging.deprecated", "kind": "semantic", "owner": "mcp", "path": "logging", "requirement": "should", "sources": [ { "locations": [ "validation/mcp-schemas/2026-07-28/schema.ts#L798-L808", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/server/utilities/logging.mdx#L8-L18" ], "reference": "MCP 2026-07-28 schema.ts, ServerCapabilities logging (@deprecated, SEP-2577); specification, Server Features, Utilities, Logging (deprecated)", "tier": 1 } ], "specification": [ { "locations": [ "sections/08-capabilities.md#req-capabilities-logging-deprecated" ], "reference": "MCP Description 0.9.0, Section 8.2" } ], "status": "internal", "summary": "The logging server capability is reported as deprecated in MCP 2026-07-28.", "surface": "ServerCapabilities", "title": "Review the deprecated logging capability" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Task capabilities from MCP 2025-11-25 and extension advertisements in MCP 2026-07-28 are not interchangeable fields. Limit each capability declaration to the versions that define it. The validator does not automatically translate a tasks object into an extension advertisement.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/tasks-capability-2026.json", "pointer": "/capabilities/0" } ], "id": "mcp.capabilities.tasks.protocol-version", "kind": "structural", "owner": "mcp", "path": "tasks", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-11-25/schema.ts#L430-L456", "validation/mcp-schemas/2025-06-18/schema.ts#L253-L302", "validation/mcp-schemas/2026-07-28/schema.ts#L788-L883" ], "reference": "MCP 2025-11-25 schema.ts, ServerCapabilities tasks; MCP 2025-06-18 and 2026-07-28 schema.ts, ServerCapabilities (no tasks)", "tier": 1 } ], "specification": [ { "locations": [ "sections/08-capabilities.md#req-capabilities-tasks-distinct", "sections/04-versioning.md#req-field-protocol-version-availability" ], "reference": "MCP Description 0.9.0, Section 8.3" } ], "status": "internal", "summary": "The core tasks server capability exists only in MCP 2025-11-25; MCP 2026-07-28 uses the tasks extension instead.", "surface": "ServerCapabilities", "title": "Keep task capabilities in their protocol version" }, { "applicability": { "protocolVersions": { "2024-11-05": "not-applicable", "2025-03-26": "not-applicable", "2025-06-18": "not-applicable", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Some client capability forms remain recognized but are deprecated in later MCP protocol versions. The warning does not invalidate the document. Review the requirement against the selected protocol version rather than assuming an older advertisement model still applies.", "enforcement": "internal", "fixtures": [ { "outcome": "warning", "path": "expected-warning/deprecated-client-capability-requirements.json", "pointer": "/prompts/0/clientRequirements" } ], "id": "mcp.client-capabilities.deprecated", "kind": "semantic", "owner": "mcp", "path": "clientRequirements", "requirement": "should", "sources": [ { "locations": [ "validation/mcp-schemas/2025-11-25/schema.ts#L1588-L1595" ], "reference": "MCP 2025-11-25 schema.ts, CreateMessageRequest includeContext (\"thisServer\" and \"allServers\" are soft-deprecated; tied to ClientCapabilities.sampling.context)", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2026-07-28/schema.ts#L732-L732", "validation/mcp-schemas/2026-07-28/schema.ts#L733-L759" ], "reference": "MCP 2026-07-28 schema.ts, ClientCapabilities roots and sampling (@deprecated, SEP-2577)", "tier": 1 } ], "specification": [ { "locations": [ "sections/08-capabilities.md#req-client-requirements-deprecated" ], "reference": "MCP Description 0.9.0, Section 8.5" } ], "status": "internal", "summary": "A client capability requirement that the applicable protocol version deprecates is reported.", "surface": "ClientCapabilities", "title": "Review deprecated client requirements" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "arbitrations": [ { "authority": "MCP schema.ts type, the source of truth for message structures", "behavior": "Reject unknown top-level requirements, as for server capabilities. Custom requirements belong in experimental and, from MCP 2026-07-28, in extensions.", "conflict": "The TypeScript type declares a fixed set of members and no index signature, while its doc comment says the set is not closed and any client can define additional capabilities.", "protocolVersions": [ "2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25", "2026-07-28" ], "rationale": "Same reading as mcp.server-capabilities.members, so one document does not treat the two capability types differently. Closing is the reversible choice.", "reviewTrigger": "Resolution of MCP issue 1898, an upstream clarification of the doc comment, or a later MCP protocol version adding an index signature.", "status": "active", "upstream": "https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1898" } ], "description": "A primitive's clientRequirements lists minimum client capabilities, not custom top-level names. Put custom requirements in experimental or in extensions where defined, after reviewing their meaning. Server capability advertisement and client requirements are different declarations.", "documentSchema": [ "#/$defs/clientCapabilityRequirements", "#/$defs/clientCapabilityValue" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/unknown-client-capability-requirement.json", "pointer": "/tools/0/clientRequirements" }, { "outcome": "passes", "path": "expected-valid/client-capability-requirements.json", "pointer": "/prompts/0/clientRequirements" } ], "id": "mcp.client-capabilities.members", "kind": "structural", "owner": "mcp", "path": "clientRequirements", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L182-L203", "validation/mcp-schemas/2025-03-26/schema.ts#L202-L223", "validation/mcp-schemas/2025-06-18/schema.ts#L224-L251", "validation/mcp-schemas/2025-11-25/schema.ts#L305-L379", "validation/mcp-schemas/2026-07-28/schema.ts#L711-L786" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, interface ClientCapabilities (no index signature)", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L182-L184", "validation/mcp-schemas/2025-03-26/schema.ts#L202-L204", "validation/mcp-schemas/2025-06-18/schema.ts#L224-L228", "validation/mcp-schemas/2025-11-25/schema.ts#L305-L309", "validation/mcp-schemas/2026-07-28/schema.ts#L711-L715" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, ClientCapabilities doc comment (\"this is not a closed set: any client can define its own, additional capabilities\")", "tier": 1 } ], "specification": [ { "locations": [ "sections/08-capabilities.md#req-client-requirements-closed", "sections/08-capabilities.md#req-client-requirements-shape" ], "reference": "MCP Description 0.9.0, Section 8.5" } ], "status": "arbitrated", "summary": "A Client Capability Requirements Object names only client capabilities the applicable MCP protocol version defines; custom requirements go in experimental and, from MCP 2026-07-28, in extensions.", "surface": "ClientCapabilities", "title": "Use recognized client capability requirements" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Client capabilities and their settings change across MCP protocol versions. Check each declared requirement against every version in the primitive's effective scope. Split variants when a requirement cannot be represented consistently across that scope.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/protocol-version-incompatible-client-capability-requirements.json", "pointer": "/tools/0/clientRequirements" }, { "outcome": "error", "path": "expected-invalid/invalid-client-requirement-value.json", "pointer": "/tools/0/clientRequirements/roots" }, { "outcome": "passes", "path": "expected-valid/client-capability-requirements.json", "pointer": "/tools/0/clientRequirements" } ], "id": "mcp.client-capabilities.protocol-shape", "kind": "structural", "owner": "mcp", "path": "clientRequirements", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L182-L203", "validation/mcp-schemas/2025-03-26/schema.ts#L202-L223", "validation/mcp-schemas/2025-06-18/schema.ts#L224-L251", "validation/mcp-schemas/2025-11-25/schema.ts#L305-L379", "validation/mcp-schemas/2026-07-28/schema.ts#L711-L786" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, interface ClientCapabilities (members and nested members per protocol version)", "tier": 1 } ], "specification": [ { "locations": [ "sections/08-capabilities.md#req-client-requirements-protocol-version-valid", "sections/08-capabilities.md#req-client-requirements-values", "sections/08-capabilities.md#req-client-requirements-extensions" ], "reference": "MCP Description 0.9.0, Section 8.5" } ], "status": "internal", "summary": "Each client capability requirement and nested member exists in every applicable protocol version's ClientCapabilities type, with object values and a boolean listChanged.", "surface": "ClientCapabilities", "title": "Match client requirements to the protocol version" }, { "applicability": { "protocolVersions": { "2024-11-05": "not-applicable", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Completion context was added in MCP 2025-06-18. A completion example spanning an earlier supported version cannot carry that context unchanged. Split the declaration's scopes when context is needed for only the newer versions.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/invalid-completion-example-semantics.json", "pointer": "/prompts/1/completionExamples/context-too-early" } ], "id": "mcp.completion.context.protocol-version", "kind": "structural", "notes": "MCP Description does not support completion examples for MCP 2024-11-05 (mcp.completion.protocol-version).", "owner": "mcp", "path": "context", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-03-26/schema.ts#L1092-L1113", "validation/mcp-schemas/2025-06-18/schema.ts#L1307-L1340", "validation/mcp-schemas/2025-11-25/schema.ts#L1995-L2025", "validation/mcp-schemas/2026-07-28/schema.ts#L2582-L2618" ], "reference": "MCP 2025-03-26 schema.ts, interface CompleteRequest (no context); MCP 2025-06-18 to 2026-07-28 schema.ts, CompleteRequest params context", "tier": 1 } ], "specification": [ { "locations": [ "sections/10-resources.md#req-template-completion-context-protocol-version", "sections/11-prompts.md#req-prompt-completion-context-protocol-version" ], "reference": "MCP Description 0.9.0, Sections 10.4.6 and 11.4" } ], "status": "internal", "summary": "A completion example carries context only from MCP 2025-06-18, where CompleteRequest defines it.", "surface": "CompleteRequest", "title": "Use completion context only where supported" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "MCP Description does not support completion examples for MCP 2024-11-05, despite the underlying protocol defining completion. The registry records that deliberate historical limitation. Scope completion examples to supported versions instead of treating this as a missing capability advertisement.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/invalid-completion-example-semantics.json", "pointer": "/prompts/0/completionExamples" }, { "outcome": "passes", "path": "expected-warning/legacy-completion-examples.json", "pointer": "/resourceTemplates/0/completionExamples/issue-prefix" } ], "gaps": [ { "behavior": "Completion examples are rejected with completion-example-version-mismatch, although MCP 2024-11-05 defines completion/complete. MCP Description does not support completion examples for this protocol version: it is old and the use case is narrow.", "protocolVersions": [ "2024-11-05" ], "reference": "Maintainer decision on issue #72, 2026-10-25", "resolution": "not-fixed" } ], "id": "mcp.completion.protocol-version", "kind": "structural", "owner": "mcp", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L951-L972", "validation/mcp-schemas/2024-11-05/schema.ts#L974-L992", "validation/mcp-schemas/2025-03-26/schema.ts#L237-L240" ], "reference": "MCP 2024-11-05 schema.ts, interfaces CompleteRequest (method completion/complete) and CompleteResult; the ServerCapabilities.completions capability is added in MCP 2025-03-26", "tier": 1 } ], "specification": [ { "locations": [ "sections/10-resources.md#req-template-completion-protocol-versions", "sections/11-prompts.md#req-prompt-completion-protocol-versions" ], "reference": "MCP Description 0.9.0, Sections 10.4.6 and 11.4 (no completion examples for MCP 2024-11-05)" } ], "status": "internal", "summary": "Completion examples are available in every protocol version that defines completion/complete and CompleteResult.", "surface": "CompleteResult", "title": "Check completion example protocol support" }, { "applicability": { "protocolVersions": "independent" }, "description": "The nested completion object is closed even when its surrounding result is open. It accepts values, total, and hasMore, not arbitrary pagination or vendor fields. Remove additional members or explicitly review a different metadata destination.", "documentSchema": [ "#/$defs/completionResult" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/completion-result-extra-field.json", "pointer": "/resourceTemplates/0/completionExamples/issue-prefix/result/completion" }, { "outcome": "passes", "path": "expected-valid/named-completion-examples.json", "pointer": "/resourceTemplates/0/completionExamples" } ], "id": "mcp.completion.result-closed", "kind": "structural", "owner": "mcp", "path": "completion", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L974-L992", "validation/mcp-schemas/2025-03-26/schema.ts#L1115-L1133", "validation/mcp-schemas/2025-06-18/schema.ts#L1342-L1362", "validation/mcp-schemas/2025-11-25/schema.ts#L2037-L2057", "validation/mcp-schemas/2026-07-28/schema.ts#L2633-L2661" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, interface CompleteResult, completion (no index signature)", "tier": 1 } ], "specification": [ { "locations": [ "sections/03-document-structure.md#req-carried-nested-closed", "sections/03-document-structure.md#req-carried-closed-reject" ], "reference": "MCP Description 0.9.0, Sections 10.4.6 and 11.4" } ], "status": "internal", "summary": "The completion object of a completion result contains only values, total, and hasMore.", "surface": "CompleteResult", "title": "Keep completion result members within MCP fields" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Tool and Prompt examples carry native MCP content, whose types and fields vary by protocol version. Check each block against the containing declaration's full effective scope. A block valid in a newer version is not automatically valid in an older one.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/protocol-version-incompatible-tool-example.json", "pointer": "/tools/0/examples/future-result/result/content/0" }, { "outcome": "error", "path": "expected-invalid/invalid-prompt-example-semantics.json", "pointer": "/prompts/4/examples/resource-link-too-new/result/messages/0/content" } ], "id": "mcp.content-block.protocol-version", "kind": "structural", "notes": "The same diagnostic codes also report embedded resource _meta (mcp.resource-contents.meta.protocol-version) and annotations.lastModified (mcp.annotations.last-modified.protocol-version); the rule property identifies which.", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L842-L851", "validation/mcp-schemas/2024-11-05/schema.ts#L853-L868", "validation/mcp-schemas/2024-11-05/schema.ts#L610-L619" ], "reference": "MCP 2024-11-05 schema.ts, TextContent, ImageContent, and EmbeddedResource (no AudioContent, no ResourceLink, no content _meta)", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2025-03-26/schema.ts#L987-L1009" ], "reference": "MCP 2025-03-26 schema.ts, AudioContent", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2025-06-18/schema.ts#L753-L762", "validation/mcp-schemas/2025-06-18/schema.ts#L1130-L1134" ], "reference": "MCP 2025-06-18 schema.ts, ResourceLink and ContentBlock, _meta on content types", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2025-11-25/schema.ts#L797-L838" ], "reference": "MCP 2025-11-25 schema.ts, Resource extends Icons (inherited by ResourceLink)", "tier": 1 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-tool-example-content-protocol-version", "sections/11-prompts.md#req-prompt-example-content-protocol-version" ], "reference": "MCP Description 0.9.0, Sections 9.3 and 11.3" } ], "status": "internal", "summary": "Content blocks in example results use only content types and fields the applicable protocol version defines: audio from MCP 2025-03-26, resource links and block _meta from 2025-06-18, and resource-link icons from 2025-11-25.", "surface": "ContentBlock", "title": "Use content blocks supported by each protocol version" }, { "applicability": { "protocolVersions": "independent" }, "description": "Content in example results is an MCP content block selected by type: text, image, audio, resource link, or embedded resource. Resource contents have a uri and either text or blob. Each carries only the fields its MCP type defines.", "documentSchema": [ "#/$defs/toolResultContent", "#/$defs/resourceContents" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/discriminated-union-members.json", "pointer": "/tools/0/interactionExamples/invalid/result/content/0" } ], "id": "mcp.content.members", "kind": "structural", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-11-25/schema.ts#L1740-L1741", "validation/mcp-schemas/2025-11-25/schema.ts#L881-L897", "validation/mcp-schemas/2026-07-28/schema.ts#L2305-L2306", "validation/mcp-schemas/2026-07-28/schema.ts#L1514-L1527" ], "reference": "MCP 2025-11-25 and 2026-07-28 schema.ts, ContentBlock and ResourceContents", "tier": 1 } ], "specification": [ { "locations": [ "sections/03-document-structure.md#req-carried-defined-fields", "sections/03-document-structure.md#req-carried-closed-reject", "sections/10-resources.md#req-resource-annotations-not-in-examples", "sections/10-resources.md#req-resource-contents-fields" ], "reference": "MCP Description 0.9.0, Section 3.6" } ], "status": "internal", "summary": "Content blocks and resource contents match exactly one MCP content type, with its required fields and no unknown fields.", "surface": "ContentBlock, ResourceContents", "title": "Use MCP content blocks and resource contents" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "A declaration must be valid in every protocol version in its effective scope. A field introduced later cannot be shared with earlier versions merely because the document also declares the later version. Omit the field or describe disjoint scoped variants.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/protocol-version-inapplicable-execution.json", "pointer": "/tools/0" }, { "outcome": "error", "path": "expected-invalid/protocol-version-inapplicable-tool-schema-dialect.json", "pointer": "/tools/0/inputSchema" } ], "id": "mcp.declaration.field.protocol-version", "kind": "structural", "notes": "outputSchema, the outputSchema root, and the tasks capability have their own rules; the rule property identifies which applies.", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L684-L704", "validation/mcp-schemas/2025-03-26/schema.ts#L781-L810", "validation/mcp-schemas/2025-06-18/schema.ts#L925-L968", "validation/mcp-schemas/2025-11-25/schema.ts#L1244-L1297", "validation/mcp-schemas/2026-07-28/schema.ts#L1956-L2015", "validation/mcp-schemas/2025-06-18/schema.ts#L304-L324", "validation/mcp-schemas/2025-11-25/schema.ts#L523-L543", "validation/mcp-schemas/2026-07-28/schema.ts#L949-L969", "validation/mcp-schemas/2025-11-25/schema.ts#L503-L521", "validation/mcp-schemas/2026-07-28/schema.ts#L929-L947", "validation/mcp-schemas/2024-11-05/schema.ts#L414-L450", "validation/mcp-schemas/2025-03-26/schema.ts#L442-L483", "validation/mcp-schemas/2025-06-18/schema.ts#L521-L562", "validation/mcp-schemas/2025-11-25/schema.ts#L797-L838", "validation/mcp-schemas/2026-07-28/schema.ts#L1433-L1474", "validation/mcp-schemas/2024-11-05/schema.ts#L452-L481", "validation/mcp-schemas/2025-03-26/schema.ts#L485-L519", "validation/mcp-schemas/2025-06-18/schema.ts#L564-L598", "validation/mcp-schemas/2025-11-25/schema.ts#L840-L874", "validation/mcp-schemas/2026-07-28/schema.ts#L1476-L1507", "validation/mcp-schemas/2024-11-05/schema.ts#L558-L574", "validation/mcp-schemas/2025-03-26/schema.ts#L596-L612", "validation/mcp-schemas/2025-06-18/schema.ts#L696-L715", "validation/mcp-schemas/2025-11-25/schema.ts#L979-L999", "validation/mcp-schemas/2026-07-28/schema.ts#L1654-L1671", "validation/mcp-schemas/2024-11-05/schema.ts#L576-L592", "validation/mcp-schemas/2025-03-26/schema.ts#L614-L630", "validation/mcp-schemas/2025-06-18/schema.ts#L717-L731", "validation/mcp-schemas/2025-11-25/schema.ts#L1001-L1015", "validation/mcp-schemas/2026-07-28/schema.ts#L1673-L1687", "validation/mcp-schemas/2024-11-05/schema.ts#L205-L248", "validation/mcp-schemas/2025-03-26/schema.ts#L225-L272", "validation/mcp-schemas/2025-06-18/schema.ts#L253-L302", "validation/mcp-schemas/2025-11-25/schema.ts#L381-L457", "validation/mcp-schemas/2026-07-28/schema.ts#L788-L883" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, interfaces BaseMetadata, Icons, Tool, Resource, ResourceTemplate, Prompt, PromptArgument, and ServerCapabilities", "tier": 1 } ], "specification": [ { "locations": [ "sections/04-versioning.md#req-field-protocol-version-availability", "sections/09-tools.md#req-tool-schema-dialect-keyword" ], "reference": "MCP Description 0.9.0, Sections 8.2, 9.1, 9.2, 10.1, 10.2, and 11.1" } ], "status": "internal", "summary": "A declaration field is used only in protocol versions whose MCP type defines it: title and _meta from 2025-06-18, Tool annotations from 2025-03-26, icons and Tool schema $schema from 2025-11-25, Tool execution only in 2025-11-25, and the completions capability from 2025-03-26.", "surface": "Tool, Resource, ResourceTemplate, Prompt, PromptArgument, ServerCapabilities", "title": "Keep fields within their supported protocol scope" }, { "applicability": { "protocolVersions": "independent" }, "description": "A form-mode requestedSchema is a flat object whose properties are MCP primitive schemas: string, number, integer, boolean, or enumeration, with only the keywords MCP defines for them.", "documentSchema": [ "#/$defs/elicitationFormSchema", "#/$defs/elicitationFormProperty", "#/$defs/elicitationFormOption" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/component-contextual-schemas.json", "pointer": "/tools/0/elicitations/0/requestedSchema" } ], "id": "mcp.elicitation.form-schema.members", "kind": "structural", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-11-25/schema.ts#L2155-L2178", "validation/mcp-schemas/2025-11-25/schema.ts#L2234-L2235", "validation/mcp-schemas/2026-07-28/schema.ts#L2788-L2811", "validation/mcp-schemas/2026-07-28/schema.ts#L2867-L2868" ], "reference": "MCP 2025-11-25 and 2026-07-28 schema.ts, ElicitRequestFormParams and PrimitiveSchemaDefinition", "tier": 1 } ], "specification": [ { "locations": [ "sections/12-elicitation.md#req-elicitation-form-shape" ], "reference": "MCP Description 0.9.0, Section 12.3" } ], "status": "internal", "summary": "requestedSchema is an object schema of MCP primitive property schemas with their defined keywords only.", "surface": "ElicitRequest requestedSchema", "title": "Use MCP primitive schemas in elicitation forms" }, { "applicability": { "protocolVersions": { "2024-11-05": "not-applicable", "2025-03-26": "not-applicable", "2025-06-18": "applies", "2025-11-25": "not-applicable", "2026-07-28": "not-applicable" } }, "description": "The allowed form-schema vocabulary depends on the MCP protocol version. Check the fields of requestedSchema against that vocabulary rather than assuming a general Tool JSON Schema can be copied into an elicitation form unchanged.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/elicitation-form-schema-2025-06-18.json", "pointer": "/prompts/0/elicitations/0/requestedSchema" } ], "id": "mcp.elicitation.form-schema.protocol-shape", "kind": "structural", "owner": "mcp", "path": "requestedSchema", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-06-18/schema.ts#L1453-L1477", "validation/mcp-schemas/2025-06-18/schema.ts#L1479-L1486", "validation/mcp-schemas/2025-06-18/schema.ts#L1517-L1525", "validation/mcp-schemas/2025-06-18/schema.ts#L1527-L1536" ], "reference": "MCP 2025-06-18 schema.ts, ElicitRequest requestedSchema and PrimitiveSchemaDefinition (default only on BooleanSchema; EnumSchema with enum and enumNames)", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2025-11-25/schema.ts#L2150-L2178", "validation/mcp-schemas/2025-11-25/schema.ts#L2228-L2235", "validation/mcp-schemas/2025-11-25/schema.ts#L2463-L2464" ], "reference": "MCP 2025-11-25 schema.ts, requestedSchema $schema, default on all primitive schemas, titled and multi-select enum schemas", "tier": 1 } ], "specification": [ { "locations": [ "sections/12-elicitation.md#req-elicitation-form-vocabulary" ], "reference": "MCP Description 0.9.0, Section 12.3" } ], "status": "internal", "summary": "In MCP 2025-06-18, a form requestedSchema has no $schema, no array or titled enum properties, and default only on boolean properties.", "surface": "ElicitRequest", "title": "Use the applicable elicitation form vocabulary" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Elicitation forms and URL flows are not available in every MCP protocol version. Scope declarations and interaction examples to the versions that define the chosen mode. Describing an interaction does not make that interaction available in an older protocol version.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/elicitation-version-mismatch.json", "pointer": "/tools/0/elicitations/0" }, { "outcome": "error", "path": "expected-invalid/invalid-tool-interaction-example-semantics.json", "pointer": "/tools/0/interactionExamples/broken/steps/0/request" } ], "id": "mcp.elicitation.protocol-version", "kind": "structural", "notes": "Elicitation Declarations scoped before MCP 2025-06-18 are outside the complete semantic checks (Section 16.2).", "owner": "mcp", "path": "mode", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-03-26/schema.ts#L202-L223", "validation/mcp-schemas/2025-06-18/schema.ts#L1453-L1477", "validation/mcp-schemas/2025-11-25/schema.ts#L2180-L2208", "validation/mcp-schemas/2026-07-28/schema.ts#L2813-L2838" ], "reference": "MCP 2025-03-26 schema.ts (no elicitation/create); MCP 2025-06-18 schema.ts, ElicitRequest (form only); MCP 2025-11-25 and 2026-07-28 schema.ts, ElicitRequestURLParams (mode \"url\")", "tier": 1 } ], "specification": [ { "locations": [ "sections/12-elicitation.md#req-elicitation-protocol-versions", "sections/09-tools.md#req-interaction-protocol-version-valid" ], "reference": "MCP Description 0.9.0, Sections 9.4 and 12.5" } ], "status": "internal", "summary": "Elicitation is used only from MCP 2025-06-18, and URL mode only from MCP 2025-11-25, in declarations and in Tool interaction steps.", "surface": "ElicitRequest", "title": "Use elicitation only where the version supports it" }, { "applicability": { "protocolVersions": "independent" }, "description": "Example results carry MCP result values: a Tool result has content, a resource read result has contents, a prompt result has messages, and a completion result has completion. Their members follow the MCP types.", "documentSchema": [ "#/$defs/completedToolResultExample", "#/$defs/completedReadResourceResultExample", "#/$defs/completedPromptResultExample", "#/$defs/promptMessageExample", "#/$defs/completedCompletionResultExample" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/malformed-resource-examples.json", "pointer": "/resourceTemplates/0/examples/missing-uri/result/contents" }, { "outcome": "error", "path": "expected-invalid/resource-example-cache-fields.json", "pointer": "/resources/1/examples/invalid/result/cacheScope" } ], "id": "mcp.example-result.members", "kind": "structural", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-11-25/schema.ts#L1104-L1130", "validation/mcp-schemas/2025-11-25/schema.ts#L723-L725", "validation/mcp-schemas/2025-11-25/schema.ts#L971-L977", "validation/mcp-schemas/2025-11-25/schema.ts#L1032-L1035", "validation/mcp-schemas/2025-11-25/schema.ts#L2042-L2057", "validation/mcp-schemas/2026-07-28/schema.ts#L1809-L1838", "validation/mcp-schemas/2026-07-28/schema.ts#L1229-L1231", "validation/mcp-schemas/2026-07-28/schema.ts#L1634-L1640", "validation/mcp-schemas/2026-07-28/schema.ts#L1704-L1707", "validation/mcp-schemas/2026-07-28/schema.ts#L2644-L2661" ], "reference": "MCP 2025-11-25 and 2026-07-28 schema.ts, CallToolResult, ReadResourceResult, GetPromptResult, PromptMessage, and CompleteResult", "tier": 1 } ], "specification": [ { "locations": [ "sections/03-document-structure.md#req-carried-defined-fields", "sections/09-tools.md#req-tool-example-result-shape", "sections/10-resources.md#req-resource-example-result-shape", "sections/11-prompts.md#req-prompt-example-result-shape", "sections/03-document-structure.md#req-completed-result-fields", "sections/10-resources.md#req-resource-example-contents", "sections/10-resources.md#req-template-completion-result", "sections/11-prompts.md#req-prompt-completion-result" ], "reference": "MCP Description 0.9.0, Sections 3.6, 9.3, 10.4.4, and 11.3" } ], "status": "internal", "summary": "Completed example results have the required members and member types of the MCP result type they carry.", "surface": "CallToolResult, ReadResourceResult, GetPromptResult, CompleteResult", "title": "Give example results their MCP result shape" }, { "applicability": { "protocolVersions": "independent" }, "description": "An icons array is non-empty, and each Icon has a src and only the MCP Icon properties mimeType, sizes, and theme, with theme light or dark.", "documentSchema": [ "#/$defs/icons", "#/$defs/icon" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/empty-ordinary-nested-collections.json", "pointer": "/info/icons" } ], "id": "mcp.icon.members", "kind": "structural", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-11-25/schema.ts#L464-L501", "validation/mcp-schemas/2026-07-28/schema.ts#L890-L927" ], "reference": "MCP 2025-11-25 and 2026-07-28 schema.ts, interface Icon", "tier": 1 } ], "specification": [ { "locations": [ "sections/99-appendices.md#req-icon-fields", "sections/15-serialization.md#req-serialization-value-formats" ], "reference": "MCP Description 0.9.0, Appendix A" } ], "status": "internal", "summary": "icons is a non-empty array of MCP Icon objects with a src and only the properties MCP defines.", "surface": "Icon", "title": "Use MCP Icon objects for icons" }, { "applicability": { "protocolVersions": { "2024-11-05": "not-applicable", "2025-03-26": "not-applicable", "2025-06-18": "not-applicable", "2025-11-25": "not-applicable", "2026-07-28": "applies" } }, "description": "In MCP 2026-07-28, sampling, elicitation, and roots responses are closed input responses rather than open results. Remove undefined fields; _meta is defined only for the sampling response. Earlier versions' open-result behavior does not carry forward to these types.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/closed-step-responses-2026.json", "pointer": "/tools/0/interactionExamples/approved/steps/0/response" } ], "id": "mcp.input-response.closed", "kind": "structural", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2026-07-28/schema.ts#L541-L542", "validation/mcp-schemas/2026-07-28/schema.ts#L2190-L2228", "validation/mcp-schemas/2026-07-28/schema.ts#L3120-L3149", "validation/mcp-schemas/2026-07-28/schema.ts#L2725-L2744" ], "reference": "MCP 2026-07-28 schema.ts, type InputResponse (CreateMessageResult, ListRootsResult, ElicitResult); none extends Result; only CreateMessageResult defines _meta, through SamplingMessage", "tier": 1 } ], "specification": [ { "locations": [ "sections/03-document-structure.md#req-carried-closed-reject", "sections/09-tools.md#req-interaction-protocol-version-valid" ], "reference": "MCP Description 0.9.0, Sections 3.6 and 9.4" } ], "status": "internal", "summary": "In MCP 2026-07-28, sampling, elicitation, and roots responses are input responses, not results, and accept only the fields their types define.", "surface": "InputResponse", "title": "Keep newer client input responses closed" }, { "applicability": { "protocolVersions": "independent" }, "description": "Interaction steps carry MCP values: elicitation requests and results, sampling requests, messages, and results, and roots lists. Each has the members its MCP type requires and defines.", "documentSchema": [ "#/$defs/elicitationInteractionRequest", "#/$defs/elicitationInteractionFormRequest", "#/$defs/elicitationInteractionUrlRequest", "#/$defs/elicitationInteractionResponse", "#/$defs/elicitationInteractionAcceptedResponse", "#/$defs/elicitationInteractionDeclinedResponse", "#/$defs/samplingCreateMessageRequest", "#/$defs/samplingCreateMessageResult", "#/$defs/samplingMessage", "#/$defs/samplingMessageContent", "#/$defs/samplingContentBlock", "#/$defs/samplingModelHint", "#/$defs/samplingModelPreferences", "#/$defs/samplingRequestTool", "#/$defs/samplingToolChoice", "#/$defs/samplingToolResultContent", "#/$defs/samplingToolUseContent", "#/$defs/rootsListRequest", "#/$defs/rootsListResult", "#/$defs/rootDeclaration" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/malformed-sampling-step.json", "pointer": "/tools/0/interactionExamples/summary/steps/0/request" }, { "outcome": "error", "path": "expected-invalid/elicitation-response-unknown-member.json", "pointer": "/tools/0/interactionExamples/approval/steps/0/response" }, { "outcome": "error", "path": "expected-invalid/discriminated-union-members.json", "pointer": "/tools/0/interactionExamples/invalid/steps/0" } ], "id": "mcp.interaction-message.members", "kind": "structural", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-11-25/schema.ts#L1578-L1622", "validation/mcp-schemas/2025-11-25/schema.ts#L1681-L1688", "validation/mcp-schemas/2025-11-25/schema.ts#L1656-L1674", "validation/mcp-schemas/2025-11-25/schema.ts#L2155-L2178", "validation/mcp-schemas/2025-11-25/schema.ts#L2471-L2486", "validation/mcp-schemas/2025-11-25/schema.ts#L2107-L2109", "validation/mcp-schemas/2025-11-25/schema.ts#L2116-L2136", "validation/mcp-schemas/2026-07-28/schema.ts#L2104-L2152", "validation/mcp-schemas/2026-07-28/schema.ts#L2245-L2249", "validation/mcp-schemas/2026-07-28/schema.ts#L2210-L2228", "validation/mcp-schemas/2026-07-28/schema.ts#L2788-L2811", "validation/mcp-schemas/2026-07-28/schema.ts#L3134-L3149", "validation/mcp-schemas/2026-07-28/schema.ts#L2742-L2744", "validation/mcp-schemas/2026-07-28/schema.ts#L2758-L2775" ], "reference": "MCP 2025-11-25 and 2026-07-28 schema.ts, CreateMessageRequestParams, SamplingMessage, CreateMessageResult, ElicitRequestFormParams, ElicitResult, ListRootsResult, and Root", "tier": 1 } ], "specification": [ { "locations": [ "sections/03-document-structure.md#req-carried-defined-fields", "sections/09-tools.md#req-interaction-protocol-version-valid" ], "reference": "MCP Description 0.9.0, Sections 3.6 and 9.4" } ], "status": "internal", "summary": "Elicitation, sampling, and roots requests and responses in interaction steps have the members and member types of their MCP types.", "surface": "ElicitRequest, ElicitResult, CreateMessageRequest, CreateMessageResult, ListRootsResult, Root", "title": "Use MCP shapes in interaction requests and responses" }, { "applicability": { "protocolVersions": "independent" }, "description": "MCP metadata keys follow a grammar for an optional dotted prefix and a local name. Check separators and permitted characters when a key is rejected. Reserved-name context and value checks are separate from this key-format check.", "documentSchema": [ "#/$defs/metaObject" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/meta-key-invalid.json", "pointer": "/tools/0" } ], "id": "mcp.meta.key-format", "kind": "structural", "notes": "The document schema rejects malformed keys first; the semantic key check applies only to direct callers of the semantic validator.", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-06-18/basic/index.mdx#L134-L147", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-11-25/basic/index.mdx#L201-L215", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/basic/index.mdx#L330-L446" ], "reference": "MCP 2025-06-18 to 2026-07-28 specification, Basic, General fields, _meta key name format", "tier": 1 } ], "specification": [ { "locations": [ "sections/03-document-structure.md#req-meta-keys" ], "reference": "MCP Description 0.9.0, Section 3.5 (the same grammar applies in every protocol version)" } ], "status": "internal", "summary": "A _meta key has an optional prefix of dot-separated labels followed by a slash, and a name that begins and ends with an alphanumeric character.", "surface": "_meta", "title": "Use valid metadata key names" }, { "applicability": { "protocolVersions": { "2024-11-05": "not-applicable", "2025-03-26": "not-applicable", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "A recognized reserved metadata key has a specific context and value shape. A key valid on one message or object may be invalid on another. Check the containing object and protocol version rather than moving the same key unchanged into every _meta object.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/meta-reserved-key-misuse.json", "pointer": "/tools/0/_meta" }, { "outcome": "error", "path": "expected-invalid/meta-reserved-keys-in-carried-values.json", "pointer": "/prompts/0/completionExamples/request-key-in-result/result/_meta" } ], "id": "mcp.meta.reserved-key-context", "kind": "semantic", "notes": "Checked on declarations and on every carried value: example results, their content, interaction step responses, and roots. MCP 2024-11-05 and 2025-03-26 do not define reserved keys; Section 16.2 limits validation for those protocol versions.", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-06-18/basic/index.mdx#L123-L147", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-11-25/basic/index.mdx#L190-L215", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/basic/index.mdx#L322-L446" ], "reference": "MCP 2025-06-18 to 2026-07-28 specification, Basic, General fields, _meta (reserved keys and where they apply)", "tier": 1 } ], "specification": [ { "locations": [ "sections/03-document-structure.md#req-meta-keys" ], "reference": "MCP Description 0.9.0, Section 3.5" } ], "status": "internal", "summary": "A reserved _meta key appears only in the message context, and with the value, that the MCP protocol version defines for it.", "surface": "_meta", "title": "Place reserved metadata in its defined context" }, { "applicability": { "protocolVersions": { "2024-11-05": "not-applicable", "2025-03-26": "not-applicable", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "An unrecognized key in an MCP-reserved namespace may belong to a newer protocol definition. It is retained with a warning rather than assigned invented semantics. Verify the key and protocol version before treating it as a recognized MCP feature.", "enforcement": "internal", "fixtures": [ { "outcome": "warning", "path": "expected-warning/unknown-reserved-meta-key.json", "pointer": "/prompts/0/_meta" } ], "id": "mcp.meta.reserved-prefix", "kind": "semantic", "notes": "A later MCP protocol version may define the key, so it is preserved rather than rejected.", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-06-18/basic/index.mdx#L140-L142", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-11-25/basic/index.mdx#L208-L210", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/basic/index.mdx#L337-L339" ], "reference": "MCP 2025-06-18 to 2026-07-28 specification, Basic, General fields, _meta (a prefix whose second label is modelcontextprotocol or mcp is reserved for MCP use)", "tier": 1 } ], "specification": [ { "locations": [ "sections/03-document-structure.md#req-meta-reserved-prefix" ], "reference": "MCP Description 0.9.0, Section 3.5" } ], "status": "internal", "summary": "A _meta key under an MCP-reserved prefix that the MCP protocol version does not define is preserved with a warning.", "surface": "_meta", "title": "Preserve unknown reserved metadata with a warning" }, { "applicability": { "protocolVersions": "independent" }, "description": "A Resource example's blob must be valid base64. Check the encoding rather than placing raw binary or a URL in the field. Encoded content remains untrusted, and a valid encoding does not establish that the resource exists or is safe to open.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/resource-example-result-semantics.json", "pointer": "/resources/0/examples/invalid-result/result/contents/0" } ], "id": "mcp.resource-contents.blob.base64", "kind": "structural", "owner": "mcp", "path": "blob", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L507-L512", "validation/mcp-schemas/2025-03-26/schema.ts#L545-L550", "validation/mcp-schemas/2025-06-18/schema.ts#L637-L642", "validation/mcp-schemas/2025-11-25/schema.ts#L913-L918", "validation/mcp-schemas/2026-07-28/schema.ts#L1549-L1554" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, interface BlobResourceContents, blob (@format byte)", "tier": 1 }, { "locations": [ "https://www.rfc-editor.org/rfc/rfc4648#section-4" ], "reference": "RFC 4648, Section 4", "tier": 2 } ], "specification": [ { "locations": [ "sections/10-resources.md#req-resource-example-blob-base64" ], "reference": "MCP Description 0.9.0, Section 10.4.4" } ], "status": "internal", "summary": "A blob in Resource Contents is canonical base64.", "surface": "BlobResourceContents", "title": "Encode binary Resource Contents as base64" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Resource Contents entries acquire _meta from MCP 2025-06-18. This is separate from result-level _meta, which is available in every supported version. Move or remove a misplaced value only after deciding which object it describes.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/resource-example-result-semantics.json", "pointer": "/resources/1/examples/unsupported-metadata/result/contents/0" } ], "id": "mcp.resource-contents.meta.protocol-version", "kind": "structural", "owner": "mcp", "path": "_meta", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L483-L497", "validation/mcp-schemas/2025-03-26/schema.ts#L521-L535", "validation/mcp-schemas/2025-06-18/schema.ts#L600-L621", "validation/mcp-schemas/2025-11-25/schema.ts#L876-L897", "validation/mcp-schemas/2026-07-28/schema.ts#L1509-L1527" ], "reference": "MCP 2024-11-05 and 2025-03-26 schema.ts, interface ResourceContents (uri, mimeType); MCP 2025-06-18 to 2026-07-28 schema.ts, interface ResourceContents (adds _meta)", "tier": 1 } ], "specification": [ { "locations": [ "sections/10-resources.md#req-resource-contents-meta" ], "reference": "MCP Description 0.9.0, Section 10.4.4" } ], "status": "internal", "summary": "Resource contents carry _meta only from MCP 2025-06-18, in Resource examples and in embedded resources.", "surface": "ResourceContents", "title": "Use Resource Contents metadata where supported" }, { "applicability": { "protocolVersions": "independent" }, "description": "Every Resource Template must contain a valid RFC 6570 URI template, even if it has no examples. Correct malformed braces, operators, or variable syntax before checking concrete expansions. The validator does not retrieve the resulting URI.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/malformed-uri-template-without-examples.json", "pointer": "/resourceTemplates/0" }, { "outcome": "error", "path": "expected-invalid/malformed-resource-template-example.json", "pointer": "/resourceTemplates/0" }, { "outcome": "error", "path": "expected-invalid/invalid-completion-example-semantics.json", "pointer": "/resourceTemplates/0" } ], "id": "mcp.resource-template.uri-template", "kind": "embedded-standard", "notes": "Reported once per Resource Template, whether or not it has examples; example checks that need the parsed template are skipped.", "owner": "mcp", "path": "uriTemplate", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L456-L461", "validation/mcp-schemas/2025-03-26/schema.ts#L489-L494", "validation/mcp-schemas/2025-06-18/schema.ts#L570-L575", "validation/mcp-schemas/2025-11-25/schema.ts#L846-L851", "validation/mcp-schemas/2026-07-28/schema.ts#L1482-L1487" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, interface ResourceTemplate, uriTemplate (\"A URI template (according to RFC 6570)\")", "tier": 1 }, { "locations": [ "https://www.rfc-editor.org/rfc/rfc6570#section-3" ], "reference": "RFC 6570, URI Template", "tier": 2 } ], "specification": [ { "locations": [ "sections/10-resources.md#req-resource-template-uri-template" ], "reference": "MCP Description 0.9.0, Section 10.2.1" } ], "status": "internal", "summary": "A Resource Template uriTemplate is a valid RFC 6570 URI template.", "surface": "ResourceTemplate", "title": "Use a valid Resource Template expression" }, { "applicability": { "protocolVersions": "independent" }, "arbitrations": [ { "authority": "MCP's schema generation configuration (--defaultNumberType integer), under which an unannotated number denotes an integer and fields that accept fractions carry @TJS-type number, such as Annotations.priority.", "behavior": "Reject a non-integer size with schema-validation. No minimum is applied, as MCP defines none.", "conflict": "schema.ts declares size as number, which TypeScript cannot restrict to integers; the generated schema.json types it as integer.", "protocolVersions": [ "2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25", "2026-07-28" ], "rationale": "The integer output is MCP's deliberate convention, not a generator defect. Following it keeps native projection valid against the generated schema and matches what MCP tooling validates.", "reviewTrigger": "MCP changes its generator configuration or annotates size with @TJS-type number.", "status": "active" } ], "description": "Resource declarations and resource-link content express raw size as an integer, following MCP's numeric schema convention. Replace a fractional value with the intended integer; the validator must not round it. No minimum is added beyond MCP's definition.", "documentSchema": [ "#/$defs/resource/properties/size", "#/$defs/toolResultContent/allOf/3/then/properties/size" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/fractional-resource-size.json", "pointer": "/resources/0/size" }, { "outcome": "error", "path": "expected-invalid/fractional-resource-link-size.json", "pointer": "/tools/0/examples/listing/result/content/0/size" }, { "outcome": "error", "path": "expected-invalid/discriminated-resource-link-size.json", "pointer": "/tools/0/interactionExamples/nested/steps/0/response/content/size" }, { "outcome": "passes", "path": "expected-valid/discriminated-unions.json", "pointer": "/tools/0/interactionExamples/approved/steps/1/response/content/size" }, { "outcome": "passes", "path": "expected-valid/named-resource-examples.json", "pointer": "/resources/2/size" } ], "id": "mcp.resource.size", "kind": "structural", "owner": "mcp", "path": "size", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L449", "validation/mcp-schemas/2025-03-26/schema.ts#L482", "validation/mcp-schemas/2025-06-18/schema.ts#L556", "validation/mcp-schemas/2025-11-25/schema.ts#L832", "validation/mcp-schemas/2026-07-28/schema.ts#L1471", "validation/mcp-schemas/2026-07-28/schema.ts#L1719-L1721" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, interface Resource, size (unannotated number); ResourceLink extends Resource from 2025-06-18", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2024-11-05/schema.json#L1508-L1511", "validation/mcp-schemas/2026-07-28/schema.json#L2760-L2763", "validation/mcp-schemas/2026-07-28/schema.json#L2830-L2833" ], "reference": "MCP generated schema.json, Resource and ResourceLink size typed integer", "tier": 3 }, { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/scripts/generate-schemas.ts#L95" ], "reference": "MCP scripts/generate-schemas.ts: typescript-json-schema --defaultNumberType integer", "tier": 3 } ], "specification": [ { "locations": [ "sections/10-resources.md#req-resource-size-integer", "sections/03-document-structure.md#req-mcp-integer-numbers" ], "reference": "MCP Description 0.9.0, Sections 3.6 and 10.1.1" }, { "locations": [ "proposal-snapshots/0029-integer-mcp-numbers.md" ], "reference": "Proposal 0029, Integer MCP Numbers" } ], "status": "arbitrated", "summary": "Resource size, in a declaration and in resource link content, is an integer when present.", "surface": "Resource", "title": "Express resource sizes as integers" }, { "applicability": { "protocolVersions": "independent" }, "description": "A Resource uri is a URI as defined by RFC 3986, with a scheme; a relative reference or free text is invalid. Any scheme is allowed, including custom ones. MCP types the field as a URI, so a value that is not one cannot be projected to a native MCP Resource.", "documentSchema": [ "#/$defs/resource/properties/uri" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/invalid-resource-uri.json", "pointer": "/resources/0/uri" }, { "outcome": "error", "path": "expected-invalid/invalid-resource-uri.json", "pointer": "/resources/1/uri" } ], "id": "mcp.resource.uri", "kind": "structural", "owner": "mcp", "path": "uri", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L419-L423", "validation/mcp-schemas/2025-03-26/schema.ts#L447-L451", "validation/mcp-schemas/2025-06-18/schema.ts#L528-L532", "validation/mcp-schemas/2025-11-25/schema.ts#L804-L808", "validation/mcp-schemas/2026-07-28/schema.ts#L1443-L1447" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, interface Resource, uri (@format uri)", "tier": 1 } ], "specification": [ { "locations": [ "sections/10-resources.md#req-resource-uri-syntax", "sections/15-serialization.md#req-serialization-value-formats" ], "reference": "MCP Description 0.9.0, Sections 10.1.2 and 15" } ], "status": "internal", "summary": "Resource uri is an RFC 3986 URI with a scheme.", "surface": "Resource", "title": "Identify resources with absolute URIs" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "An open MCP result can carry fields that its protocol version does not define. Those values are preserved without assigning them later-version meaning, and a warning identifies the affected version. Review the field or split protocol variants if the warning is not intended.", "enforcement": "internal", "fixtures": [ { "outcome": "warning", "path": "expected-warning/open-result-unknown-properties.json", "pointer": "/tools/0/examples/traced/result" }, { "outcome": "warning", "path": "expected-warning/open-results-shared-across-protocol-versions.json", "pointer": "/prompts/0/examples/default/result" }, { "outcome": "warning", "path": "expected-warning/open-step-responses-before-2026.json", "pointer": "/tools/0/interactionExamples/approved/steps/0/response" }, { "outcome": "warning", "path": "expected-warning/component-protocol-scope.json", "pointer": "/components/resourceExamples/current/result" } ], "id": "mcp.result.additional-properties.preserve", "kind": "preservation", "notes": "The warnings of this rule for a document equal the union of its warnings for each protocol-version-specific Effective Protocol View (scripts/test-views.mjs).", "owner": "mcp", "requirement": "may", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L42-L48", "validation/mcp-schemas/2025-03-26/schema.ts#L61-L67", "validation/mcp-schemas/2025-06-18/schema.ts#L60-L69", "validation/mcp-schemas/2025-11-25/schema.ts#L88-L97", "validation/mcp-schemas/2026-07-28/schema.ts#L218-L236" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, interface Result (index signature [key: string]: unknown, inherited by every result type)", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L793-L805", "validation/mcp-schemas/2025-03-26/schema.ts#L899-L911", "validation/mcp-schemas/2025-06-18/schema.ts#L1067-L1081", "validation/mcp-schemas/2025-11-25/schema.ts#L1649-L1674", "validation/mcp-schemas/2025-06-18/schema.ts#L1538-L1557", "validation/mcp-schemas/2025-11-25/schema.ts#L2466-L2486", "validation/mcp-schemas/2024-11-05/schema.ts#L1032-L1039", "validation/mcp-schemas/2025-03-26/schema.ts#L1173-L1180", "validation/mcp-schemas/2025-06-18/schema.ts#L1404-L1413", "validation/mcp-schemas/2025-11-25/schema.ts#L2100-L2109" ], "reference": "MCP 2024-11-05 to 2025-11-25 schema.ts, CreateMessageResult, ElicitResult, and ListRootsResult extend Result", "tier": 1 } ], "specification": [ { "locations": [ "sections/03-document-structure.md#req-carried-open-preserve" ], "reference": "MCP Description 0.9.0, Section 3.6 (Carried MCP Values)" } ], "status": "internal", "summary": "A field that an open MCP result type allows but the MCP protocol version does not define is accepted and preserved without meaning, with a warning attributed to that protocol version.", "surface": "Result", "title": "Preserve fields on open results with a warning" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Root entries acquire _meta from MCP 2025-06-18. This is different from metadata on the surrounding roots result. Remove misplaced metadata or scope the containing example to protocol versions that define it.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/root-meta-before-2025-06-18.json", "pointer": "/tools/0/interactionExamples/with-root-meta/steps/0/response/roots/0" }, { "outcome": "passes", "path": "expected-warning/open-step-responses-before-2026.json", "pointer": "/tools/0/interactionExamples/approved/steps/0/response/roots/0" } ], "id": "mcp.root.meta.protocol-version", "kind": "structural", "owner": "mcp", "path": "_meta", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L1041-L1059", "validation/mcp-schemas/2025-03-26/schema.ts#L1182-L1200", "validation/mcp-schemas/2025-06-18/schema.ts#L1415-L1440", "validation/mcp-schemas/2025-11-25/schema.ts#L2111-L2136", "validation/mcp-schemas/2026-07-28/schema.ts#L2746-L2775" ], "reference": "MCP 2024-11-05 and 2025-03-26 schema.ts, interface Root (uri, name); MCP 2025-06-18 to 2026-07-28 schema.ts, interface Root (adds _meta)", "tier": 1 } ], "specification": [ { "locations": [ "sections/03-document-structure.md#req-meta-protocol-version-availability", "sections/09-tools.md#req-interaction-protocol-version-valid" ], "reference": "MCP Description 0.9.0, Sections 3.5, 3.6, and 9.4" } ], "status": "internal", "summary": "A root in a roots response may carry _meta from MCP 2025-06-18.", "surface": "Root", "title": "Use root metadata only where supported" }, { "applicability": { "protocolVersions": "independent" }, "description": "Root entries in interaction responses use file:// URIs. An arbitrary resource URI is not a valid root merely because the resource is accessible to the server. Correct the root URI without fetching or probing the referenced filesystem location.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/invalid-tool-interaction-example-semantics.json", "pointer": "/tools/0/interactionExamples/broken/steps/3/response/roots/0" } ], "id": "mcp.root.uri.file-scheme", "kind": "semantic", "owner": "mcp", "path": "uri", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L1045-L1052", "validation/mcp-schemas/2025-03-26/schema.ts#L1186-L1193", "validation/mcp-schemas/2025-06-18/schema.ts#L1421-L1428", "validation/mcp-schemas/2025-11-25/schema.ts#L2117-L2124", "validation/mcp-schemas/2026-07-28/schema.ts#L2759-L2766" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, interface Root, uri (\"This *must* start with file:// for now\")", "tier": 1 }, { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/client/roots.mdx#L100-L102" ], "reference": "MCP 2026-07-28 specification, Client Features, Roots, Data Types (uri MUST be a file:// URI)", "tier": 1 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-interaction-protocol-version-valid", "sections/09-tools.md#req-interaction-response-closed" ], "reference": "MCP Description 0.9.0, Section 9.4" } ], "status": "internal", "summary": "A root URI in a roots response starts with file://.", "surface": "Root", "title": "Use file URIs for roots" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Sampling tools and toolChoice are available from MCP 2025-11-25. Earlier-version interaction examples cannot use those fields. Remove them or narrow the containing Tool's protocol scope to versions that support them.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/invalid-tool-interaction-example-semantics.json", "pointer": "/tools/0/interactionExamples/broken/steps/2/request" } ], "id": "mcp.sampling.tools.protocol-version", "kind": "structural", "owner": "mcp", "path": "tools, toolChoice", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-06-18/schema.ts#L1028-L1065", "validation/mcp-schemas/2025-11-25/schema.ts#L1573-L1622", "validation/mcp-schemas/2026-07-28/schema.ts#L2086-L2152" ], "reference": "MCP 2025-06-18 schema.ts, CreateMessageRequest (no tools); MCP 2025-11-25 and 2026-07-28 schema.ts, CreateMessageRequestParams tools and toolChoice", "tier": 1 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-interaction-sampling-protocol-version" ], "reference": "MCP Description 0.9.0, Section 9.4" } ], "status": "internal", "summary": "A sampling request uses tools and toolChoice only from MCP 2025-11-25.", "surface": "CreateMessageRequest", "title": "Use sampling tools only where supported" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "arbitrations": [ { "authority": "MCP schema.ts type, the source of truth for message structures", "behavior": "Reject unknown top-level members. Custom capabilities belong in experimental and, from MCP 2026-07-28, in extensions.", "conflict": "The TypeScript type declares a fixed set of members and no index signature, while its doc comment says the set is not closed and any server can define additional capabilities. The comment does not say where such capabilities go; experimental is the defined container.", "protocolVersions": [ "2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25", "2026-07-28" ], "rationale": "Capabilities are sent on the wire during initialization, so the structural source of truth governs. Closing is also the reversible choice: opening the object later invalidates no document, while closing it later would.", "reviewTrigger": "Resolution of MCP issue 1898, an upstream clarification of the doc comment, or a later MCP protocol version adding an index signature.", "status": "active", "upstream": "https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1898" } ], "description": "Server capabilities have defined members rather than arbitrary top-level names. Remove unknown members or use the experimental or extensions maps where the applicable protocol version allows them. MCP Description specification extensions follow their own x- rules.", "documentSchema": [ "#/$defs/capabilities", "#/$defs/capabilityPrompts", "#/$defs/capabilityResources", "#/$defs/capabilityTools", "#/$defs/extensionCapabilities" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/unknown-server-capability.json", "pointer": "/capabilities/0" }, { "outcome": "passes", "path": "expected-valid/client-capability-requirements.json", "pointer": "/capabilities/0" } ], "id": "mcp.server-capabilities.members", "kind": "structural", "notes": "x-* properties are MCP Description specification extensions, not capabilities; native projection removes them.", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L205-L248", "validation/mcp-schemas/2025-03-26/schema.ts#L225-L272", "validation/mcp-schemas/2025-06-18/schema.ts#L253-L302", "validation/mcp-schemas/2025-11-25/schema.ts#L381-L457", "validation/mcp-schemas/2026-07-28/schema.ts#L788-L883" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, interface ServerCapabilities (no index signature)", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L205-L207", "validation/mcp-schemas/2025-03-26/schema.ts#L225-L227", "validation/mcp-schemas/2025-06-18/schema.ts#L253-L257", "validation/mcp-schemas/2025-11-25/schema.ts#L381-L385", "validation/mcp-schemas/2026-07-28/schema.ts#L788-L792" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, ServerCapabilities doc comment (\"this is not a closed set: any server can define its own, additional capabilities\")", "tier": 1 } ], "specification": [ { "locations": [ "sections/08-capabilities.md#req-capabilities-closed", "sections/08-capabilities.md#req-extensions-identifier-form", "sections/14-specification-extensions.md#req-extension-ineligible-locations" ], "reference": "MCP Description 0.9.0, Sections 8.2 and 8.4" } ], "status": "arbitrated", "summary": "A server Capabilities Object contains only the capabilities the applicable MCP protocol version defines; custom capabilities go in experimental and, from MCP 2026-07-28, in extensions.", "surface": "ServerCapabilities", "title": "Advertise only recognized server capabilities" }, { "applicability": { "protocolVersions": { "2024-11-05": "not-applicable", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Tool annotations are a closed set of behavior hints. Resource annotation fields such as audience and priority do not belong here, and custom keys are not allowed. Remove those properties; author-reviewed server metadata can instead use the Tool's _meta where the protocol version defines it.", "documentSchema": [ "#/$defs/toolAnnotations" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/tool-annotations-unknown-property.json", "pointer": "/tools/0/annotations" }, { "outcome": "passes", "path": "expected-valid/distinct-tool-and-resource-annotations.json", "pointer": "/tools/0/annotations" } ], "id": "mcp.tool-annotations.members", "kind": "structural", "notes": "Tool annotations are not available in MCP 2024-11-05; that boundary is checked separately.", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-03-26/schema.ts#L727-L779", "validation/mcp-schemas/2025-06-18/schema.ts#L869-L923", "validation/mcp-schemas/2025-11-25/schema.ts#L1168-L1222", "validation/mcp-schemas/2026-07-28/schema.ts#L1900-L1954" ], "reference": "MCP 2025-03-26 to 2026-07-28 schema.ts, interface ToolAnnotations (no index signature)", "tier": 1 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-tool-annotations-closed", "sections/09-tools.md#req-tool-annotations-fields" ], "reference": "MCP Description 0.9.0, Section 9.6" } ], "status": "internal", "summary": "A Tool annotations object contains only title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.", "surface": "ToolAnnotations", "title": "Tool annotations contain only MCP hints" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "arbitrations": [ { "authority": "MCP specification text on schema dialects, with the requirement that tool arguments are objects", "behavior": "Reject a declared root type that excludes \"object\"; accept other roots that are valid under the dialect, which mcp.tool.schema.native-shape reports as warnings.", "conflict": "The specification validates embedded schemas under their declared or default dialect, while schema.ts requires the JSON Schema keyword and value type \"object\" at the root. A schema rooted in $ref or allOf can describe an object but does not match the TypeScript type.", "protocolVersions": [ "2025-11-25", "2026-07-28" ], "rationale": "One position for every conflict between MCP's dialect text and the schema syntax of its TypeScript types (Proposal 0032): MCP Description enforces what MCP requires of the data and reports, but does not decide, the narrower TypeScript syntax. Replaces the Draft 3 decision to require a literal type \"object\" in every protocol version.", "reviewTrigger": "Resolution of MCP issue 3238 or a later MCP protocol version that changes the inputSchema type.", "status": "active", "upstream": "https://github.com/modelcontextprotocol/modelcontextprotocol/issues/3238" } ], "description": "Tool arguments are always a JSON object, so after component resolution the inputSchema root must describe an object. Before MCP 2025-11-25 the root declares the literal type object. From MCP 2025-11-25 a declared root type must include object; a root in $ref or allOf stays valid, and mcp.tool.schema.native-shape warns that the MCP Tool type expects a literal type object.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/non-object-input-schema.json", "pointer": "/tools/0/inputSchema" }, { "outcome": "error", "path": "expected-invalid/non-object-input-schema.json", "pointer": "/tools/2/inputSchema" }, { "outcome": "error", "path": "expected-invalid/non-literal-object-input-schema-before-2025-11-25.json", "pointer": "/tools/0/inputSchema" }, { "outcome": "passes", "path": "expected-valid/custom-tool-schema-keywords.json", "pointer": "/tools/0/inputSchema" }, { "outcome": "passes", "path": "expected-warning/tool-schema-mcp-type-mismatch.json", "pointer": "/tools/2/inputSchema" } ], "id": "mcp.tool.input-schema.object-root", "kind": "structural", "owner": "mcp", "path": "inputSchema", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L696-L703", "validation/mcp-schemas/2025-03-26/schema.ts#L797-L804", "validation/mcp-schemas/2025-06-18/schema.ts#L938-L945", "validation/mcp-schemas/2025-11-25/schema.ts#L1257-L1265", "validation/mcp-schemas/2026-07-28/schema.ts#L1981-L1997" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, interface Tool, inputSchema type: \"object\"", "tier": 1 }, { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/server/tools.mdx#L293-L293" ], "reference": "MCP 2026-07-28 specification, Server Features, Tools, Data Types, Tool (inputSchema MUST be a valid JSON Schema object, not null)", "tier": 1 }, { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-11-25/basic/index.mdx#L140-L186", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/basic/index.mdx#L251-L297" ], "reference": "MCP 2025-11-25 and 2026-07-28 specification, Basic, JSON Schema usage (schemas are validated under their declared or default dialect)", "tier": 1 }, { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/seps/2106-json-schema-2020-12.md" ], "reference": "MCP SEP-2106 (Final), which keeps type \"object\" deliberately", "tier": 4 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-tool-input-schema-object-root" ], "reference": "MCP Description 0.9.0, Section 9.2" } ], "status": "arbitrated", "summary": "Tool inputSchema describes an object: a literal type \"object\" before MCP 2025-11-25, and from MCP 2025-11-25 a declared root type that includes \"object\".", "surface": "Tool", "title": "Give Tool input schemas an object root" }, { "applicability": { "protocolVersions": { "2024-11-05": "opaque", "2025-03-26": "opaque", "2025-06-18": "opaque", "2025-11-25": "opaque", "2026-07-28": "applies" } }, "description": "MCP 2026-07-28 gives x-mcp-header meaning on string, integer, or boolean input properties reachable through properties chains. Check header tokens, placement, and case-insensitive uniqueness. Earlier protocol versions preserve the keyword without applying those MCP header semantics.", "enforcement": "internal", "fixtures": [ { "outcome": "not-applicable", "path": "expected-valid/protocol-version-inapplicable-mcp-header.json", "pointer": "/tools/0/inputSchema" }, { "outcome": "passes", "path": "expected-valid/custom-tool-schema-keywords.json", "pointer": "/tools/0/inputSchema/properties/region" }, { "outcome": "error", "path": "expected-invalid/invalid-mcp-header-value.json", "pointer": "/tools/0/inputSchema/properties/region" }, { "outcome": "error", "path": "expected-invalid/invalid-mcp-header-placement.json", "pointer": "/tools/0/inputSchema/allOf/0/properties/region" }, { "outcome": "error", "path": "expected-invalid/duplicate-mcp-header.json", "pointer": "/tools/0/inputSchema/properties/fallbackRegion" } ], "id": "mcp.tool.input-schema.x-mcp-header", "kind": "semantic", "owner": "mcp", "path": "inputSchema properties x-mcp-header", "sources": [ { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/server/tools.mdx#L334-L402" ], "reference": "MCP 2026-07-28 specification, Streamable HTTP transport, x-mcp-header validity and extraction rules", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2026-07-28/schema.ts#L1981-L1997" ], "reference": "MCP 2026-07-28 schema.ts, interface Tool, inputSchema doc comment", "tier": 1 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-tool-x-mcp-header" ], "reference": "MCP Description 0.9.0, Section 9.2" } ], "status": "internal", "summary": "An x-mcp-header annotation is a non-empty HTTP field-name token on a boolean, integer, or string property reachable from the input schema root through properties only, and is unique case-insensitively within the Tool.", "surface": "Tool", "title": "Use valid HTTP header mappings in Tool input" }, { "applicability": { "protocolVersions": { "2024-11-05": "not-applicable", "2025-03-26": "not-applicable", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "not-applicable" } }, "arbitrations": [ { "authority": "MCP specification text on schema dialects, with the object requirement on structured output", "behavior": "Reject a declared root type that excludes \"object\"; accept other roots that are valid under the dialect, which mcp.tool.schema.native-shape reports as warnings.", "conflict": "The specification validates the outputSchema under its declared or default dialect, while schema.ts requires the JSON Schema keyword and value type \"object\" at the root. A root in allOf or $ref can describe an object without matching the TypeScript type.", "protocolVersions": [ "2025-11-25" ], "rationale": "One position for every conflict between MCP's dialect text and the schema syntax of its TypeScript types (Proposal 0032): MCP Description enforces what MCP requires of the data and reports, but does not decide, the narrower TypeScript syntax.", "reviewTrigger": "Resolution of MCP issue 3238 or an MCP erratum for 2025-11-25.", "status": "active", "upstream": "https://github.com/modelcontextprotocol/modelcontextprotocol/issues/3238" } ], "description": "MCP 2025-06-18 and 2025-11-25 require structured output to be an object. For MCP 2025-06-18 the outputSchema root declares type object. For MCP 2025-11-25 a declared root type must include object; a root without a literal type object stays valid and mcp.tool.schema.native-shape warns. MCP 2026-07-28 permits other roots, so an array schema needs a scope that excludes the object-only versions; projection must not wrap it in an object as a repair.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/non-object-output-schema-before-2026.json", "pointer": "/tools/0/outputSchema" }, { "outcome": "not-applicable", "path": "expected-valid/protocol-coverage-and-tool-schemas.json", "pointer": "/tools/3/outputSchema" }, { "outcome": "passes", "path": "expected-warning/tool-schema-mcp-type-mismatch.json", "pointer": "/tools/3/outputSchema" } ], "gaps": [ { "behavior": "The object-root check also runs where outputSchema is not defined, so a non-object outputSchema reports this error in addition to the protocol-version applicability error.", "protocolVersions": [ "2024-11-05", "2025-03-26" ], "resolution": "not-fixed" } ], "id": "mcp.tool.output-schema.object-root", "kind": "structural", "owner": "mcp", "path": "outputSchema", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-06-18/schema.ts#L947-L955", "validation/mcp-schemas/2025-11-25/schema.ts#L1272-L1284" ], "reference": "MCP 2025-06-18 and 2025-11-25 schema.ts, interface Tool, outputSchema (type \"object\")", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2026-07-28/schema.ts#L1999-L2005" ], "reference": "MCP 2026-07-28 schema.ts, interface Tool, outputSchema (no root type)", "tier": 1 }, { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-11-25/basic/index.mdx#L140-L186" ], "reference": "MCP 2025-11-25 specification, Basic, JSON Schema usage (schemas are validated under their declared or default dialect)", "tier": 1 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-tool-output-schema-object-root" ], "reference": "MCP Description 0.9.0, Section 9.2" } ], "status": "arbitrated", "summary": "Before MCP 2026-07-28, a Tool outputSchema describes an object: a literal type \"object\" for MCP 2025-06-18, and a declared root type that includes \"object\" for MCP 2025-11-25.", "surface": "Tool", "title": "Use object output schemas before MCP 2026" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "not-applicable", "2025-11-25": "not-applicable", "2026-07-28": "not-applicable" } }, "description": "Tool outputSchema is available from MCP 2025-06-18. A Tool whose effective scope includes an earlier protocol version cannot carry it unchanged. Omit it for the earlier version or provide disjoint variants.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/output-schema-before-2025-06-18.json", "pointer": "/tools/0" } ], "id": "mcp.tool.output-schema.protocol-version", "kind": "structural", "owner": "mcp", "path": "outputSchema", "sources": [ { "locations": [ "validation/mcp-schemas/2025-03-26/schema.ts#L781-L810" ], "reference": "MCP 2025-03-26 schema.ts, interface Tool (closed; no outputSchema)", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2025-06-18/schema.ts#L947-L955" ], "reference": "MCP 2025-06-18 schema.ts, interface Tool, outputSchema", "tier": 1 } ], "specification": [ { "locations": [ "sections/04-versioning.md#req-field-protocol-version-availability" ], "reference": "MCP Description 0.9.0, Section 9.1 (Tool Object field table)" } ], "status": "internal", "summary": "A Tool declares outputSchema only for MCP protocol versions whose Tool type defines it.", "surface": "Tool", "title": "Declare output schemas only where MCP defines them" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "arbitrations": [ { "authority": "MCP schema.ts doc comment, consistent with MCP 2026-07-28", "behavior": "Accept and preserve any JSON Schema keyword in these protocol versions.", "conflict": "The TypeScript type of inputSchema (and outputSchema from 2025-06-18) lists only type, properties, required, and from 2025-11-25 $schema, with no index signature, while its doc comment defines the value as a JSON Schema object.", "protocolVersions": [ "2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25" ], "rationale": "A JSON Schema object admits any keyword. MCP 2026-07-28 makes this explicit with an index signature, and rejecting keywords such as $defs or $ref would reject Tools that MCP clients accept.", "reviewTrigger": "An upstream clarification or erratum for the earlier protocol versions.", "status": "active" } ], "description": "Embedded Tool schemas can contain keywords beyond the fields MCP lists. A tool must preserve them through the operations covered by the specification instead of discarding unrecognized keywords. This is a tooling guarantee, so a valid custom keyword does not itself produce a document diagnostic.", "enforcement": "internal", "fixtures": [ { "outcome": "passes", "path": "view-fixtures/view-tool-schema-keywords-2025-11-25.json", "pointer": "/expected" } ], "id": "mcp.tool.schema-keywords.preserve", "kind": "preservation", "owner": "mcp", "path": "inputSchema, outputSchema", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L696-L703", "validation/mcp-schemas/2025-03-26/schema.ts#L797-L804", "validation/mcp-schemas/2025-06-18/schema.ts#L938-L945", "validation/mcp-schemas/2025-11-25/schema.ts#L1257-L1265", "validation/mcp-schemas/2025-06-18/schema.ts#L947-L955", "validation/mcp-schemas/2025-11-25/schema.ts#L1272-L1284" ], "reference": "MCP 2024-11-05 to 2025-11-25 schema.ts, interface Tool, inputSchema and outputSchema doc comments (\"A JSON Schema object\")", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2026-07-28/schema.ts#L1981-L1997", "validation/mcp-schemas/2026-07-28/schema.ts#L1999-L2005" ], "reference": "MCP 2026-07-28 schema.ts, interface Tool, inputSchema and outputSchema (index signature [key: string]: unknown)", "tier": 1 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-tool-schema-vocabulary", "sections/09-tools.md#req-tool-schema-keywords-preserved" ], "reference": "MCP Description 0.9.0, Section 9.2" } ], "status": "arbitrated", "summary": "Tool inputSchema and outputSchema are JSON Schema objects; keywords beyond those MCP lists are permitted and preserved, and acquire MCP semantics only where a protocol version defines them.", "surface": "Tool", "title": "Retain embedded JSON Schema keywords" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "not-applicable", "2026-07-28": "not-applicable" } }, "description": "Early MCP protocol versions define a limited Tool-schema shape without a default embedded dialect. Check the known properties and required-name list without rejecting other keywords using an inferred meta-schema. Incomplete example validation is reported separately.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/malformed-pre-dialect-tool-schema-shape.json", "pointer": "/tools/0/inputSchema" } ], "id": "mcp.tool.schema.legacy-shape", "kind": "structural", "notes": "From MCP 2025-11-25 the embedded dialect governs these keywords (json-schema.tool-schema.valid); mcp.tool.schema.native-shape warns where the MCP 2025-11-25 Tool type is narrower.", "owner": "mcp", "path": "inputSchema, outputSchema", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L696-L703", "validation/mcp-schemas/2025-03-26/schema.ts#L797-L804", "validation/mcp-schemas/2025-06-18/schema.ts#L938-L945", "validation/mcp-schemas/2025-06-18/schema.ts#L947-L955" ], "reference": "MCP 2024-11-05 to 2025-06-18 schema.ts, interface Tool, inputSchema (and outputSchema from 2025-06-18): properties?: { [key: string]: object }, required?: string[]", "tier": 1 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-tool-schema-legacy-shape", "sections/09-tools.md#req-tool-schema-legacy-no-dialect" ], "reference": "MCP Description 0.9.0, Section 9.2" } ], "status": "internal", "summary": "Before MCP 2025-11-25, Tool schema properties is an object of objects and required is an array of strings; other keywords are preserved.", "surface": "Tool", "title": "Check early Tool schemas without inferring a dialect" }, { "applicability": { "protocolVersions": { "2024-11-05": "not-applicable", "2025-03-26": "not-applicable", "2025-06-18": "not-applicable", "2025-11-25": "applies", "2026-07-28": "applies" } }, "arbitrations": [ { "authority": "MCP specification text on schema dialects", "behavior": "Accept the schema, report a warning naming the protocol versions concerned, and let native projection fail its postcondition for them.", "conflict": "MCP validates embedded schemas under their declared or default dialect, JSON Schema 2020-12 by default, which allows boolean subschemas and roots in $ref or allOf. The TypeScript Tool type requires a literal type \"object\" at the inputSchema root, and in MCP 2025-11-25 also at the outputSchema root and an object for each top-level properties value.", "protocolVersions": [ "2025-11-25", "2026-07-28" ], "rationale": "The conflict is internal to MCP, so MCP Description reports it instead of deciding it (Proposal 0032). MCP 2026-07-28 removed the properties restriction, the official SDKs accept boolean property subschemas, and authors can always meet the restriction without changing the meaning of the schema.", "reviewTrigger": "Resolution of MCP issue 3238 or an MCP erratum for 2025-11-25.", "status": "active", "upstream": "https://github.com/modelcontextprotocol/modelcontextprotocol/issues/3238" } ], "description": "From MCP 2025-11-25, an embedded Tool schema is judged by its JSON Schema dialect, but the MCP Tool type still restricts some schema syntax: a literal type object at the inputSchema root, and for MCP 2025-11-25 at the outputSchema root and an object for each top-level properties value. A schema that misses a restriction stays valid and receives a warning naming the protocol versions concerned, because its native projection for them fails. Use {} instead of true, {\"not\": {}} instead of false, add type object beside $ref or allOf, or narrow the Tool's protocolVersions.", "enforcement": "internal", "fixtures": [ { "outcome": "warning", "path": "expected-warning/tool-schema-mcp-type-mismatch.json", "pointer": "/tools/0/inputSchema/properties/enabled" }, { "outcome": "warning", "path": "expected-warning/tool-schema-mcp-type-mismatch.json", "pointer": "/tools/0/inputSchema/properties/debug" }, { "outcome": "warning", "path": "expected-warning/tool-schema-mcp-type-mismatch.json", "pointer": "/tools/1/outputSchema/properties/result" }, { "outcome": "warning", "path": "expected-warning/tool-schema-mcp-type-mismatch.json", "pointer": "/tools/2/inputSchema" }, { "outcome": "warning", "path": "expected-warning/tool-schema-mcp-type-mismatch.json", "pointer": "/tools/3/outputSchema" }, { "outcome": "passes", "path": "expected-valid/tool-schema-mcp-type-shapes.json", "pointer": "/tools/0/inputSchema" }, { "outcome": "passes", "path": "expected-valid/tool-schema-mcp-type-shapes.json", "pointer": "/tools/1/inputSchema" }, { "outcome": "passes", "path": "expected-valid/tool-schema-mcp-type-shapes.json", "pointer": "/tools/2/inputSchema" }, { "outcome": "passes", "path": "expected-valid/tool-schema-mcp-type-shapes.json", "pointer": "/tools/3/inputSchema" } ], "id": "mcp.tool.schema.native-shape", "kind": "structural", "notes": "Only a declared root type is examined; composition is not analyzed to prove that a root admits objects. Nested schemas and keywords other than top-level properties are not restricted by any MCP Tool type.", "owner": "mcp", "path": "inputSchema, outputSchema", "requirement": "should", "sources": [ { "locations": [ "validation/mcp-schemas/2025-11-25/schema.ts#L1257-L1284" ], "reference": "MCP 2025-11-25 schema.ts, interface Tool: inputSchema and outputSchema have type: \"object\" and properties?: { [key: string]: object }", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2026-07-28/schema.ts#L1981-L2005" ], "reference": "MCP 2026-07-28 schema.ts, interface Tool: inputSchema has type: \"object\" and an open index signature; outputSchema has no root type", "tier": 1 }, { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-11-25/basic/index.mdx#L140-L186", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/basic/index.mdx#L251-L297" ], "reference": "MCP 2025-11-25 and 2026-07-28 specification, Basic, JSON Schema usage (schemas are validated under their declared or default dialect)", "tier": 1 }, { "locations": [ "https://github.com/modelcontextprotocol/typescript-sdk/blob/39ae8e6192cf43273aaaf2de4169dfa9f7216e28/packages/core/src/schemas.ts#L1352-L1358" ], "reference": "Official TypeScript SDK, Tool schema: any JSON value under properties, type: z.literal('object') at the inputSchema root", "tier": 5 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-tool-schema-native-shape" ], "reference": "MCP Description 0.9.0, Section 9.2" }, { "locations": [ "proposal-snapshots/0032-dialect-governed-tool-schemas.md" ], "reference": "Proposal 0032, Dialect-governed Tool schemas" } ], "status": "arbitrated", "summary": "A Tool schema that is valid under its dialect but misses a schema-syntax restriction of the MCP Tool type for an applicable protocol version is accepted with a warning.", "surface": "Tool", "title": "Report Tool schemas that MCP Tool types reject" }, { "applicability": { "protocolVersions": { "2024-11-05": "not-applicable", "2025-03-26": "not-applicable", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "A successful Tool example for a Tool with outputSchema must carry the required structuredContent. The schema describes that structured value, not the unstructured content array. Check success and error examples separately before deciding which payload is missing.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/invalid-tool-example-result-semantics.json", "pointer": "/tools/0/examples/missing/result" }, { "outcome": "error", "path": "expected-invalid/invalid-tool-interaction-example-semantics.json", "pointer": "/tools/0/interactionExamples/broken/result" } ], "id": "mcp.tool.structured-content.output-schema", "kind": "semantic", "notes": "Conformance of structuredContent to outputSchema is checked by mcpdesc.tool.example.schema-conformance. Error results are governed by mcpdesc.tool.example.error-result.", "owner": "mcp", "path": "structuredContent", "requirement": "must", "sources": [ { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-06-18/server/tools.mdx#L309-L382", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-11-25/server/tools.mdx#L335-L408", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/server/tools.mdx#L509-L631" ], "reference": "MCP 2025-06-18 to 2026-07-28 specification, Server Features, Tools, Output Schema (\"Servers MUST provide structured results that conform to this schema\")", "tier": 1 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-tool-example-structured-content" ], "reference": "MCP Description 0.9.0, Section 9.3" } ], "status": "internal", "summary": "When a Tool declares outputSchema, a successful result contains structuredContent.", "surface": "CallToolResult", "title": "Supply structured content when an output schema needs it" }, { "applicability": { "protocolVersions": { "2024-11-05": "not-applicable", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Legacy HTTP plus SSE remains representable but is deprecated for later MCP protocol versions. The warning does not by itself invalidate the document. Review whether the server still offers that transport or whether the description should advertise Streamable HTTP instead.", "enforcement": "internal", "fixtures": [ { "outcome": "warning", "path": "expected-warning/legacy-sse-modern-protocol-version.json", "pointer": "/transports/0" } ], "id": "mcp.transport.legacy-sse.deprecated", "kind": "semantic", "owner": "mcp", "requirement": "should", "sources": [ { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-03-26/basic/transports.mdx#L250-L277" ], "reference": "MCP 2025-03-26 specification, Basic, Transports, Backwards Compatibility (deprecated HTTP+SSE transport)", "tier": 1 } ], "specification": [ { "locations": [ "sections/06-transports.md#req-transport-legacy-sse-warning" ], "reference": "MCP Description 0.9.0, Section 6.2" } ], "status": "internal", "summary": "Legacy HTTP+SSE associated with MCP 2025-03-26 or later is reported, because Streamable HTTP replaces it.", "surface": "Transport", "title": "Review deprecated legacy SSE transports" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Streamable HTTP is not defined by the earliest supported MCP protocol version. Scope the transport to versions that define it and keep root protocol coverage consistent. A URL alone does not make a transport applicable to every protocol version.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/protocol-version-inapplicable-streamable-http.json", "pointer": "/transports/0" } ], "id": "mcp.transport.streamable-http.protocol-version", "kind": "structural", "owner": "mcp", "requirement": "must", "sources": [ { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-03-26/basic/transports.mdx#L50-L277" ], "reference": "MCP 2025-03-26 specification, Basic, Transports, Streamable HTTP (replaces HTTP+SSE from 2024-11-05)", "tier": 1 } ], "specification": [ { "locations": [ "sections/06-transports.md#req-transport-streamable-http-protocol-versions" ], "reference": "MCP Description 0.9.0, Section 6.2" } ], "status": "internal", "summary": "Streamable HTTP is used only from MCP 2025-03-26.", "surface": "Transport", "title": "Use Streamable HTTP only where supported" }, { "applicability": { "protocolVersions": "independent" }, "description": "A completion example must target a Prompt argument or Resource Template variable that exists. Context entries must name other declared targets, not repeat the argument being completed. Correct the example names or the declaration they describe.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/invalid-completion-example-semantics.json", "pointer": "/prompts/2/completionExamples/bad-membership/argument" }, { "outcome": "passes", "path": "expected-valid/named-completion-examples.json", "pointer": "/prompts/0/completionExamples" } ], "id": "mcpdesc.completion-example.target", "kind": "mcpdesc-semantic", "owner": "mcpdesc", "path": "argument, context", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-06-18/schema.ts#L1307-L1340", "validation/mcp-schemas/2025-11-25/schema.ts#L1995-L2025", "validation/mcp-schemas/2026-07-28/schema.ts#L2582-L2618" ], "reference": "MCP 2025-06-18 to 2026-07-28 schema.ts, CompleteRequest context.arguments (previously-resolved variables in a URI template or prompt)", "tier": 1 } ], "specification": [ { "locations": [ "sections/10-resources.md#req-template-completion-target", "sections/11-prompts.md#req-prompt-completion-target" ], "reference": "MCP Description 0.9.0, Sections 10.4.6 and 11.4" } ], "status": "internal", "summary": "A completion example completes a declared Prompt argument or URI template variable, and its context names other declared arguments or variables only.", "surface": "Completion example", "title": "Complete a declared argument or template variable" }, { "applicability": { "protocolVersions": "independent" }, "description": "The components object holds non-empty named maps in its five namespaces. A Reference Object has exactly one $componentRef. Where a value may be inline or a reference, the inline form is a JSON object without $componentRef.", "documentSchema": [ "#/$defs/components", "#/$defs/componentMap", "#/$defs/referenceObject", "#/$defs/schemaComponentValue", "#/$defs/jsonSchemaObject" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/components-empty-and-reference-shapes.json", "pointer": "/components/schemas" } ], "id": "mcpdesc.components.members", "kind": "structural", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/17-components.md#req-components-fields", "sections/17-components.md#req-reference-object-fields", "sections/14-specification-extensions.md#req-extension-ineligible-locations", "sections/14-specification-extensions.md#req-extension-component-names", "sections/17-components.md#req-component-maps", "sections/17-components.md#req-components-closed" ], "reference": "MCP Description 0.9.0, Sections 17.1 and 17.2" } ], "status": "internal", "summary": "Components contain non-empty, well-named maps; a Reference Object has only $componentRef; an inline schema or example is an object.", "surface": "Components, Reference Object", "title": "Shape components and Reference Objects" }, { "applicability": { "protocolVersions": "independent" }, "description": "A component reference must identify an existing value in the namespace required by its use site, without a reference cycle. Check both the target name and the namespace. Reuse does not exempt the resolved value from validation in its containing declaration.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/component-reference-resolution.json", "pointer": "/components/schemas" } ], "id": "mcpdesc.components.references", "kind": "mcpdesc-semantic", "owner": "mcpdesc", "path": "$componentRef", "requirement": "must", "specification": [ { "locations": [ "sections/17-components.md#req-component-reference-form", "sections/17-components.md#req-component-reference-resolution", "sections/09-tools.md#req-tool-schema-references-resolved", "sections/09-tools.md#req-tool-example-references-resolved", "sections/12-elicitation.md#req-elicitation-schema-references-resolved", "sections/10-resources.md#req-resource-example-references-resolved", "sections/11-prompts.md#req-prompt-example-references-resolved", "sections/17-components.md#req-component-ref-distinct", "sections/17-components.md#req-component-contextual-validation", "sections/17-components.md#req-component-reference-pointer", "sections/17-components.md#req-component-resolution-errors", "sections/17-components.md#req-component-cycles" ], "reference": "MCP Description 0.9.0, Sections 17.2 to 17.4" } ], "status": "internal", "summary": "A Reference Object targets an existing component in the namespace its use site requires, without cycles.", "surface": "Reference Object", "title": "Resolve component references in the right namespace" }, { "applicability": { "protocolVersions": "independent" }, "description": "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.", "documentSchema": [ "#", "#/$defs/jsonValue", "#/$defs/specificationExtensionValue" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/empty-ordinary-root-collections.json", "pointer": "/capabilities" }, { "outcome": "error", "path": "expected-invalid/empty-tag-catalog-reference.json", "pointer": "/tags" }, { "outcome": "passes", "path": "expected-valid/optional-schema-omitted.json", "pointer": "" } ], "id": "mcpdesc.document.schema", "kind": "structural", "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.", "owner": "mcpdesc", "specification": [ { "locations": [ "sections/16-conformance.md#req-document-schema", "sections/03-document-structure.md#req-root-fields", "sections/03-document-structure.md#req-closed-objects", "sections/09-tools.md#req-tool-input-schema-required", "sections/03-document-structure.md#req-ordinary-collections-non-empty", "sections/03-document-structure.md#req-ordinary-collections-omitted", "sections/04-versioning.md#req-mcpdesc-required", "sections/04-versioning.md#req-mcpdesc-version", "sections/04-versioning.md#req-version-check", "sections/05-info-object.md#req-info-required", "sections/06-transports.md#req-transports-non-empty", "sections/08-capabilities.md#req-capabilities-non-empty", "sections/13-tags.md#req-tags-non-empty", "sections/13-tags.md#req-tags-omitted", "sections/16-conformance.md#req-conforming-document", "sections/14-specification-extensions.md#req-extension-names", "sections/14-specification-extensions.md#req-extension-unknown-accepted", "sections/15-serialization.md#req-serialization-empty-collections" ], "reference": "MCP Description 0.9.0, Section 16.1, item 7" } ], "status": "internal", "summary": "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.", "surface": "Document", "title": "Match the MCP Description document schema" }, { "applicability": { "protocolVersions": "independent" }, "description": "Form properties, required names, enum labels, defaults, and bounds must agree with one another. Correct references to absent properties and contradictory constraints. Passing JSON Schema's outer shape checks does not prove that the declared form is internally consistent.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/elicitation-form-semantics.json", "pointer": "/prompts/0/elicitations/0/requestedSchema/required" }, { "outcome": "error", "path": "expected-invalid/elicitation-form-invalid-range.json", "pointer": "/prompts/0/elicitations/0/requestedSchema/properties/count" }, { "outcome": "passes", "path": "expected-valid/elicitation-declarations.json", "pointer": "/tools/0/elicitations" } ], "id": "mcpdesc.elicitation.form-schema.consistency", "kind": "mcpdesc-semantic", "owner": "mcpdesc", "path": "requestedSchema", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-06-18/schema.ts#L1479-L1486", "validation/mcp-schemas/2025-11-25/schema.ts#L2228-L2235", "validation/mcp-schemas/2026-07-28/schema.ts#L2861-L2868", "validation/mcp-schemas/2025-06-18/schema.ts#L1527-L1536", "validation/mcp-schemas/2025-11-25/schema.ts#L2463-L2464", "validation/mcp-schemas/2026-07-28/schema.ts#L3117-L3118" ], "reference": "MCP 2025-06-18 to 2026-07-28 schema.ts, PrimitiveSchemaDefinition and EnumSchema (enumNames are display names for enum values)", "tier": 1 } ], "specification": [ { "locations": [ "sections/12-elicitation.md#req-elicitation-form-required", "sections/12-elicitation.md#req-elicitation-form-enum-names", "sections/12-elicitation.md#req-elicitation-form-defaults", "sections/12-elicitation.md#req-elicitation-form-ranges" ], "reference": "MCP Description 0.9.0, Section 12.3" } ], "status": "internal", "summary": "A form requestedSchema is internally consistent: required names declared properties, enumNames match enum values, defaults lie within enums, and minimum bounds do not exceed maximum bounds.", "surface": "Elicitation Declaration", "title": "Keep elicitation form constraints consistent" }, { "applicability": { "protocolVersions": "independent" }, "description": "An elicitation declaration has a name, a mode, and a message. Form mode requires requestedSchema and forbids url; URL mode requires url and forbids requestedSchema. Unknown properties are rejected.", "documentSchema": [ "#/$defs/elicitationDeclaration" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/elicitation-branch-mixing.json", "pointer": "/resources/0/elicitations/0" }, { "outcome": "error", "path": "expected-invalid/discriminated-union-members.json", "pointer": "/tools/0/elicitations/0" } ], "id": "mcpdesc.elicitation.members", "kind": "structural", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/12-elicitation.md#req-elicitation-declaration-fields", "sections/12-elicitation.md#req-elicitation-name-format", "sections/12-elicitation.md#req-elicitation-message", "sections/12-elicitation.md#req-elicitation-documentation-fields", "sections/12-elicitation.md#req-elicitation-form-schema-required", "sections/12-elicitation.md#req-elicitation-form-no-url", "sections/12-elicitation.md#req-elicitation-url-no-schema", "sections/12-elicitation.md#req-elicitation-url-syntax" ], "reference": "MCP Description 0.9.0, Section 12.2" } ], "status": "internal", "summary": "An Elicitation Declaration has its required fields, the fields of its mode only, and no unknown properties.", "surface": "Elicitation Declaration", "title": "Declare elicitations with their mode fields" }, { "applicability": { "protocolVersions": "independent" }, "description": "Elicitation declaration names identify interactions within their primitive. Duplicate names make a Tool interaction's declaration reference ambiguous. Rename one declaration and update the references that are intended to select it.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/elicitation-form-semantics.json", "pointer": "/prompts/0/elicitations/1" } ], "id": "mcpdesc.elicitation.name-unique", "kind": "mcpdesc-semantic", "owner": "mcpdesc", "path": "name", "requirement": "must", "specification": [ { "locations": [ "sections/12-elicitation.md#req-elicitation-name-unique" ], "reference": "MCP Description 0.9.0, Section 12.2" } ], "status": "internal", "summary": "Elicitation Declaration names are unique within their primitive.", "surface": "Elicitation Declaration", "title": "Give each elicitation declaration a unique name" }, { "applicability": { "protocolVersions": "independent" }, "description": "An example result is the completed payload, not a JSON-RPC response or a pending workflow. Remove envelope fields such as jsonrpc and id and do not include task or input-required state. Multi-step interactions belong in the explicit interaction example structure.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/invalid-tool-example-result-semantics.json", "pointer": "/tools/3/examples/task-result/result" }, { "outcome": "error", "path": "expected-invalid/invalid-prompt-example-semantics.json", "pointer": "/prompts/3/examples/task-state/result" }, { "outcome": "error", "path": "expected-invalid/resource-example-result-semantics.json", "pointer": "/resources/0/examples/invalid-result/result" }, { "outcome": "error", "path": "expected-invalid/invalid-completion-example-semantics.json", "pointer": "/prompts/2/completionExamples/bad-membership/result" } ], "id": "mcpdesc.example.completed-result-form", "kind": "mcpdesc-semantic", "notes": "Envelope fields are jsonrpc, id, and error. Non-completed workflow fields are task, inputRequests, and requestState. They are excluded from the field classification of mcp.result.additional-properties.preserve.", "owner": "mcpdesc", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2026-07-28/schema.ts#L571-L595", "validation/mcp-schemas/2026-07-28/schema.ts#L218-L236" ], "reference": "MCP 2026-07-28 schema.ts, InputRequiredResult (inputRequests, requestState) and Result.resultType", "tier": 1 }, { "locations": [ "validation/mcp-schemas/2025-11-25/schema.ts#L1386-L1393" ], "reference": "MCP 2025-11-25 schema.ts, CreateTaskResult (task)", "tier": 1 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-tool-example-completed-form", "sections/10-resources.md#req-resource-example-completed-form", "sections/11-prompts.md#req-prompt-example-completed-form", "sections/09-tools.md#req-tool-example-not-interaction" ], "reference": "MCP Description 0.9.0, Sections 3.6, 9.3, 10.4.4, 10.4.6, 11.3, and 11.4" } ], "status": "internal", "summary": "An example result is a completed result payload: it contains no JSON-RPC envelope field and no non-completed workflow field.", "surface": "Example result", "title": "Show completed results without message envelopes" }, { "applicability": { "protocolVersions": "independent" }, "description": "Named example maps are non-empty, use names matching ^[A-Za-z0-9._-]+$, and hold an example object or a Reference Object. Each example object has its required members, such as input and result, and only its defined properties.", "documentSchema": [ "#/$defs/toolExamples", "#/$defs/toolExample", "#/$defs/resourceExamples", "#/$defs/resourceExample", "#/$defs/resourceTemplateExamples", "#/$defs/resourceTemplateExample", "#/$defs/promptExamples", "#/$defs/promptExample", "#/$defs/completionExamples", "#/$defs/completionExample", "#/$defs/completionArgument", "#/$defs/completionContext" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/component-extension-boundaries.json", "pointer": "/components/toolExamples/x-map-extension" } ], "id": "mcpdesc.example.members", "kind": "structural", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/09-tools.md#req-tool-example-fields", "sections/10-resources.md#req-resource-example-fields", "sections/10-resources.md#req-resource-template-example-fields", "sections/11-prompts.md#req-prompt-example-fields", "sections/09-tools.md#req-tool-examples-map", "sections/09-tools.md#req-tool-example-closed", "sections/10-resources.md#req-resource-examples-map", "sections/10-resources.md#req-resource-example-closed", "sections/10-resources.md#req-template-completion-examples-map", "sections/10-resources.md#req-template-completion-example-closed", "sections/10-resources.md#req-template-completion-context-shape", "sections/11-prompts.md#req-prompt-examples-map", "sections/11-prompts.md#req-prompt-example-closed", "sections/11-prompts.md#req-prompt-example-arguments-shape", "sections/11-prompts.md#req-prompt-completion-examples-map", "sections/11-prompts.md#req-prompt-completion-example-closed", "sections/11-prompts.md#req-prompt-completion-context-shape" ], "reference": "MCP Description 0.9.0, Sections 9.3, 10.4, and 11.3" } ], "status": "internal", "summary": "Example maps and Tool, Resource, Resource Template, Prompt, and completion example objects have valid names, required members, and no unknown properties.", "surface": "Tool, Resource, Resource Template, Prompt, and completion examples", "title": "Shape named example maps and example objects" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "A completed example result must contain the fields each applicable MCP protocol version requires, with valid values. Check the result's full effective scope, not only the newest version. Fields permitted but undefined on open result types are handled separately as warnings.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/invalid-prompt-example-semantics.json", "pointer": "/prompts/0/examples/unknown-and-missing/result" }, { "outcome": "error", "path": "expected-invalid/invalid-completion-example-semantics.json", "pointer": "/prompts/3/completionExamples/missing-result-type/result" }, { "outcome": "passes", "path": "expected-valid/named-tool-examples.json", "pointer": "/tools/0/examples" }, { "outcome": "passes", "path": "expected-valid/named-resource-examples.json", "pointer": "/resources/0/examples" }, { "outcome": "passes", "path": "expected-warning/legacy-result-meta.json", "pointer": "/resources/0/examples/with-result-meta/result" }, { "outcome": "passes", "path": "expected-warning/open-results-shared-across-protocol-versions.json", "pointer": "/tools/0/examples/paris/result" } ], "id": "mcpdesc.example.result.protocol-fidelity", "kind": "mcpdesc-semantic", "notes": "Fields an MCP protocol version does not define are governed by mcp.result.additional-properties.preserve (accepted with a warning). When present, resultType must be \"complete\", ttlMs non-negative, and cacheScope \"public\" or \"private\" in every applicable protocol version (document schema).", "owner": "mcpdesc", "sources": [ { "locations": [ "validation/mcp-schemas/2026-07-28/schema.ts#L218-L236", "validation/mcp-schemas/2026-07-28/schema.ts#L1076-L1110" ], "reference": "MCP 2026-07-28 schema.ts, interface Result (resultType required) and interface CacheableResult (ttlMs, cacheScope required)", "tier": 1 } ], "specification": [ { "locations": [ "sections/03-document-structure.md#req-carried-defined-fields", "sections/09-tools.md#req-tool-example-result-shape", "sections/10-resources.md#req-resource-example-result-shape", "sections/11-prompts.md#req-prompt-example-result-shape" ], "reference": "MCP Description 0.9.0, Sections 9.3, 10.4.4, 10.4.6, 11.3, and 11.4" }, { "locations": [ "validation/README.md#examples-fail-fast" ], "reference": "Examples fail fast decision (validation README, 2026-10-25, issue #72)" } ], "status": "internal", "summary": "An example result contains every field that each applicable MCP protocol version requires, and every field a protocol version defines has a valid value.", "surface": "Example result", "title": "Match example results to every applicable version" }, { "applicability": { "protocolVersions": "independent" }, "description": "Extension identifiers in an MCP-reserved namespace are checked against the pinned catalogue. Unknown or experimental identifiers are preserved with a warning. Verify the identifier and its maturity; an unrecognized identifier is not silently assigned known extension semantics.", "enforcement": "internal", "fixtures": [ { "outcome": "warning", "path": "expected-warning/unknown-reserved-extension-identifier.json", "pointer": "/capabilities/0/extensions" }, { "outcome": "warning", "path": "expected-warning/deprecated-client-capability-requirements.json", "pointer": "/prompts/0/clientRequirements/extensions" } ], "id": "mcpdesc.extensions.catalogue-maturity", "kind": "mcpdesc-semantic", "notes": "The pinned catalogue lists no experimental identifiers, so no document currently produces the experimental-identifier warning.", "owner": "mcpdesc", "path": "capabilities.extensions, clientRequirements.extensions", "requirement": "should", "sources": [ { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/basic/index.mdx#L337-L339" ], "reference": "MCP 2026-07-28 specification, Basic, General fields, _meta key name format (second label modelcontextprotocol or mcp is reserved)", "tier": 1 } ], "specification": [ { "locations": [ "sections/08-capabilities.md#req-extensions-reserved-identifiers", "sections/08-capabilities.md#req-extensions-catalogue-maturity", "sections/08-capabilities.md#req-extensions-official-no-warning" ], "reference": "MCP Description 0.9.0, Sections 8.4 and 8.5; validator extension catalogue (effective 2026-09-04)" } ], "status": "internal", "summary": "An extension identifier under an MCP-reserved prefix that the pinned extension catalogue lists as experimental, or does not list, is preserved with a warning.", "surface": "Extension identifier", "title": "Review reserved extension identifiers" }, { "applicability": { "protocolVersions": "independent" }, "description": "The required info object names and versions the server. Its contact and license objects are closed and follow the property tables of Section 5.", "documentSchema": [ "#/$defs/info", "#/$defs/contact", "#/$defs/license" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/malformed-info-transport-tag-resource.json", "pointer": "/info/owner" } ], "id": "mcpdesc.info.members", "kind": "structural", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/05-info-object.md#req-info-fields", "sections/05-info-object.md#req-contact-fields", "sections/05-info-object.md#req-license-fields", "sections/04-versioning.md#req-info-unscoped", "sections/05-info-object.md#req-info-protocol-version-independent", "sections/05-info-object.md#req-info-name-non-empty", "sections/05-info-object.md#req-info-version-non-empty", "sections/15-serialization.md#req-serialization-value-formats" ], "reference": "MCP Description 0.9.0, Section 5" } ], "status": "internal", "summary": "Info has a non-empty name and version, and Info, Contact, and License contain only their defined properties with the defined types.", "surface": "Info, Contact, License", "title": "Describe the server in a valid Info Object" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "not-applicable", "2025-11-25": "not-applicable", "2026-07-28": "not-applicable" } }, "description": "MCP 2024-11-05 and 2025-03-26 receive structural and selected checks, not a claim of complete MCP semantic conformance. The warning describes a validation limitation rather than an invalid document. Adding a later protocol version does not make checks for the earlier versions complete.", "enforcement": "internal", "fixtures": [ { "outcome": "warning", "path": "expected-warning/legacy-result-meta.json", "pointer": "/protocolVersions" } ], "id": "mcpdesc.legacy-protocol.validation-scope", "kind": "mcpdesc-semantic", "owner": "mcpdesc", "path": "protocolVersions", "requirement": "must", "specification": [ { "locations": [ "sections/16-conformance.md#req-legacy-validation-scope", "proposal-snapshots/0024-validation-rule-identity-and-provenance.md", "sections/12-elicitation.md#req-elicitation-legacy-incomplete" ], "reference": "MCP Description 0.9.0, Sections 3.5 and 16.2; Proposal 0024, Section 4.1" } ], "status": "internal", "summary": "A document applying to MCP 2024-11-05 or 2025-03-26 is reported as receiving structural and selected checks only, not complete MCP semantic conformance.", "surface": "Document", "title": "Limited validation for early MCP protocol versions" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Native projection selects a Tool, Resource, Resource Template, or Prompt by its identifier in one protocol view. A declaration outside that view cannot be projected for that version. Check the identifier and the declaration's inherited or explicit scope.", "enforcement": "external", "fixtures": [ { "outcome": "error", "path": "projection-fixtures/tool-not-applicable-2024-11-05.json", "pointer": "/expectedError" }, { "outcome": "error", "path": "projection-fixtures/resource-template-not-applicable-2025-03-26.json", "pointer": "/expectedError" } ], "id": "mcpdesc.projection.declaration-applicable", "kind": "mcpdesc-semantic", "notes": "Implemented by @mcpdesc/core; this repository checks the fixtures with scripts/test-projection-fixtures.mjs.", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/04-versioning.md#req-native-projection-declaration-applicable" ], "reference": "MCP Description 0.9.0, Section 4.14, step 3" } ], "status": "delegated", "summary": "Native projection selects one declaration of the requested kind and identifier in the Effective Protocol View for the protocol version.", "surface": "Native projection", "title": "Select an applicable declaration for projection" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Native projection resolves Tool schema components, removes description-only fields, and checks the value against the selected MCP schema. It does not repair values or invent defaults. A postcondition failure returns no projected value. It is an implementation or specification defect, unless validation warned about the Tool schema under mcp.tool.schema.native-shape for that protocol version.", "enforcement": "external", "fixtures": [ { "outcome": "passes", "path": "projection-fixtures/tool-icons-execution-component-2025-11-25.json", "pointer": "/expected" }, { "outcome": "passes", "path": "projection-fixtures/tool-component-input-array-output-2026-07-28.json", "pointer": "/expected" }, { "outcome": "passes", "path": "projection-fixtures/prompt-arguments-2024-11-05.json", "pointer": "/expected/arguments" }, { "outcome": "passes", "path": "projection-fixtures/tools-list-2025-11-25.json", "pointer": "/expected" }, { "outcome": "passes", "path": "projection-fixtures/tool-boolean-property-schema-2026-07-28.json", "pointer": "/expected/inputSchema/properties" }, { "outcome": "error", "path": "projection-fixtures/tool-postcondition-failed-2025-11-25.json", "pointer": "/expectedError" }, { "outcome": "error", "path": "projection-fixtures/tools-list-postcondition-failed-2025-11-25.json", "pointer": "/expectedError" }, { "outcome": "error", "path": "projection-fixtures/tool-ref-root-postcondition-failed-2025-11-25.json", "pointer": "/expectedError" }, { "outcome": "error", "path": "projection-fixtures/tool-ref-root-postcondition-failed-2026-07-28.json", "pointer": "/expectedError" } ], "id": "mcpdesc.projection.native-schema", "kind": "mcpdesc-semantic", "notes": "The postcondition cases come from Tool schemas that are valid under their JSON Schema dialect but miss a schema-syntax restriction of the MCP Tool type (Proposal 0032), not from an injected fault: the source is valid with a warning, yet the native value fails the pinned MCP schema. A list fails as a whole. scripts/test-projection-fixtures.mjs checks that each failure case's value really fails that schema and that every expected value passes it.", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/04-versioning.md#req-native-projection-references-resolved", "sections/04-versioning.md#req-native-projection-fields", "sections/04-versioning.md#req-native-projection-postcondition", "sections/04-versioning.md#req-native-projection-no-synthesis", "sections/04-versioning.md#req-native-projection-lists", "sections/09-tools.md#req-tool-example-projection-omitted", "sections/09-tools.md#req-interaction-projection-omitted", "sections/04-versioning.md#req-native-projection-steps", "sections/04-versioning.md#req-native-projection-no-repair", "sections/10-resources.md#req-resource-example-projection-omitted", "sections/10-resources.md#req-template-completion-projection-omitted", "sections/11-prompts.md#req-prompt-example-projection-omitted", "sections/11-prompts.md#req-prompt-completion-projection-omitted" ], "reference": "MCP Description 0.9.0, Section 4.14, steps 4 to 6, no synthesis, and lists" } ], "status": "delegated", "summary": "A native projection keeps exactly the declaration fields that the MCP type defines in the protocol version, unchanged after reference resolution, and the value validates against the pinned MCP schema for that protocol version.", "surface": "Tool, Resource, ResourceTemplate, Prompt", "title": "Preserve MCP values when projecting declarations" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Native projection first validates the source and checks that the requested MCP protocol version appears at the root. Fix source errors or select a declared version. These failures come from the projection operation, not a new document-validation phase.", "enforcement": "external", "fixtures": [ { "outcome": "error", "path": "projection-fixtures/tool-source-invalid.json", "pointer": "/expectedError" }, { "outcome": "error", "path": "projection-fixtures/tool-protocol-version-not-declared.json", "pointer": "/expectedError" }, { "outcome": "error", "path": "projection-fixtures/prompt-protocol-version-not-declared.json", "pointer": "/expectedError" } ], "id": "mcpdesc.projection.source-valid", "kind": "mcpdesc-semantic", "notes": "Implemented by @mcpdesc/core; this repository checks the fixtures with scripts/test-projection-fixtures.mjs.", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/04-versioning.md#req-native-projection-source-valid", "sections/04-versioning.md#req-native-projection-protocol-version-declared" ], "reference": "MCP Description 0.9.0, Section 4.14, steps 1 and 2" } ], "status": "delegated", "summary": "Native projection starts from a document without validation errors and from a protocol version in its root protocolVersions.", "surface": "Native projection", "title": "Project a valid source and declared protocol version" }, { "applicability": { "protocolVersions": "independent" }, "description": "A Prompt example supplies every required argument and no undeclared argument. Check names against the containing Prompt, including when the example comes from a reusable component. Omitted optional arguments do not need placeholder values.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/invalid-prompt-example-semantics.json", "pointer": "/prompts/0/examples/unknown-and-missing/arguments" }, { "outcome": "error", "path": "expected-invalid/component-contextual-examples.json", "pointer": "/components/promptExamples/bad-arguments" }, { "outcome": "passes", "path": "expected-valid/named-prompt-examples.json", "pointer": "/prompts/2" } ], "id": "mcpdesc.prompt.example.arguments", "kind": "mcpdesc-semantic", "owner": "mcpdesc", "path": "arguments", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2024-11-05/schema.ts#L588-L591", "validation/mcp-schemas/2025-03-26/schema.ts#L626-L629", "validation/mcp-schemas/2025-06-18/schema.ts#L727-L730", "validation/mcp-schemas/2025-11-25/schema.ts#L1011-L1014", "validation/mcp-schemas/2026-07-28/schema.ts#L1683-L1686" ], "reference": "MCP 2024-11-05 to 2026-07-28 schema.ts, interface PromptArgument, required (\"Whether this argument must be provided\")", "tier": 1 } ], "specification": [ { "locations": [ "sections/11-prompts.md#req-prompt-example-arguments" ], "reference": "MCP Description 0.9.0, Section 11.3" } ], "status": "internal", "summary": "A Prompt example supplies every required Prompt argument and no undeclared argument.", "surface": "Prompt example", "title": "Supply the Prompt arguments the example requires" }, { "applicability": { "protocolVersions": "independent" }, "description": "A Prompt has a name, and each argument has a name. Both accept only the properties of their Section 11 tables, each with its defined type.", "documentSchema": [ "#/$defs/prompt", "#/$defs/promptArgument" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/empty-ordinary-nested-collections.json", "pointer": "/prompts/0/arguments" } ], "id": "mcpdesc.prompt.members", "kind": "structural", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/11-prompts.md#req-prompt-fields", "sections/11-prompts.md#req-prompt-argument-fields", "sections/13-tags.md#req-entity-tags-shape", "sections/13-tags.md#req-entity-tags-unique" ], "reference": "MCP Description 0.9.0, Sections 11.1 and 11.2" } ], "status": "internal", "summary": "Prompt and Prompt Argument Objects have their required fields, defined property types, and no unknown properties.", "surface": "Prompt, PromptArgument", "title": "Declare Prompts and arguments with their fields" }, { "applicability": { "protocolVersions": "independent" }, "description": "An omitted scope inherits its parent's full scope; an explicit child scope must stay within it. Declarations with the same identity cannot overlap where the specification requires uniqueness. Narrow the scopes rather than expecting the validator to choose one variant.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/elicitation-scope-outside-parent.json", "pointer": "/resourceTemplates/0/elicitations/0" }, { "outcome": "error", "path": "expected-invalid/scoped-version-not-in-root.json", "pointer": "/transports/0" }, { "outcome": "error", "path": "expected-invalid/overlapping-tool-scope.json", "pointer": "/tools/1" }, { "outcome": "error", "path": "expected-invalid/overlapping-capabilities.json", "pointer": "/capabilities/0" } ], "id": "mcpdesc.protocol-scope.consistency", "kind": "mcpdesc-semantic", "owner": "mcpdesc", "path": "protocolVersions", "requirement": "must", "specification": [ { "locations": [ "sections/04-versioning.md#req-scope-subset", "sections/08-capabilities.md#req-capability-scopes-disjoint", "sections/09-tools.md#req-tool-names-disjoint", "sections/12-elicitation.md#req-elicitation-scope", "sections/04-versioning.md#req-scope-root-subset", "sections/10-resources.md#req-resource-scopes-disjoint", "sections/11-prompts.md#req-prompt-scopes-disjoint", "sections/11-prompts.md#req-prompt-variants-disjoint" ], "reference": "MCP Description 0.9.0, Sections 4.10 and 8.6" } ], "status": "internal", "summary": "Nested protocol scopes stay within their parent scope, and same-named primitives and capability objects do not overlap in protocol scope.", "surface": "Document", "title": "Keep protocol scopes consistent and disjoint" }, { "applicability": { "protocolVersions": "independent" }, "description": "Root and declaration protocolVersions arrays are non-empty, contain no duplicates, and name only MCP protocol versions this specification supports.", "documentSchema": [ "#/$defs/protocolVersionScope", "#/$defs/supportedProtocolVersion" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/closed-protocol-enum.json", "pointer": "/protocolVersions/0" } ], "id": "mcpdesc.protocol-versions.values", "kind": "structural", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/04-versioning.md#req-protocol-versions-values" ], "reference": "MCP Description 0.9.0, Section 4" } ], "status": "internal", "summary": "A protocolVersions array is non-empty, has unique values, and contains only supported MCP protocol-version identifiers.", "surface": "Document, scoped declarations", "title": "List supported MCP protocol versions in protocol scopes" }, { "applicability": { "protocolVersions": "independent" }, "description": "A Resource Template example records the concrete requested URI, which must be an RFC 6570 expansion of the containing template. Check the template and URI together, including examples reached through components. Matching a URI does not require network retrieval.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/resource-example-result-semantics.json", "pointer": "/resourceTemplates/0/examples/not-an-expansion" }, { "outcome": "error", "path": "expected-invalid/component-contextual-examples.json", "pointer": "/components/resourceTemplateExamples/bad-uri" }, { "outcome": "passes", "path": "expected-valid/named-resource-examples.json", "pointer": "/resourceTemplates/0" } ], "id": "mcpdesc.resource-template.example.expansion", "kind": "mcpdesc-semantic", "owner": "mcpdesc", "path": "uri", "requirement": "must", "sources": [ { "locations": [ "https://www.rfc-editor.org/rfc/rfc6570#section-3" ], "reference": "RFC 6570, URI Template", "tier": 2 } ], "specification": [ { "locations": [ "sections/10-resources.md#req-resource-template-example-expansion" ], "reference": "MCP Description 0.9.0, Section 10.4.3" } ], "status": "internal", "summary": "A Resource Template example uri is a valid RFC 6570 expansion of the template.", "surface": "Resource Template example", "title": "Use a concrete URI that expands the template" }, { "applicability": { "protocolVersions": "independent" }, "description": "Resource example contents are compared with the declaration's requested URI, MIME type, and declared raw size. A mutable resource can differ between observations, so size differences are warnings. Review the example and declaration together rather than inferring live content.", "enforcement": "internal", "fixtures": [ { "outcome": "warning", "path": "expected-warning/resource-example-consistency.json", "pointer": "/resources/0/examples/collection-snapshot/result" } ], "id": "mcpdesc.resource.example.consistency", "kind": "mcpdesc-semantic", "notes": "Collections and indirect reads may legitimately differ, so these are warnings.", "owner": "mcpdesc", "path": "result.contents", "requirement": "should", "specification": [ { "locations": [ "sections/10-resources.md#req-resource-example-requested-uri", "sections/10-resources.md#req-resource-example-mime-type", "sections/10-resources.md#req-resource-example-size" ], "reference": "MCP Description 0.9.0, Section 10.4.4" } ], "status": "internal", "summary": "Resource example contents agree with their declaration: the requested URI is returned, MIME types match, and raw size matches a declared size.", "surface": "Resource example", "title": "Keep Resource examples consistent with declarations" }, { "applicability": { "protocolVersions": "independent" }, "description": "A Resource has a uri and a name; a Resource Template has a uriTemplate and a name. Both accept only the properties of their Section 10 tables, each with its defined type.", "documentSchema": [ "#/$defs/resource", "#/$defs/resourceTemplate" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/malformed-info-transport-tag-resource.json", "pointer": "/resources/0" } ], "id": "mcpdesc.resource.members", "kind": "structural", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/10-resources.md#req-resource-fields", "sections/10-resources.md#req-resource-template-fields", "sections/13-tags.md#req-entity-tags-shape", "sections/13-tags.md#req-entity-tags-unique" ], "reference": "MCP Description 0.9.0, Sections 10.1.1 and 10.2.1" } ], "status": "internal", "summary": "Resource and Resource Template Objects have their required fields, defined property types, and no unknown properties.", "surface": "Resource, ResourceTemplate", "title": "Declare Resources and templates with their fields" }, { "applicability": { "protocolVersions": "independent" }, "description": "Named security schemes are non-empty and each scheme has a type and the fields that type requires, such as OAuth flows with their URLs and scopes. Unknown properties are rejected.", "documentSchema": [ "#/$defs/securitySchemeMap", "#/$defs/securityScheme", "#/$defs/oauthFlows", "#/$defs/oauthFlow" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/empty-ordinary-root-collections.json", "pointer": "/securitySchemes" }, { "outcome": "error", "path": "expected-invalid/invalid-security-scheme-name.json", "pointer": "/securitySchemes" }, { "outcome": "error", "path": "expected-invalid/discriminated-union-members.json", "pointer": "/securitySchemes/token" } ], "id": "mcpdesc.security-scheme.members", "kind": "structural", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/07-security.md#req-security-scheme-fields", "sections/07-security.md#req-security-schemes-map", "sections/07-security.md#req-oauth-flows-fields", "sections/15-serialization.md#req-serialization-value-formats" ], "reference": "MCP Description 0.9.0, Sections 7.1 and 7.2" } ], "status": "internal", "summary": "securitySchemes is a non-empty map of Security Scheme Objects that contain their type-specific required fields and only defined properties.", "surface": "Security Scheme", "title": "Define security schemes with their required fields" }, { "applicability": { "protocolVersions": "independent" }, "description": "Security requirements refer to named schemes, and scopes have meaning only for OAuth 2.0 or OpenID Connect schemes. Correct missing references or repeated scopes. An uncatalogued scope can produce a warning where the scheme declares a static scope catalogue.", "documentSchema": [ "#/$defs/securityRequirementArray", "#/$defs/securityRequirement" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/unknown-security-reference.json", "pointer": "/security/0" }, { "outcome": "error", "path": "expected-invalid/non-oauth-scopes.json", "pointer": "/security/0" }, { "outcome": "error", "path": "expected-invalid/duplicate-security-scope.json", "pointer": "/security/0" }, { "outcome": "warning", "path": "expected-warning/uncatalogued-oauth-scope.json", "pointer": "/tools/0/security/0/oauth" }, { "outcome": "warning", "path": "expected-warning/uncatalogued-openid-scope.json", "pointer": "/security/0/oidc" } ], "id": "mcpdesc.security.requirements", "kind": "mcpdesc-semantic", "notes": "The document schema rejects duplicate scopes first; the semantic duplicate-scope check applies only to direct callers of the semantic validator.", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/07-security.md#req-security-scheme-references", "sections/07-security.md#req-security-scopes-unique", "sections/07-security.md#req-security-scopes-oauth-only", "sections/07-security.md#req-security-uncatalogued-scope", "sections/06-transports.md#req-transport-security-example", "sections/14-specification-extensions.md#req-extension-ineligible-locations" ], "reference": "MCP Description 0.9.0, Sections 7.1 to 7.3" } ], "status": "internal", "summary": "Security requirements name declared schemes, list scopes only for OAuth 2.0 and OpenID Connect schemes, do not repeat scopes, and use catalogued scopes when the scheme declares a static catalogue.", "surface": "Security Requirement", "title": "Reference security schemes and scopes correctly" }, { "applicability": { "protocolVersions": "independent" }, "description": "A document is UTF-8 JSON or a single restricted YAML document that decodes to the JSON data model: string keys only, no duplicate keys, tags, or aliases, no merge semantics, and only finite numbers. Rejected YAML is not validated further.", "enforcement": "external", "fixtures": [ { "outcome": "passes", "path": "serialization-fixtures/equivalent/document.json", "pointer": "" }, { "outcome": "passes", "path": "serialization-fixtures/equivalent/document.yaml", "pointer": "" }, { "outcome": "passes", "path": "serialization-fixtures/expected-valid/scalars-and-ordinary-merge-key.yaml", "pointer": "" }, { "outcome": "error", "path": "serialization-fixtures/expected-invalid/multiple-documents.yaml", "pointer": "" }, { "outcome": "error", "path": "serialization-fixtures/expected-invalid/non-string-key.yaml", "pointer": "" }, { "outcome": "error", "path": "serialization-fixtures/expected-invalid/duplicate-key.yaml", "pointer": "" }, { "outcome": "error", "path": "serialization-fixtures/expected-invalid/positive-infinity.yaml", "pointer": "" }, { "outcome": "error", "path": "serialization-fixtures/expected-invalid/custom-tag.yaml", "pointer": "" }, { "outcome": "error", "path": "serialization-fixtures/expected-invalid/alias.yaml", "pointer": "" }, { "outcome": "error", "path": "serialization-fixtures/expected-invalid/merge-alias.yaml", "pointer": "" } ], "id": "mcpdesc.serialization.conforming", "kind": "structural", "notes": "Checked when a serialization is decoded, before document validation, so a validator that receives decoded data reports this rule as delegated. Checked by decoding the serialization fixtures; scripts/test-serializations.mjs also checks that the equivalent JSON and YAML documents decode and validate identically.", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/03-document-structure.md#req-conforming-serialization", "sections/15-serialization.md#req-serialization-json", "sections/15-serialization.md#req-serialization-yaml-claims", "sections/15-serialization.md#req-serialization-yaml-single-document", "sections/15-serialization.md#req-serialization-yaml-string-keys", "sections/15-serialization.md#req-serialization-yaml-duplicate-keys", "sections/15-serialization.md#req-serialization-yaml-scalars", "sections/15-serialization.md#req-serialization-yaml-tags", "sections/15-serialization.md#req-serialization-yaml-aliases", "sections/15-serialization.md#req-serialization-yaml-merge-keys", "sections/15-serialization.md#req-serialization-yaml-validation" ], "reference": "MCP Description 0.9.0, Section 15" } ], "status": "delegated", "summary": "A document uses a conforming serialization: RFC 8259 JSON in UTF-8, or exactly one YAML document within the restricted YAML profile.", "surface": "Document serialization", "title": "Serialize documents as JSON or restricted YAML" }, { "applicability": { "protocolVersions": "independent" }, "description": "Each entry of the root tags catalogue is a Tag Object with a name and only the properties of Section 13.1.", "documentSchema": [ "#/$defs/tag" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/malformed-info-transport-tag-resource.json", "pointer": "/tags/0" } ], "id": "mcpdesc.tag.members", "kind": "structural", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/13-tags.md#req-tag-fields" ], "reference": "MCP Description 0.9.0, Section 13.1" } ], "status": "internal", "summary": "A Tag Object has a non-empty name and only its defined properties.", "surface": "Tag", "title": "Declare tags with a name" }, { "applicability": { "protocolVersions": "independent" }, "description": "When the document declares a tag catalogue, primitive tag references must name entries in it. Root tag names and repeated primitive references are checked for duplicates. Fix the name or catalogue entry instead of relying on an undeclared alias.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/duplicate-root-tag.json", "pointer": "/tags/1" }, { "outcome": "error", "path": "expected-invalid/duplicate-tag-reference.json", "pointer": "/tools/0/tags" } ], "id": "mcpdesc.tags.references", "kind": "mcpdesc-semantic", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/13-tags.md#req-tags-unique", "sections/13-tags.md#req-tags-references", "sections/09-tools.md#req-tool-tags-references", "sections/10-resources.md#req-resource-tags-references", "sections/10-resources.md#req-resource-template-tags-references", "sections/11-prompts.md#req-prompt-tags-references", "sections/13-tags.md#req-tag-name-unique", "sections/13-tags.md#req-tags-undeclared-error" ], "reference": "MCP Description 0.9.0, Sections 13.2 and 13.3" } ], "status": "internal", "summary": "Root tag names are unique, and primitives reference only declared tags.", "surface": "Tag", "title": "Reference unique declared tags" }, { "applicability": { "protocolVersions": "independent" }, "description": "Tool execution errors are completed MCP Tool results with isError true, not a separate description-only error catalogue. Check the error result's content and avoid presenting successful structured output as the error payload.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/invalid-tool-example-result-semantics.json", "pointer": "/tools/1/examples/business-error/result" } ], "id": "mcpdesc.tool.example.error-result", "kind": "mcpdesc-semantic", "notes": "MCP does not forbid structuredContent on error results; MCP Description requires its absence so that example structuredContent always conforms to outputSchema.", "owner": "mcpdesc", "path": "result", "requirement": "must", "specification": [ { "locations": [ "sections/09-tools.md#req-tool-example-error-result", "sections/09-tools.md#req-tool-example-success" ], "reference": "MCP Description 0.9.0, Section 9.3 (an execution-error result MUST NOT contain structuredContent; outputSchema does not validate error content)" } ], "status": "internal", "summary": "A Tool execution-error example result sets isError to true and does not contain structuredContent.", "surface": "Tool example", "title": "Represent Tool execution errors as error results" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "Example input must satisfy the resolved inputSchema, and successful structured output must satisfy outputSchema when supplied. Correct the example or the declaration's schema. Where resolution or dialect support prevents complete checking, the diagnostic must make that limitation visible.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/tool-example-schema-mismatches.json", "pointer": "/tools/0/examples/wrong-types" }, { "outcome": "error", "path": "expected-invalid/component-contextual-examples.json", "pointer": "/components/toolExamples/bad-input" }, { "outcome": "warning", "path": "expected-warning/pre-dialect-tool-example.json", "pointer": "/tools/0/examples/friendly" }, { "outcome": "warning", "path": "expected-warning/unresolved-external-tool-example-ref.json", "pointer": "/tools/0/examples/external-identifier" } ], "id": "mcpdesc.tool.example.schema-conformance", "kind": "mcpdesc-semantic", "notes": "Before MCP 2025-11-25 no embedded dialect is defined, so only the legacy shape is checked and the warning reports the gap.", "owner": "mcpdesc", "path": "examples, interactionExamples", "requirement": "must", "sources": [ { "locations": [ "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-06-18/server/tools.mdx#L309-L382", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2025-11-25/server/tools.mdx#L335-L408", "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/docs/specification/2026-07-28/server/tools.mdx#L509-L631" ], "reference": "MCP 2025-06-18 to 2026-07-28 specification, Server Features, Tools, Output Schema (structured results conform to outputSchema)", "tier": 1 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-tool-example-input-valid", "sections/09-tools.md#req-tool-example-incomplete-validation" ], "reference": "MCP Description 0.9.0, Sections 9.2, 9.3, and 9.4" } ], "status": "internal", "summary": "A Tool example input validates against inputSchema, and its structuredContent against outputSchema, for every applicable protocol version; incomplete validation is reported.", "surface": "Tool example", "title": "Check Tool examples against their schemas" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "A Tool interaction example can contradict its explicit minimum client requirements. Review the warning against the scenario and the declared requirements. The example does not automatically create or strengthen a client requirement.", "enforcement": "internal", "fixtures": [ { "outcome": "warning", "path": "expected-warning/tool-interaction-client-requirements-contradictions.json", "pointer": "/tools/0/interactionExamples/contradictory/steps/0" } ], "id": "mcpdesc.tool.interaction.client-requirements-consistency", "kind": "mcpdesc-semantic", "notes": "Steps never create requirements; the warning reports a contradiction only.", "owner": "mcpdesc", "path": "steps", "requirement": "should", "specification": [ { "locations": [ "sections/09-tools.md#req-interaction-client-requirements-warning" ], "reference": "MCP Description 0.9.0, Sections 8.5 and 9.4" } ], "status": "internal", "summary": "Interaction steps do not contradict the Tool's explicit client capability requirements.", "surface": "Tool interaction example", "title": "Keep interactions consistent with client requirements" }, { "applicability": { "protocolVersions": { "2024-11-05": "applies", "2025-03-26": "applies", "2025-06-18": "applies", "2025-11-25": "applies", "2026-07-28": "applies" } }, "description": "A Tool's elicitation step must agree with the named elicitation declaration and its requested form. Accepted form content must satisfy that schema, while declined or cancelled responses have different content rules. Check the reference, request, and response together.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/invalid-tool-interaction-example-semantics.json", "pointer": "/tools/0/interactionExamples/broken/steps/0" }, { "outcome": "passes", "path": "expected-valid/named-tool-interaction-examples.json", "pointer": "/tools/0/interactionExamples" } ], "id": "mcpdesc.tool.interaction.elicitation-consistency", "kind": "mcpdesc-semantic", "owner": "mcpdesc", "path": "steps", "requirement": "must", "sources": [ { "locations": [ "validation/mcp-schemas/2025-06-18/schema.ts#L1538-L1557", "validation/mcp-schemas/2025-11-25/schema.ts#L2466-L2486", "validation/mcp-schemas/2026-07-28/schema.ts#L3120-L3149" ], "reference": "MCP 2025-06-18 to 2026-07-28 schema.ts, interface ElicitResult, content (present for accepted form responses)", "tier": 1 } ], "specification": [ { "locations": [ "sections/09-tools.md#req-interaction-elicitation-declaration", "sections/09-tools.md#req-interaction-elicitation-response" ], "reference": "MCP Description 0.9.0, Section 9.4" } ], "status": "internal", "summary": "An elicitation step matches the Tool's named Elicitation Declaration, and its response content is present exactly when an accepted form response requires it and validates against the requested schema.", "surface": "Tool interaction example", "title": "Match elicitation steps to their declaration" }, { "applicability": { "protocolVersions": "independent" }, "description": "A Tool interaction example has input, ordered steps, and a result. Each step is an elicitation, sampling, or roots step with its request and response, and accepts only its defined properties.", "documentSchema": [ "#/$defs/toolInteractionExamples", "#/$defs/toolInteractionExample", "#/$defs/toolInteractionStep", "#/$defs/toolInteractionElicitationStep", "#/$defs/toolInteractionSamplingStep", "#/$defs/toolInteractionRootsStep" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/discriminated-union-members.json", "pointer": "/tools/0/interactionExamples/invalid/steps/1" }, { "outcome": "error", "path": "expected-invalid/malformed-tool-interaction-examples.json", "pointer": "/tools/0/interactionExamples/broken/description" } ], "id": "mcpdesc.tool.interaction.members", "kind": "structural", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/09-tools.md#req-interaction-example-fields", "sections/09-tools.md#req-interaction-step-fields", "sections/09-tools.md#req-interaction-examples-map", "sections/09-tools.md#req-interaction-step-closed" ], "reference": "MCP Description 0.9.0, Section 9.4" } ], "status": "internal", "summary": "Interaction examples and steps have their required members, a known step type, and no unknown properties.", "surface": "Tool interaction example", "title": "Shape Tool interaction examples and steps" }, { "applicability": { "protocolVersions": "independent" }, "description": "A Tool has a non-empty name and an inputSchema, and accepts only the properties of the Section 9.1 table, each with its defined type. The execution object accepts only taskSupport.", "documentSchema": [ "#/$defs/tool", "#/$defs/execution" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/empty-ordinary-nested-collections.json", "pointer": "/tools/0/elicitations" }, { "outcome": "error", "path": "expected-invalid/missing-tool-input-schema.json", "pointer": "/tools/0" } ], "id": "mcpdesc.tool.members", "kind": "structural", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/09-tools.md#req-tool-fields", "sections/09-tools.md#req-tool-input-schema-required", "sections/09-tools.md#req-execution-fields", "sections/12-elicitation.md#req-elicitations-non-empty", "sections/13-tags.md#req-entity-tags-shape", "sections/13-tags.md#req-entity-tags-unique" ], "reference": "MCP Description 0.9.0, Sections 9.1 and 9.7" } ], "status": "internal", "summary": "A Tool Object has its required fields, defined property types, and no unknown properties; so does its Execution Object.", "surface": "Tool, Execution", "title": "Declare Tools with their defined fields" }, { "applicability": { "protocolVersions": "independent" }, "description": "A transport is Streamable HTTP, stdio, or legacy SSE, selected by type. Each type requires its own fields, such as url or command, and accepts only the properties in its Section 6.2 table.", "documentSchema": [ "#/$defs/transport" ], "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/malformed-info-transport-tag-resource.json", "pointer": "/transports/0" }, { "outcome": "error", "path": "expected-invalid/transport-arg-typo.json", "pointer": "/transports/0" }, { "outcome": "error", "path": "expected-invalid/transport-independent-defects.json", "pointer": "/transports" }, { "outcome": "error", "path": "expected-invalid/transport-discriminator-errors.json", "pointer": "/transports" }, { "outcome": "passes", "path": "expected-valid/discriminated-unions.json", "pointer": "/transports" } ], "id": "mcpdesc.transport.members", "kind": "structural", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/06-transports.md#req-transport-streamable-http-fields", "sections/06-transports.md#req-transport-stdio-fields", "sections/06-transports.md#req-transport-sse-fields", "sections/06-transports.md#req-transport-type", "sections/06-transports.md#req-transport-closed", "sections/15-serialization.md#req-serialization-value-formats" ], "reference": "MCP Description 0.9.0, Section 6.2" } ], "status": "internal", "summary": "A Transport Object matches exactly one transport type and contains its required fields and only its defined properties.", "surface": "Transport", "title": "Declare transports with their type-specific fields" }, { "applicability": { "protocolVersions": "independent" }, "description": "When transports are declared, every root protocol version must be covered by at least one transport's effective scope. An omitted transport scope inherits all root versions. Add appropriate coverage or narrow the documented protocol versions rather than leaving an unreachable view. Descriptions may omit transports entirely.", "enforcement": "internal", "fixtures": [ { "outcome": "error", "path": "expected-invalid/root-version-without-transport.json", "pointer": "/protocolVersions" }, { "outcome": "error", "path": "expected-invalid/scoped-version-not-in-root.json", "pointer": "/protocolVersions" } ], "id": "mcpdesc.transports.coverage", "kind": "mcpdesc-semantic", "owner": "mcpdesc", "path": "transports", "requirement": "must", "specification": [ { "locations": [ "sections/06-transports.md#req-transport-coverage", "sections/06-transports.md#req-transport-coverage-omitted" ], "reference": "MCP Description 0.9.0, Section 6.5" } ], "status": "internal", "summary": "Every protocol version at the root is covered by at least one transport when transports are declared.", "surface": "Document", "title": "Cover each declared protocol version with a transport" }, { "applicability": { "protocolVersions": "independent" }, "description": "A merge validates every input, requires equivalent views for a shared protocol version and equal unscoped metadata, collapses equivalent declarations, keeps differing ones as disjoint variants, renames colliding components, and fails rather than guess when inputs conflict.", "enforcement": "external", "fixtures": [ { "outcome": "error", "path": "view-fixtures/merge-component-extension-conflict.json", "pointer": "/expectedFailure" }, { "outcome": "passes", "path": "view-fixtures/merge-component-name-collision.json", "pointer": "/expected" }, { "outcome": "error", "path": "view-fixtures/merge-invalid-input.json", "pointer": "/expectedFailure" }, { "outcome": "error", "path": "view-fixtures/merge-object-extension-conflict.json", "pointer": "/expectedFailure" }, { "outcome": "passes", "path": "view-fixtures/merge-object-extensions-variants.json", "pointer": "/expected" }, { "outcome": "passes", "path": "view-fixtures/merge-protocol-scoped-primitives.json", "pointer": "/expected" }, { "outcome": "error", "path": "view-fixtures/merge-same-protocol-version-conflict.json", "pointer": "/expectedFailure" }, { "outcome": "passes", "path": "view-fixtures/merge-security-forms.json", "pointer": "/expected" }, { "outcome": "error", "path": "view-fixtures/merge-tag-catalogue-conflict.json", "pointer": "/expectedFailure" }, { "outcome": "error", "path": "view-fixtures/merge-unscoped-conflict.json", "pointer": "/expectedFailure" } ], "id": "mcpdesc.view.merge", "kind": "mcpdesc-semantic", "notes": "Checked by the cases in view-fixtures/; scripts/test-view-fixtures.mjs also checks the round-trip invariant of Section 4.13 for every merge result.", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/04-versioning.md#req-merge-inputs", "sections/04-versioning.md#req-merge-algorithm", "sections/04-versioning.md#req-merge-equivalence", "sections/04-versioning.md#req-merge-security", "sections/04-versioning.md#req-merge-collections", "sections/13-tags.md#req-tags-merge", "sections/14-specification-extensions.md#req-extension-merge", "sections/17-components.md#req-component-merge", "sections/17-components.md#req-component-merge-extensions" ], "reference": "MCP Description 0.9.0, Section 4.13, and the merge requirements of Sections 13, 14, and 17" } ], "status": "delegated", "summary": "A merge result is valid, preserves every input protocol-version view, and fails on any conflict it cannot represent faithfully.", "surface": "Effective Protocol View", "title": "Merge protocol views without guessing" }, { "applicability": { "protocolVersions": "independent" }, "description": "A single-version projection validates the source, keeps the declarations whose effective scope includes the protocol version, removes their scopes, and keeps everything else unchanged: security forms, examples, client requirements, tags, extensions, and the components still referenced.", "enforcement": "external", "fixtures": [ { "outcome": "passes", "path": "view-fixtures/view-client-requirements-2026-07-28.json", "pointer": "/expected" }, { "outcome": "passes", "path": "view-fixtures/view-completion-examples-2026-07-28.json", "pointer": "/expected" }, { "outcome": "passes", "path": "view-fixtures/view-component-pruning-2026-07-28.json", "pointer": "/expected" }, { "outcome": "passes", "path": "view-fixtures/view-prompt-examples-2026-07-28.json", "pointer": "/expected" }, { "outcome": "passes", "path": "view-fixtures/view-protocol-scoped-primitives-2025-11-25.json", "pointer": "/expected" }, { "outcome": "passes", "path": "view-fixtures/view-protocol-scoped-primitives-2026-07-28.json", "pointer": "/expected" }, { "outcome": "passes", "path": "view-fixtures/view-resource-examples-2026-07-28.json", "pointer": "/expected" }, { "outcome": "error", "path": "view-fixtures/view-protocol-version-not-declared.json", "pointer": "/expectedFailure" }, { "outcome": "passes", "path": "view-fixtures/view-security-forms-2025-11-25.json", "pointer": "/expected" }, { "outcome": "passes", "path": "view-fixtures/view-security-forms-2026-07-28.json", "pointer": "/expected" }, { "outcome": "error", "path": "view-fixtures/view-source-invalid.json", "pointer": "/expectedFailure" }, { "outcome": "passes", "path": "view-fixtures/view-specification-extensions-2025-11-25.json", "pointer": "/expected" }, { "outcome": "passes", "path": "view-fixtures/view-tool-interaction-examples-2025-11-25.json", "pointer": "/expected" } ], "id": "mcpdesc.view.projection", "kind": "mcpdesc-semantic", "notes": "Checked by the cases in view-fixtures/, which scripts/test-view-fixtures.mjs recomputes with the reference operations of scripts/mcpdesc-views.mjs. Implementations such as @mcpdesc/core must pass them.", "owner": "mcpdesc", "requirement": "must", "specification": [ { "locations": [ "sections/04-versioning.md#req-view-projection", "sections/04-versioning.md#req-view-projection-transports", "sections/03-document-structure.md#req-security-empties-preserved", "sections/07-security.md#req-security-empty-distinction", "sections/07-security.md#req-security-projection", "sections/15-serialization.md#req-serialization-empty-values-preserved", "sections/09-tools.md#req-tool-example-views-preserved", "sections/09-tools.md#req-interaction-views-preserved", "sections/08-capabilities.md#req-client-requirements-views", "sections/10-resources.md#req-resource-example-views", "sections/10-resources.md#req-template-completion-views", "sections/11-prompts.md#req-prompt-example-views", "sections/11-prompts.md#req-prompt-completion-views", "sections/13-tags.md#req-tags-views", "sections/14-specification-extensions.md#req-extension-views", "sections/17-components.md#req-component-pruning" ], "reference": "MCP Description 0.9.0, Section 4.12, and the view requirements of Sections 3 to 17" } ], "status": "delegated", "summary": "An Effective Protocol View is a valid document for one protocol version that keeps the applicable declarations and preserves their content, security semantics, and referenced components.", "surface": "Effective Protocol View", "title": "Project a document to one MCP protocol version" } ], "uncheckedRequirements": [ { "location": "sections/03-document-structure.md#req-omission-not-absence", "note": "Constrains how consumers interpret an absent property.", "reason": "runtime" }, { "location": "sections/03-document-structure.md#req-primitive-absence", "note": "Constrains how consumers interpret an absent collection.", "reason": "runtime" }, { "location": "sections/03-document-structure.md#req-property-order", "note": "Concerns how tools read a serialization, not a document value.", "reason": "processing" }, { "location": "sections/03-document-structure.md#req-serialization-order", "note": "Concerns how tools read a serialization, not a document value.", "reason": "processing" }, { "location": "sections/04-versioning.md#req-no-network-conformance", "note": "Network access by a validator cannot be shown by a document fixture.", "reason": "processing" }, { "location": "sections/04-versioning.md#req-schema-aliases", "note": "Concerns schema publication, checked by the release publication checks rather than by document validation.", "reason": "processing" }, { "location": "sections/04-versioning.md#req-schema-bytes-immutable", "note": "Concerns schema publication, checked by the release publication checks rather than by document validation.", "reason": "processing" }, { "location": "sections/04-versioning.md#req-schema-identifier-exact", "note": "An authoring choice; omitting or varying $schema does not change conformance.", "reason": "guidance" }, { "location": "sections/04-versioning.md#req-schema-prerelease-identity", "note": "Concerns schema publication, checked by the release publication checks rather than by document validation.", "reason": "processing" }, { "location": "sections/04-versioning.md#req-schema-publication-headers", "note": "Concerns schema publication, checked by the release publication checks rather than by document validation.", "reason": "processing" }, { "location": "sections/04-versioning.md#req-schema-publication-http", "note": "Concerns schema publication, checked by the release publication checks rather than by document validation.", "reason": "processing" }, { "location": "sections/04-versioning.md#req-schema-retrieval-policy", "note": "Network access by a consumer cannot be shown by a document fixture.", "reason": "processing" }, { "location": "sections/04-versioning.md#req-schema-status-manifests", "note": "Concerns repository files, not documents.", "reason": "processing" }, { "location": "sections/04-versioning.md#req-schema-uri-immutable", "note": "Concerns schema publication, checked by the release publication checks rather than by document validation.", "reason": "processing" }, { "location": "sections/04-versioning.md#req-version-support", "note": "Concerns implementation claims.", "reason": "processing" }, { "location": "sections/05-info-object.md#req-info-trust", "note": "Constrains how consumers interpret Info values.", "reason": "runtime" }, { "location": "sections/05-info-object.md#req-info-version-semver", "note": "A versioning convention; any non-empty version is valid.", "reason": "guidance" }, { "location": "sections/06-transports.md#req-transport-selection", "note": "Concerns client connection behavior.", "reason": "runtime" }, { "location": "sections/06-transports.md#req-transports-omission", "note": "Constrains how consumers interpret absent transports.", "reason": "runtime" }, { "location": "sections/07-security.md#req-security-no-combined-requirement", "note": "Concerns tool behavior when transports differ.", "reason": "processing" }, { "location": "sections/07-security.md#req-security-schemes-omission", "note": "Constrains how consumers interpret absent security schemes.", "reason": "runtime" }, { "location": "sections/07-security.md#req-security-transport-variants", "note": "An authoring choice that a document cannot show.", "reason": "guidance" }, { "location": "sections/08-capabilities.md#req-capability-independence", "note": "Concerns tool transformations, not document values.", "reason": "processing" }, { "location": "sections/08-capabilities.md#req-client-requirements-compatibility", "note": "Concerns compatibility tools, not documents.", "reason": "processing" }, { "location": "sections/08-capabilities.md#req-client-requirements-extension-compatibility", "note": "Concerns compatibility tools, not documents.", "reason": "processing" }, { "location": "sections/08-capabilities.md#req-client-requirements-unconditional", "note": "Whether a capability is used on every runtime path cannot be decided from the document.", "reason": "guidance" }, { "location": "sections/08-capabilities.md#req-extensions-catalogue-disclosure", "note": "Concerns validator metadata and release practice.", "reason": "processing" }, { "location": "sections/08-capabilities.md#req-extensions-not-reinterpreted", "note": "Concerns tool transformations, not document values.", "reason": "processing" }, { "location": "sections/08-capabilities.md#req-extensions-profiles", "note": "Concerns optional validation profiles.", "reason": "processing" }, { "location": "sections/09-tools.md#req-interaction-no-secrets", "note": "Whether a value is a secret cannot be decided from the document.", "reason": "guidance" }, { "location": "sections/09-tools.md#req-interaction-step-not-wire", "note": "Concerns MCP connections, not documents.", "reason": "runtime" }, { "location": "sections/09-tools.md#req-interaction-untrusted", "note": "Constrains how consumers use scenario content.", "reason": "runtime" }, { "location": "sections/09-tools.md#req-tool-annotations-untrusted", "note": "Constrains MCP clients.", "reason": "runtime" }, { "location": "sections/09-tools.md#req-tool-example-no-secrets", "note": "Whether a value is a secret cannot be decided from the document.", "reason": "guidance" }, { "location": "sections/09-tools.md#req-tool-example-not-inferred", "note": "Concerns how producers create documents.", "reason": "processing" }, { "location": "sections/09-tools.md#req-tool-example-tooling", "note": "Concerns documentation and mock tooling.", "reason": "processing" }, { "location": "sections/09-tools.md#req-tool-example-untrusted", "note": "Constrains how consumers use example content.", "reason": "runtime" }, { "location": "sections/09-tools.md#req-tool-schema-closed-recommended", "note": "Recommends a schema style; both styles are valid.", "reason": "guidance" }, { "location": "sections/09-tools.md#req-tool-schema-consumer-certainty", "note": "Advice to consumers about unresolved references.", "reason": "runtime" }, { "location": "sections/09-tools.md#req-tool-schema-no-fetch", "note": "Network access by a validator cannot be shown by a document fixture.", "reason": "processing" }, { "location": "sections/09-tools.md#req-tool-schema-self-contained", "note": "An authoring preference; external references remain valid.", "reason": "guidance" }, { "location": "sections/10-resources.md#req-resource-annotations-hints", "note": "Constrains how consumers use annotations.", "reason": "runtime" }, { "location": "sections/10-resources.md#req-resource-example-no-secrets", "note": "Whether a value is a secret cannot be decided from the document.", "reason": "guidance" }, { "location": "sections/10-resources.md#req-resource-example-order", "note": "Concerns how consumers use example contents.", "reason": "processing" }, { "location": "sections/10-resources.md#req-resource-example-tooling", "note": "Concerns documentation and mock tooling.", "reason": "processing" }, { "location": "sections/10-resources.md#req-resource-example-untrusted", "note": "Constrains how consumers use example content.", "reason": "runtime" }, { "location": "sections/11-prompts.md#req-prompt-example-no-secrets", "note": "Whether a value is a secret cannot be decided from the document.", "reason": "guidance" }, { "location": "sections/11-prompts.md#req-prompt-example-tooling", "note": "Concerns documentation and mock tooling.", "reason": "processing" }, { "location": "sections/11-prompts.md#req-prompt-example-untrusted", "note": "Constrains how consumers use example content.", "reason": "runtime" }, { "location": "sections/12-elicitation.md#req-elicitation-not-capability", "note": "Constrains how consumers interpret a declaration.", "reason": "runtime" }, { "location": "sections/12-elicitation.md#req-elicitation-runtime-wording", "note": "Concerns the message a server sends at run time.", "reason": "runtime" }, { "location": "sections/12-elicitation.md#req-elicitation-url-no-fetch", "note": "Network access by a validator cannot be shown by a document fixture.", "reason": "processing" }, { "location": "sections/13-tags.md#req-tags-display-order", "note": "Concerns how user interfaces present tags.", "reason": "runtime" }, { "location": "sections/14-specification-extensions.md#req-extension-documentation", "note": "Concerns extension publication, outside the document.", "reason": "guidance" }, { "location": "sections/14-specification-extensions.md#req-extension-lowercase-prefixes", "note": "A naming convention; any name matching ^x- is valid.", "reason": "guidance" }, { "location": "sections/14-specification-extensions.md#req-extension-mechanisms-separate", "note": "Concerns tool transformations, not document values.", "reason": "processing" }, { "location": "sections/14-specification-extensions.md#req-extension-naming-convention", "note": "A naming convention; any name matching ^x- is valid.", "reason": "guidance" }, { "location": "sections/14-specification-extensions.md#req-extension-no-core-override", "note": "Concerns extension design; validation applies core rules regardless of extensions.", "reason": "guidance" }, { "location": "sections/14-specification-extensions.md#req-extension-no-secrets", "note": "Whether a value is a secret cannot be decided from the document.", "reason": "guidance" }, { "location": "sections/14-specification-extensions.md#req-extension-object-values", "note": "An authoring preference; any JSON value is valid.", "reason": "guidance" }, { "location": "sections/14-specification-extensions.md#req-extension-schema-unavailable", "note": "Concerns optional extension validation by tools.", "reason": "processing" }, { "location": "sections/14-specification-extensions.md#req-extension-untrusted", "note": "Constrains how consumers use extension content.", "reason": "runtime" }, { "location": "sections/15-serialization.md#req-serialization-conversion", "note": "Checked for one document pair by scripts/test-serializations.mjs; concerns conversion tools.", "reason": "processing" }, { "location": "sections/15-serialization.md#req-serialization-explicit-reuse", "note": "An authoring recommendation.", "reason": "guidance" }, { "location": "sections/15-serialization.md#req-serialization-json-claims", "note": "Concerns implementation claims.", "reason": "processing" }, { "location": "sections/15-serialization.md#req-serialization-media-type", "note": "Concerns media types used by tools.", "reason": "processing" }, { "location": "sections/15-serialization.md#req-serialization-negotiation", "note": "Concerns tool exchanges, not documents.", "reason": "processing" }, { "location": "sections/15-serialization.md#req-serialization-numbers", "note": "Concerns implementation number handling.", "reason": "processing" }, { "location": "sections/15-serialization.md#req-serialization-schema-property", "note": "An authoring recommendation; $schema is optional.", "reason": "guidance" }, { "location": "sections/15-serialization.md#req-serialization-support", "note": "Concerns implementation capabilities.", "reason": "processing" }, { "location": "sections/15-serialization.md#req-serialization-untrusted", "note": "Resource limits of tools cannot be shown by a document fixture.", "reason": "processing" }, { "location": "sections/15-serialization.md#req-serialization-yaml-quoted-dates", "note": "A style recommendation; unquoted dates decode identically.", "reason": "guidance" }, { "location": "sections/16-conformance.md#req-conformance-claim", "note": "Concerns implementation claims.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-conforming-implementation", "note": "Concerns implementation behavior; its checkable parts are separate requirements.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-diagnostic-component-provenance", "note": "Specifies component-reference resolution and diagnostic provenance, which document fixtures cannot validate as a conformance property.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-diagnostic-conditional-reduction", "note": "Specifies validator error reduction and is tested by repository diagnostic tests rather than document fixtures.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-diagnostic-deduplication", "note": "Specifies validator diagnostic deduplication and is tested by repository diagnostic tests rather than document fixtures.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-diagnostic-detail", "note": "Defines the validation result format, checked against its result schema rather than document conformance fixtures.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-diagnostic-rule", "note": "Concerns validator output; scripts/test-validation-rules.mjs checks it for the candidate validator on every fixture.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-diagnostic-rule-attribution", "note": "Specifies validator rule attribution and is tested by repository diagnostic tests rather than document fixtures.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-diagnostic-source-location", "note": "Specifies validator diagnostic locations; this behavior is exercised by repository diagnostic tests rather than document fixtures.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-diagnostic-union-closure", "note": "Constrains schema authoring and repository schema checks, not the contents of an individual description.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-diagnostic-union-conditionals", "note": "Constrains schema authoring and repository schema checks, not the contents of an individual description.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-implementation-recommendations", "note": "Concerns implementation behavior.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-partial-support", "note": "Concerns implementation documentation.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-rule-results", "note": "Concerns validator output; scripts/test-validation-rules.mjs checks the candidate validator's rule results against the validation result schema and every fixture citation.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-rule-results-executed", "note": "Concerns validator behavior; scripts/test-validation-rules.mjs checks that every passed result of the candidate validator has a recorded evaluation.", "reason": "processing" }, { "location": "sections/16-conformance.md#req-stricter-profile", "note": "Concerns implementation profiles.", "reason": "processing" }, { "location": "sections/17-components.md#req-component-limits", "note": "Resource limits of tools cannot be shown by a document fixture.", "reason": "processing" }, { "location": "sections/18-document-ordering.md#req-document-ordering-algorithm", "note": "Concerns how serializers organize output, not a document value.", "reason": "processing" }, { "location": "sections/18-document-ordering.md#req-document-ordering-collections", "note": "Constrains preservation of arrays and named-map entries during serialization.", "reason": "processing" }, { "location": "sections/18-document-ordering.md#req-document-ordering-default", "note": "Recommends an authoring and serialization presentation policy; property order does not affect document conformance.", "reason": "guidance" }, { "location": "sections/18-document-ordering.md#req-document-ordering-preservation", "note": "Constrains serializer behavior when applying the presentation profile.", "reason": "processing" }, { "location": "sections/18-document-ordering.md#req-document-ordering-recognition", "note": "Constrains serializer traversal and handling of unknown or opaque values.", "reason": "processing" }, { "location": "sections/99-appendices.md#req-icon-client-formats", "note": "Constrains MCP clients that display icons.", "reason": "runtime" } ] }