From 7b73bc7790fc22b9e3e07c15cefdd2907b7696f3 Mon Sep 17 00:00:00 2001 From: Koichi ITO Date: Tue, 15 Sep 2026 00:52:02 +0900 Subject: [PATCH] [Doc] Describe connect across both protocol lifecycles ## Motivation and Context The client documentation equated `MCP::Client#connect` with the MCP initialization handshake, which MCP 2026-07-28 removed: a modern connection probes `server/discover` instead. Calling `connect` first is still required on either era, since it settles the lifecycle and registers the identity, capabilities, and protocol version that modern requests carry in `_meta`, so the wording now names that rather than the handshake. ## How Has This Been Tested? Without `connect` a modern server rejects the first request; with it the same call succeeds. The documentation site builds with the new wording. ## Breaking Changes None. The change is documentation prose and example comments. --- README.md | 2 +- docs/_client/authorization.md | 2 +- docs/_client/lifecycle.md | 4 ++-- docs/_client/transports.md | 6 +++--- docs/index.md | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 7a71fb27..143d7d5c 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,7 @@ stdio_transport = MCP::Client::Stdio.new( ) client = MCP::Client.new(transport: stdio_transport) -# Perform the MCP initialization handshake before sending any requests. +# Negotiate the protocol lifecycle before sending any requests. client.connect # List available tools. diff --git a/docs/_client/authorization.md b/docs/_client/authorization.md index 72efd014..49542fb4 100644 --- a/docs/_client/authorization.md +++ b/docs/_client/authorization.md @@ -78,7 +78,7 @@ transport = MCP::Client::HTTP.new( oauth: provider, ) client = MCP::Client.new(transport: transport) -client.connect # `initialize` is sent here; if the server replies 401 the OAuth flow runs and the handshake is retried with the acquired token +client.connect # the lifecycle is established here; if the server replies 401 the OAuth flow runs and the request is retried with the acquired token client.tools ``` diff --git a/docs/_client/lifecycle.md b/docs/_client/lifecycle.md index 632db502..0d4637c3 100644 --- a/docs/_client/lifecycle.md +++ b/docs/_client/lifecycle.md @@ -12,7 +12,7 @@ This page covers `MCP::Client#connect` and how it negotiates between the two. ## Handshake -Call `MCP::Client#connect` to perform the MCP [initialization handshake](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization) before sending any other requests. The client sends an `initialize` request through the transport, followed by the required `notifications/initialized` notification, and caches the server's `InitializeResult` (protocol version, capabilities, server info, instructions): +Call `MCP::Client#connect` before sending any other requests. On the handshake lifecycle it performs the MCP [initialization handshake](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization): the client sends an `initialize` request through the transport, followed by the required `notifications/initialized` notification, and caches the server's `InitializeResult` (protocol version, capabilities, server info, instructions): ```ruby client.connect @@ -22,7 +22,7 @@ client.connected? # => true client.server_info # => cached InitializeResult ``` -`connect` accepts optional `client_info:`, `protocol_version:`, and `capabilities:` keyword arguments. It is idempotent: a second call returns the cached result without contacting the server. After `close`, state is cleared and `connect` will handshake again. +`connect` accepts optional `client_info:`, `protocol_version:`, and `capabilities:` keyword arguments. It is idempotent: a second call returns the cached result without contacting the server. After `close`, state is cleared and `connect` establishes the lifecycle again. This applies to both the Stdio and HTTP transports described on the [Transports](/client/transports/) page. diff --git a/docs/_client/transports.md b/docs/_client/transports.md index d69e5e90..f0c7ed84 100644 --- a/docs/_client/transports.md +++ b/docs/_client/transports.md @@ -35,7 +35,7 @@ stdio_transport = MCP::Client::Stdio.new( ) client = MCP::Client.new(transport: stdio_transport) -# Perform the MCP initialization handshake before sending any requests. +# Negotiate the protocol lifecycle before sending any requests. client.connect # List available tools. @@ -57,7 +57,7 @@ stdio_transport.close The stdio transport automatically handles: - Spawning the server process with `Open3.popen3` -- MCP protocol initialization handshake (`initialize` request + `notifications/initialized`) +- Lifecycle negotiation (a `server/discover` probe, or `initialize` + `notifications/initialized` on the handshake lifecycle) - JSON-RPC 2.0 message framing over newline-delimited JSON - Answering server `ping` requests; see [Answering Server Pings](/client/ping/#answering-server-pings) @@ -93,7 +93,7 @@ Example usage: http_transport = MCP::Client::HTTP.new(url: "https://api.example.com/mcp") client = MCP::Client.new(transport: http_transport) -# Perform the MCP initialization handshake before sending any requests. +# Negotiate the protocol lifecycle before sending any requests. client.connect # List available tools diff --git a/docs/index.md b/docs/index.md index ee275fc6..cb07259b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -83,7 +83,7 @@ stdio_transport = MCP::Client::Stdio.new( ) client = MCP::Client.new(transport: stdio_transport) -# Perform the MCP initialization handshake before sending any requests. +# Negotiate the protocol lifecycle before sending any requests. client.connect # List available tools.