Fix draft spec examples and restore dropped guidance#2890
Merged
Conversation
- Show client capability declarations in their real shape: the value of _meta["io.modelcontextprotocol/clientCapabilities"] is the ClientCapabilities object, not a top-level "capabilities" wrapper (which belonged to the removed initialize request). - Relabel embedded Request/Response example pairs on elicitation, sampling, and roots pages to make the MRTR envelope clear: input requests are delivered inside InputRequiredResult.inputRequests, and client results are returned inside inputResponses on the retried request. Strip the leftover JSON-RPC result wrappers from those examples. - Replace the dangling URLElicitationRequiredError reference (the error no longer exists) with the InputRequiredResult/requestState retry flow. - Remove the unsupported pattern property from the StringSchema example in the restricted elicitation schema subset.
…fields - Add a note to tools, resources, prompts, completion, and pagination pages stating that request examples omit the required _meta request metadata for brevity, with a link to the _meta documentation. - Add the missing resultType: "complete" field to result examples on the tools, completion, and pagination pages. - Remove a stray top-level resultType field from a completion/complete request example (the field belongs on results, not requests). - Add ttlMs and cacheScope to the pagination resources/list response example, matching the caching requirements for list results. - Add resultType, ttlMs, and cacheScope rows to the server/discover Response Fields table.
…ellation The Timeouts section from the 2025-11-25 lifecycle page was dropped in the draft restructure. Re-add it to the cancellation page: senders SHOULD establish per-request timeouts, cancel on expiry (closing the response stream on Streamable HTTP, sending notifications/cancelled on stdio), MAY reset the clock on progress notifications, and SHOULD enforce a maximum timeout regardless.
- Scope the caching-hints MUST to results with resultType "complete": interim input_required results from multi round-trip requests are not CacheableResults and carry no caching hints. - Define what identifies a cached response (method plus the request parameters that affect the result) and forbid caching results produced via MRTR retries carrying inputResponses or requestState.
…moval
- New major-changes entry: all results carry a required resultType
field ("complete" or "input_required"); clients treat an absent
field from earlier-protocol servers as "complete".
- Reword the MRTR entry so resultType is not described as something
only InputRequiredResult carries.
- New major-changes entry: SSE stream resumability and redelivery
(Last-Event-ID) are removed; a broken response stream loses the
request and clients re-issue it as a new request.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
localden
added
spec
rc-high-priority
CaitieM20
reviewed
Jun 8, 2026
| - **stdio**: There is no per-request stream to close. The client **MUST** send a | ||
| `notifications/cancelled` notification referencing the request ID. | ||
|
|
||
| ## Timeouts |
Contributor
There was a problem hiding this comment.
thanks for adding this guidance
CaitieM20
reviewed
Jun 8, 2026
CaitieM20
reviewed
Jun 8, 2026
| | `capabilities` | `ServerCapabilities` | yes | Capabilities the server supports (tools, resources, prompts, etc.). | | ||
| | `serverInfo` | `Implementation` | yes | Name and version of the server software. | | ||
| | `instructions` | `string` | no | Natural-language guidance for LLMs on how to use this server effectively. | | ||
| | Field | Type | Required | Description | |
Contributor
There was a problem hiding this comment.
This section is a bit different than most of our doc pages, which is causing us to update any time any part of the message envelope changes which is not ideal.
The typical pattern most pages use is defining Data Types which are specific to the concept being introduced. Prompts, Resources, Tools all do this. I think we should re-write this section to match vs just adding all the additional fields.
Contributor
Author
There was a problem hiding this comment.
yeah, I think this is a better idea .... will update
Contributor
Author
There was a problem hiding this comment.
Done in 50b44bd — replaced the table with a Data Types / DiscoverResult section listing only the concept-specific fields, matching the Tools/Prompts/Resources pages. Envelope fields now appear only in the JSON example.
CaitieM20
previously approved these changes
Jun 8, 2026
CaitieM20
left a comment
CaitieM20
left a comment
Contributor
There was a problem hiding this comment.
I think we should rewrite the section in discover.mdx I flagged but doesn't need to block this PR
Match the pattern used by the Tools, Prompts, and Resources pages: describe only the concept-specific DiscoverResult fields, leaving envelope fields (resultType, ttlMs, cacheScope) to the JSON example and the caching page. This keeps the page from needing updates whenever the message envelope changes.
CaitieM20
approved these changes
Jun 17, 2026
This was referenced Jun 18, 2026
chore: sync spec-types/draft.ts to modelcontextprotocol@2fb207d
modelcontextprotocol/conformance#348
Merged
9 tasks
pcarleton
pushed a commit
to modelcontextprotocol/conformance
that referenced
this pull request
Jun 23, 2026
Updates SEP-2549 caching traceability text to match modelcontextprotocol/modelcontextprotocol#2890: - Scope the five *-caching-hints requirements to results with resultType: "complete" (interim input_required results carry no hints). - Add two excluded client MUST NOT rows from the new Cache Key section (cache-key mismatch, multi round-trip retry results). Neither is wire-observable since a conformant client may simply never cache. No check IDs change; traceability.json will be refreshed by the scheduled traceability workflow. Claude-Session: https://claude.ai/code/session_01Gbqx5LodtAghT5fRYFxeja
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Documentation-only fixes to
docs/specification/draft/: brings examples in line with the draft schema, restores guidance lost in the restructure, and documents two wire-format changes in the changelog.Why now
Most request/response examples in the draft currently fail validation against the draft schema, so anyone implementing from the docs produces non-conformant messages.
Changes
_metarequest metadata for brevity, linking to the base-protocol definition.resultTypeto six response examples (tools, completion, pagination), remove a strayresultTypefrom a request example in completion.mdx, and add the missingttlMs/cacheScopeto the pagination list example.ttlMs/cacheScope/resultTyperows to discover.mdx's Response Fields table (they are required onDiscoverResultbut absent from the table).{"capabilities": ...}wrapper from the removedinitializerequest — copied verbatim, servers read that as declaring no capability.inputRequests/inputResponses), since the server-initiated RPC shape they implied no longer exists.URLElicitationRequiredError(-32042) in elicitation.mdx; the retry flow now referencesInputRequiredResult/requestState.patternproperty from the StringSchema example that the schema does not define.notifications/cancelledon stdio); lives in basic/patterns/cancellation.mdx.resultType: "complete"(anInputRequiredResulthas no caching fields) and add a Cache Key section (results from MRTR retries are not cacheable).resultTypefield on all results and for the removal of SSE stream resumability/redelivery.Verification
npm run preppasses clean, including the link checker.