Skip to content

docs(unstable-v2): let a Client send the selected version when it falls back - #2874

Merged
benbrandt merged 1 commit into
mainfrom
docs/v2-initialize-latest-version
Nov 18, 2026
Merged

benbrandt merged 1 commit into
mainfrom
docs/v2-initialize-latest-version

Conversation

@benbrandt

Copy link
Copy Markdown
Member

Summary

The v2 initialization page says the initialize request MUST include the latest protocol version the Client supports. Two documented fallbacks send a lower version:

  • "Repeating initialization" lets the Client send initialize again with the version the Agent selected.
  • The migration guide tells a Client that needs v1-only features to reconnect with a v1 initialize.

Read literally, both broke the rule.

Changes

  • Initialization page: the rule stays. A new sentence says that after the Agent selects a lower version, the Client MAY send that version when it repeats initialize or opens a new connection. Changed in the stable page and its draft/ copy.
  • Migration guide: the dual-stack rules repeated the unscoped MUST. They get the same exception.

Notes

  • The exception applies only after the Agent has selected a lower version. A Client still offers its latest version first, so it keeps finding an Agent that later adds a newer version.
  • The exception covers a new connection as well as a repeated initialize, because an Agent that implements only v1 may not accept a repeated initialize.
  • v1 is unchanged, and so is the schema.

Checks

  • Prettier and typos pass on the changed files.
  • The links and anchors added by this change resolve.

…ls back

The initialization page requires every `initialize` request to carry the
latest protocol version the Client supports. The same page lets a Client
repeat `initialize` with the lower version the Agent selected, and the
migration guide tells it to reconnect with a v1 `initialize`. Read
literally, both fallbacks broke the rule.

- Keep the rule, and say that after the Agent selects a lower version
  the Client may send that version when it repeats `initialize` or opens
  a new connection.
- Add the same exception to the dual-stack rules in the migration guide.
@benbrandt
benbrandt requested a review from a team as a code owner November 18, 2026 12:55
@benbrandt
benbrandt enabled auto-merge (squash) November 18, 2026 12:57
@benbrandt
benbrandt merged commit 353cb9b into main Nov 18, 2026
10 checks passed
@benbrandt
benbrandt deleted the docs/v2-initialize-latest-version branch November 18, 2026 13:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant