Skip to content

Restructure draft transport documentation#2845

Merged
CaitieM20 merged 19 commits into
fix/spec-improvementsfrom
refactor/transport-docs
Jun 3, 2026
Merged

Restructure draft transport documentation#2845
CaitieM20 merged 19 commits into
fix/spec-improvementsfrom
refactor/transport-docs

Conversation

@dsp-ant

@dsp-ant dsp-ant commented Jun 2, 2026

Copy link
Copy Markdown
Member

Note

Stacked on #2844. Review the diff against fix/spec-improvements; this PR retargets to main once #2844 merges.

Motivation and Context

The transports page presented MRTR, subscription streams, and the request-metadata model as Streamable HTTP features, while the stdio section was silent about them. That split mirrored earlier protocol revisions, where the transports genuinely differed in capabilities. In the current draft, protocol semantics are identical on every transport; only the binding differs. A reader of just the stdio section had no signal that server-initiated requests are gone there too.

There was also no page defining the core message patterns the protocol is built from, so that knowledge lived implicitly inside transport sections.

Changes

  • Add basic/patterns.mdx (Message Patterns), after Lifecycle: defines the client-initiated model and the core patterns every transport carries (request/response, multi round-trip requests, subscribe and notify), each with a sequence diagram and a link to its detailed page. New patterns added in future revisions are defined there without transport changes. MRTR stays under basic/utilities/, alongside subscriptions and progress.
  • Split basic/transports.mdx into a transports/ section:
    • index.mdx: binding concerns only. What a transport must provide (message delivery, metadata carriage, cancellation and termination signaling), the standard bindings, and requirements for custom transports. Keeps the /basic/transports URL.
    • stdio.mdx and streamable-http.mdx: per-transport bindings.
  • Remove leftovers from the bidirectional era: clients no longer send JSON-RPC responses on either transport, and the stdio page now states explicitly that servers must not write JSON-RPC requests to stdout.
  • Note that the stdio framing is plain newline-delimited JSON-RPC over a byte stream; custom stream transports (Unix domain sockets, TCP) should reuse it rather than define new framing.
  • Deduplicate backward compatibility: the binding pages are canonical for era-detection mechanics; lifecycle keeps the era model and the compatibility matrix.
  • Reorder the lifecycle and transports pages: scope statement first, terminology before use, transition material last.
  • Fix typos in the MRTR security requirements.

How was this tested?

npm run prep passes and mint broken-links is clean. The restructure commit is mostly file moves; streamable-http.mdx is detected as a 77% rename of the old transports.mdx.

dsp-ant added 9 commits June 2, 2026 16:55
The transports page presented MRTR, subscription streams, and the
request-metadata model as Streamable HTTP features, while the stdio
section was silent about them. The split mirrored the old transport
model, where each transport had genuinely different capabilities. In the
current draft, protocol semantics are identical on every transport; only
the binding differs.

- Split basic/transports.mdx into a transports/ section:
  - index.mdx: transport-independent overview — the client-initiated
    message flow, MRTR and subscriptions/listen as the only
    server-to-client mechanisms on any transport, the per-request
    metadata model, and what a binding must define.
  - stdio.mdx and streamable-http.mdx: per-transport bindings.
- Move MRTR from basic/utilities/ to basic/transports/, since it is part
  of the transport message flow rather than an optional utility. Add a
  redirect for the old URL.
- Remove leftovers from the bidirectional era: clients no longer send
  JSON-RPC responses on either transport, and the stdio page now states
  explicitly that servers must not write JSON-RPC requests to stdout.
- Update navigation and all draft-internal links.
The stdio wire format (newline-delimited JSON-RPC over a reliable
bidirectional byte stream) is not specific to standard streams; only the
process-lifecycle rules are. State this on the stdio page and recommend
that custom stream-based transports (Unix domain sockets, TCP) reuse the
stdio framing instead of defining new framing.
The era-detection mechanics were spelled out three times: in lifecycle,
in the transport binding pages, and partially in server/discover. The
copies had already drifted once.

- Binding pages are now canonical for detection mechanics. The stdio
  page absorbs the detail previously only in lifecycle (preferred
  version in _meta, three probe outcomes, supportedVersions selection).
- Lifecycle keeps the transport-independent content: the era model,
  caching guidance, and the compatibility matrix. It links to the
  binding pages for mechanics.
- server/discover refers to the stdio binding page instead of restating
  the fallback rules.
@dsp-ant dsp-ant requested review from a team as code owners June 2, 2026 16:39
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Jun 2, 2026
dsp-ant added 2 commits June 2, 2026 19:50
- Open with a scope statement and a short overview instead of normative
  rules.
- Add a terminology section defining modern, legacy, and dual-era before
  first use (previously defined inside the compatibility-matrix intro).
- Group the statelessness requirements under their own heading; split
  compound bullets and demote the connection-identity rationale to a
  note.
