Express cache lifetimes as non-negative integers

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.

Requirement

ttlMs in a Resource example result is a non-negative integer when present.

Details

Rule ID: mcp.cacheable-result.ttl-ms
Owner: mcp
Surface: CacheableResult · Path: ttlMs
Kind: structural
Requirement level: must
Protocol versions: independent of the MCP protocol version
Document schema locations: #/$defs/completedReadResourceResultExample/properties/ttlMs
Status: arbitrated · Enforcement: internal

Required by

• MCP Description 0.9.0, Sections 3.6 and 10.4.4
  • 3. Document Structure: req-mcp-integer-numbers
  • 10. Resources and Resource Templates: req-resource-example-result-shape
• Proposal 0029, Integer MCP Numbers
  • proposal-snapshots/0029-integer-mcp-numbers.md

Based on

• Tier 1 — MCP schema.ts and normative specification text: MCP 2026-07-28 schema.ts, interface CacheableResult, ttlMs (unannotated number, @minimum 0)
  • validation/mcp-schemas/2026-07-28/schema.ts#L1081-L1094
• Tier 3 — Generated MCP schema.json: MCP 2026-07-28 generated schema.json, ReadResourceResult.ttlMs typed integer
  • validation/mcp-schemas/2026-07-28/schema.json#L2625-L2629
• Tier 3 — Generated MCP schema.json: MCP scripts/generate-schemas.ts: typescript-json-schema –defaultNumberType integer
  • https://github.com/modelcontextprotocol/modelcontextprotocol/blob/dae694f61a31f7a3ec2af3aff709e11f70f61e48/scripts/generate-schemas.ts#L95

Gaps and arbitrations

Arbitration: 2026-07-28

Conflict: schema.ts declares ttlMs as number, which TypeScript cannot restrict to integers; the generated schema.json types it as integer.

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.

Rationale: A millisecond duration is an integer in MCP’s generated schema; accepting fractions would let examples disagree with MCP’s types.

Review trigger: MCP changes its generator configuration or annotates ttlMs with @TJS-type number..

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.

Examples

Valid example

Source: expected-valid/named-resource-examples.json · Selected: /resources/1/examples/two-files/result/ttlMs

60000

Invalid example

Source: expected-invalid/fractional-ttl-ms.json · Selected: /resources/0/examples/cached/result/ttlMs

60000.5

Invalid example

Source: expected-invalid/resource-example-cache-fields.json · Selected: /resources/1/examples/invalid/result/ttlMs

-1

Rule Source Code

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