Fix draft spec examples and restore dropped guidance#2890
Open
pja-ant wants to merge 5 commits into
Open
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
| `cursor` for paginated list requests). Clients **MUST NOT** serve a cached response for | ||
| a request whose method or parameters differ from the request that produced it. | ||
|
|
||
| Results produced by retrying a request through the |
Contributor
There was a problem hiding this comment.
I think this is fine to clarify, but we don't technically support MRTR on any of the Cacheable Results. So in practice not an issue in the current spec.
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.
CaitieM20
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
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.