- Move extension negotiation before backward compatibility, so core
  protocol material precedes transition material.
- Promote backward compatibility to a top-level section (anchor
  unchanged).
- Open with a scope statement instead of the UTF-8 encoding rule; the
  encoding requirement moves to the top of Message Flow.
- Move Custom Transports before Backward Compatibility, so requirements
  for new bindings precede transition material.

@CaitieM20 CaitieM20 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The transport split is much cleaner, thanks for doing this. Also makes it super clear that both behave the same,

I still see MRTR as part of features/utilities since its describing message flow & contents. Plus the other utilities mentioned in the message flow diagram subscriptions & progress notifications are also defined in utilities.

I think the thing you may be getting at here though is the protocol itself provides for core message patterns that all transports need to implement.

  • Request/response
  • Subscribe & notify
  • MRTR - Input Required.

Things like Tasks & Triggers/Events also support different messaging patterns and if these become core protocol I'd expect them to be described on the transports/index page as well.

@@ -0,0 +1,129 @@
---
title: Transports

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if this should be split into two pages a Transports page and move the Message Flow section to Overview or it's own page after Lifecycle

In previous versions some of the message flow was handled by the lifecycle page but now this just says its a stateless protocol.

I think what you are correctly identifying is there is no good place for people to get a high-level overview for the messaging patterns supported by MCP.

dsp-ant and others added 3 commits June 2, 2026 23:09
Review feedback on the transport restructure: MRTR describes message
flow and contents, like subscriptions and progress, which live under
utilities. Moving only MRTR under transports was inconsistent. The
underlying gap is that no page defined the core message patterns every
transport carries.

- Add basic/patterns.mdx (Message Patterns), after Lifecycle in the nav.
  It defines the client-initiated model and the three core patterns
  (request/response, multi round-trip requests, subscribe and notify),
  each with a sequence diagram and a link to its detailed page, and
  states that new patterns are added there without transport changes.
- Move MRTR back to basic/utilities/ and drop the redirect.
- Slim the transports overview to binding concerns: message delivery
  requirements, metadata carriage, cancellation, custom transports, and
  backward compatibility. It links to the patterns page for flow
  semantics.
@CaitieM20

Copy link
Copy Markdown
Contributor

opened a PR against your branch to include these changes in basic/index.mdx #2846

dsp-ant and others added 2 commits June 3, 2026 10:43
update basic/index.mdx to reference message patterns page
Use the same pattern names and order in the base-protocol overview as on
the patterns page, and link each pattern to its section. Rename the
Request/Response heading to Request and Response so its anchor does not
contain an encoded slash.
dsp-ant added 2 commits June 3, 2026 12:23
The protocol is stateless: there is no initialize/operate/shutdown
sequence left to describe. Initialization became per-request metadata,
and shutdown is a transport-binding concern documented on the binding
pages. The remaining content of the lifecycle page has one theme: how
two implementations agree on what they are speaking.

- Rename basic/lifecycle.mdx to basic/versioning.mdx, titled
  "Versioning and Compatibility", covering version negotiation,
  extension negotiation, and backward compatibility. Add a redirect.
- Move the statelessness section to the base-protocol overview, where
  the execution model belongs.
- Update navigation and all draft-internal links.
…g-page

Rename Lifecycle to Versioning and Compatibility
@CaitieM20 CaitieM20 merged commit 79df957 into fix/spec-improvements Jun 3, 2026
5 checks passed
@CaitieM20 CaitieM20 deleted the refactor/transport-docs branch June 3, 2026 16:12
CaitieM20 added a commit that referenced this pull request Jun 3, 2026
* Remove mentioning of deprecated features

* Fix links in architecture

* Fix stdio legacy-fallback rule and add compatibility matrix

The stdio backward-compatibility probe told clients to fall back to the
legacy initialize handshake only on Method not found (-32601). Legacy
protocol revisions never specified how a server responds to an unknown
request received before initialize, and implementations vary: some return
-32601, others reject the request as invalid (-32602), and some do not
respond at all. A fallback keyed to -32601 therefore fails against real
legacy servers.

- Rewrite the stdio fallback rule: any error that is not a recognized
  modern error, or no response within a timeout, indicates a legacy
  server. Forbid keying the fallback to a single error code.
- Add guidance to cache the era determination per server.
- Recommend probing on stdio even for modern-only clients, since legacy
  servers may process era-ambiguous methods under legacy semantics.
- Add a compatibility matrix covering modern/dual-era/legacy client and
  server combinations, including the previously unspecified cases
  (legacy client vs modern-only server, dual-era server semantics).
- Align the duplicated text in transports.mdx and discover.mdx.

* Tighten wording in lifecycle backward-compatibility section

* Replace em-dashes with plain punctuation in new spec text

* Restructure draft transport documentation (#2845)

* Restructure draft transport documentation

The transports page presented MRTR, subscription streams, and the
request-metadata model as Streamable HTTP features, while the stdio
section was silent about them. The split mirrored the old transport
model, where each transport had genuinely different capabilities. In the
current draft, protocol semantics are identical on every transport; only
the binding differs.

- Split basic/transports.mdx into a transports/ section:
  - index.mdx: transport-independent overview — the client-initiated
    message flow, MRTR and subscriptions/listen as the only
    server-to-client mechanisms on any transport, the per-request
    metadata model, and what a binding must define.
  - stdio.mdx and streamable-http.mdx: per-transport bindings.
- Move MRTR from basic/utilities/ to basic/transports/, since it is part
  of the transport message flow rather than an optional utility. Add a
  redirect for the old URL.
- Remove leftovers from the bidirectional era: clients no longer send
  JSON-RPC responses on either transport, and the stdio page now states
  explicitly that servers must not write JSON-RPC requests to stdout.
- Update navigation and all draft-internal links.

* Fix typos in MRTR security requirements

* Note that stdio framing generalizes to any byte stream

The stdio wire format (newline-delimited JSON-RPC over a reliable
bidirectional byte stream) is not specific to standard streams; only the
process-lifecycle rules are. State this on the stdio page and recommend
that custom stream-based transports (Unix domain sockets, TCP) reuse the
stdio framing instead of defining new framing.

* State the transport message flow declaratively

* Trim request metadata wording in transport overview

* Replace em-dashes with plain punctuation in new spec text

* Make message-direction rules prescriptive in transport bindings

* Clarify stdio receiving-messages section

* Deduplicate backward-compatibility text across lifecycle and transports

The era-detection mechanics were spelled out three times: in lifecycle,
in the transport binding pages, and partially in server/discover. The
copies had already drifted once.

- Binding pages are now canonical for detection mechanics. The stdio
  page absorbs the detail previously only in lifecycle (preferred
  version in _meta, three probe outcomes, supportedVersions selection).
- Lifecycle keeps the transport-independent content: the era model,
  caching guidance, and the compatibility matrix. It links to the
  binding pages for mechanics.
- server/discover refers to the stdio binding page instead of restating
  the fallback rules.

* Reorder lifecycle page: scope first, transition material last

- Open with a scope statement and a short overview instead of normative
  rules.
- Add a terminology section defining modern, legacy, and dual-era before
  first use (previously defined inside the compatibility-matrix intro).
- Group the statelessness requirements under their own heading; split
  compound bullets and demote the connection-identity rationale to a
  note.
- Move extension negotiation before backward compatibility, so core
  protocol material precedes transition material.
- Promote backward compatibility to a top-level section (anchor
  unchanged).

* Reorder transport overview: scope first, transition material last

- Open with a scope statement instead of the UTF-8 encoding rule; the
  encoding requirement moves to the top of Message Flow.
- Move Custom Transports before Backward Compatibility, so requirements
  for new bindings precede transition material.

* Add message patterns page; keep MRTR under utilities

Review feedback on the transport restructure: MRTR describes message
flow and contents, like subscriptions and progress, which live under
utilities. Moving only MRTR under transports was inconsistent. The
underlying gap is that no page defined the core message patterns every
transport carries.

- Add basic/patterns.mdx (Message Patterns), after Lifecycle in the nav.
  It defines the client-initiated model and the three core patterns
  (request/response, multi round-trip requests, subscribe and notify),
  each with a sequence diagram and a link to its detailed page, and
  states that new patterns are added there without transport changes.
- Move MRTR back to basic/utilities/ and drop the redirect.
- Slim the transports overview to binding concerns: message delivery
  requirements, metadata carriage, cancellation, custom transports, and
  backward compatibility. It links to the patterns page for flow
  semantics.

* update basic/index.mdx to reference message patterns page

* add message patterns

* Align pattern names between overview and patterns page

Use the same pattern names and order in the base-protocol overview as on
the patterns page, and link each pattern to its section. Rename the
Request/Response heading to Request and Response so its anchor does not
contain an encoded slash.

* Title the transports index page Overview, matching other group index pages

* Rename Lifecycle to Versioning and Compatibility

The protocol is stateless: there is no initialize/operate/shutdown
sequence left to describe. Initialization became per-request metadata,
and shutdown is a transport-binding concern documented on the binding
pages. The remaining content of the lifecycle page has one theme: how
two implementations agree on what they are speaking.

- Rename basic/lifecycle.mdx to basic/versioning.mdx, titled
  "Versioning and Compatibility", covering version negotiation,
  extension negotiation, and backward compatibility. Add a redirect.
- Move the statelessness section to the base-protocol overview, where
  the execution model belongs.
- Update navigation and all draft-internal links.

---------

Co-authored-by: Caitie McCaffrey <caitiem20@github.com>

---------

Co-authored-by: Caitie McCaffrey <caitiem20@github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants