examples: rewrite default examples for 2026 stateless

hortovanyi · hortovanyi · commit a12f14c68444 · 2026-06-08T07:46:29.000+10:00
Replace the stateful 2025-11-25 handshake prose (initialize -&gt;
notifications/initialized -&gt; Mcp-Session-Id) in the 2026-default examples
with the stateless 2026 flow: server/discover plus per-request _meta carrying
the three io.modelcontextprotocol/* keys, MCP-Protocol-Version: 2026-07-28,
no session header. Covers READMEs, doc-comments, banners, curl snippets, the
middleware-auth-lambda test-event fixtures and TESTING.md, the icon-showcase
label, and a tool-output-introspection rustdoc fix. Genuine 2025 snippets
are kept under explicit "2025-11-25 (opt-in)" labels.
diff --git a/examples/derive-macro-server/README.md b/examples/derive-macro-server/README.md
@@ -10,7 +10,7 @@ This example demonstrates how to use the `#[derive(McpTool)]` macro for simplifi
 - **Optional Parameters**: Handling optional fields with `Option<T>`
 - **Error Handling**: Proper error handling in tool implementations
 - **Complex Data Types**: Working with various parameter types (strings, numbers, booleans)
-- **MCP 2025-11-25 Compliance**: Full specification compliance with proper `_meta` field handling
+- **MCP 2026-07-28 Compliance**: Full specification compliance with proper `_meta` field handling
 
 ## 🛠️ Available Tools
 
diff --git a/examples/function-macro-server/README.md b/examples/function-macro-server/README.md
@@ -245,7 +245,7 @@ Each tool defines its JSON schema with:
 - Manual trait implementations (this example)
 - Derive macros for struct-based tools (`#[derive(McpTool)]`)
 - Enhanced declarative `tool!` macro with parameter constraints
-- Full MCP 2025-11-25 protocol support with real-time notifications
+- Full MCP 2026-07-28 protocol support with real-time notifications
 
 **What's Coming:**
 - `#[mcp_tool]` function attribute macro completion
diff --git a/examples/icon-showcase/Cargo.toml b/examples/icon-showcase/Cargo.toml
@@ -6,7 +6,7 @@ authors.workspace = true
 license.workspace = true
 repository.workspace = true
 homepage.workspace = true
-description = "Example showcasing MCP 2025-11-25 icon support on tools, resources, prompts, and implementations"
+description = "Example showcasing MCP 2026-07-28 icon support on tools, resources, prompts, and implementations"
 
 [dependencies]
 turul-mcp-protocol = { workspace = true }
diff --git a/examples/icon-showcase/src/main.rs b/examples/icon-showcase/src/main.rs
@@ -1,4 +1,4 @@
-//! MCP 2025-11-25 Icon Support Showcase
+//! MCP 2026-07-28 Icon Support Showcase
 //!
 //! Demonstrates the `icons` field available on Tool, Resource, Prompt,
 //! ResourceTemplate, and Implementation types. Icons use the `Icon` struct
@@ -11,7 +11,7 @@ use turul_mcp_protocol::{
 };
 
 fn main() {
-    println!("=== MCP 2025-11-25 Icon Support Showcase ===\n");
+    println!("=== MCP 2026-07-28 Icon Support Showcase ===\n");
 
     // --- Tool with an HTTPS icon ---
     let calculator_tool = Tool::new(
diff --git a/examples/middleware-auth-lambda/TESTING.md b/examples/middleware-auth-lambda/TESTING.md
@@ -120,13 +120,18 @@ cargo lambda invoke middleware-auth-lambda \
   --output-format json | jq .
 ```
 
+The event body is a stateless 2026-07-28 `server/discover` request — no
+`initialize` handshake, no `Mcp-Session-Id`, and the per-request `_meta`
+(protocolVersion, clientInfo, clientCapabilities) inside `params`.
+
 **Expected response**:
 ```json
 {
   "jsonrpc": "2.0",
   "id": 1,
   "result": {
-    "protocolVersion": "2025-11-25",
+    "resultType": "complete",
+    "supportedVersions": ["2026-07-28"],
     "capabilities": {},
     "serverInfo": {
       "name": "middleware-auth-lambda",
@@ -284,7 +289,7 @@ cat /tmp/lambda-output.log | grep "Authorizer context"
 
 ## Streamable HTTP Compatibility
 
-This example uses the MCP 2025-11-25 **Streamable HTTP** transport via REST API (V1). REST API supports standard HTTP POST with full request/response control, making it compatible with Streamable HTTP. The Lambda adapter converts the API Gateway event into a standard `hyper::Request`, which the framework's `StreamableHttpHandler` processes normally.
+This example uses the MCP 2026-07-28 **Streamable HTTP** transport via REST API (V1). REST API supports standard HTTP POST with full request/response control, making it compatible with Streamable HTTP. The Lambda adapter converts the API Gateway event into a standard `hyper::Request`, which the framework's `StreamableHttpHandler` processes normally. The 2026 core is stateless: each request carries its own `_meta`; there is no `initialize`/`notifications/initialized` handshake and no `Mcp-Session-Id`.
 
 **Note**: All three authorizer context shapes (V1 nested, V1 flat, V2) are supported for extraction. However, Streamable HTTP transport requires REST API (V1).
 
diff --git a/examples/middleware-auth-lambda/src/main.rs b/examples/middleware-auth-lambda/src/main.rs
@@ -17,11 +17,13 @@
 //!
 //! # Transport: Streamable HTTP (REST API V1)
 //!
-//! This example uses the MCP 2025-11-25 Streamable HTTP transport via REST API (V1).
+//! This example uses the MCP 2026-07-28 Streamable HTTP transport via REST API (V1).
 //! REST API supports standard HTTP POST with full request/response control, making it
 //! compatible with Streamable HTTP. The Lambda adapter converts the API Gateway event
 //! into a standard `hyper::Request`, which the framework's `StreamableHttpHandler`
-//! processes normally.
+//! processes normally. The 2026 core is stateless: there is no `initialize`/
+//! `notifications/initialized` handshake and no `Mcp-Session-Id` — every request
+//! carries its own `_meta` (protocolVersion, clientInfo, clientCapabilities).
 //!
 //! **Note**: HTTP API (V2) authorizer context extraction is fully supported, but
 //! Streamable HTTP transport requires REST API (V1).
@@ -91,18 +93,21 @@
 //! # Usage
 //!
 //! ```bash
-//! # With valid API key
+//! # With valid API key (2026-07-28 stateless: no session handshake;
+//! # each request carries its own `_meta`)
 //! curl -X POST http://localhost:9000/lambda-url/middleware-auth-lambda \
 //!   -H "Content-Type: application/json" \
 //!   -H "Accept: application/json" \
+//!   -H "MCP-Protocol-Version: 2026-07-28" \
 //!   -H "X-API-Key: secret-key-123" \
-//!   -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
+//!   -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"test","version":"1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'
 //!
-//! # Without API key (should fail)
+//! # Without API key (should fail at the auth layer)
 //! curl -X POST http://localhost:9000/lambda-url/middleware-auth-lambda \
 //!   -H "Content-Type: application/json" \
 //!   -H "Accept: application/json" \
-//!   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+//!   -H "MCP-Protocol-Version: 2026-07-28" \
+//!   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"test","version":"1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'
 //! ```
 
 use async_trait::async_trait;
@@ -291,7 +296,7 @@ async fn main() -> Result<(), Error> {
     init_logging();
 
     info!("🚀 Starting AWS Lambda MCP Server with Authentication Middleware");
-    info!("Architecture: MCP 2025-11-25 with middleware auth layer");
+    info!("Architecture: MCP 2026-07-28 (stateless) with middleware auth layer");
     info!("  - X-API-Key header validation");
     info!("  - Lambda authorizer context extraction");
     info!("  - User context injection");
diff --git a/examples/middleware-auth-lambda/test-events/README.md b/examples/middleware-auth-lambda/test-events/README.md
@@ -100,6 +100,6 @@ Examples:
 
 ## Transport
 
-This example uses MCP 2025-11-25 **Streamable HTTP** transport via REST API (V1). REST API supports standard HTTP POST with full request/response control, making it compatible with Streamable HTTP.
+This example uses MCP 2026-07-28 **Streamable HTTP** transport via REST API (V1). REST API supports standard HTTP POST with full request/response control, making it compatible with Streamable HTTP. The 2026 core is stateless: each request carries its own `_meta` (protocolVersion, clientInfo, clientCapabilities); there is no `initialize`/`notifications/initialized` handshake and no `Mcp-Session-Id`.
 
 **Note**: All three authorizer shapes (V1 nested, V1 flat, V2) are supported for context extraction. However, Streamable HTTP transport requires REST API (V1).
diff --git a/examples/middleware-auth-lambda/test-events/apigw-v1-flat-authorizer.json b/examples/middleware-auth-lambda/test-events/apigw-v1-flat-authorizer.json
@@ -5,9 +5,10 @@
   "headers": {
     "Content-Type": "application/json",
     "Accept": "application/json",
+    "MCP-Protocol-Version": "2026-07-28",
     "X-API-Key": "secret-key-123"
   },
-  "body": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-11-25\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}",
+  "body": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"server/discover\",\"params\":{\"_meta\":{\"io.modelcontextprotocol/protocolVersion\":\"2026-07-28\",\"io.modelcontextprotocol/clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"},\"io.modelcontextprotocol/clientCapabilities\":{}}}}",
   "requestContext": {
     "accountId": "123456789012",
     "apiId": "test-api-id",
diff --git a/examples/middleware-auth-lambda/test-events/apigw-v1-with-authorizer.json b/examples/middleware-auth-lambda/test-events/apigw-v1-with-authorizer.json
@@ -5,9 +5,10 @@
   "headers": {
     "Content-Type": "application/json",
     "Accept": "application/json",
+    "MCP-Protocol-Version": "2026-07-28",
     "X-API-Key": "secret-key-123"
   },
-  "body": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-11-25\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}",
+  "body": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"server/discover\",\"params\":{\"_meta\":{\"io.modelcontextprotocol/protocolVersion\":\"2026-07-28\",\"io.modelcontextprotocol/clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"},\"io.modelcontextprotocol/clientCapabilities\":{}}}}",
   "requestContext": {
     "accountId": "123456789012",
     "apiId": "test-api-id",
diff --git a/examples/middleware-auth-lambda/test-events/apigw-v2-with-authorizer.json b/examples/middleware-auth-lambda/test-events/apigw-v2-with-authorizer.json
@@ -6,6 +6,7 @@
   "headers": {
     "content-type": "application/json",
     "accept": "application/json",
+    "mcp-protocol-version": "2026-07-28",
     "x-api-key": "secret-key-123"
   },
   "requestContext": {
@@ -31,6 +32,6 @@
     "time": "01/Jan/2025:00:00:00 +0000",
     "timeEpoch": 1704067200000
   },
-  "body": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-11-25\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}",
+  "body": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"server/discover\",\"params\":{\"_meta\":{\"io.modelcontextprotocol/protocolVersion\":\"2026-07-28\",\"io.modelcontextprotocol/clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"},\"io.modelcontextprotocol/clientCapabilities\":{}}}}",
   "isBase64Encoded": false
 }
diff --git a/examples/middleware-auth-server/src/main.rs b/examples/middleware-auth-server/src/main.rs
@@ -13,12 +13,14 @@
 //! # Start server
 //! cargo run --bin middleware-auth-server
 //!
-//! # Valid request with API key
+//! # Valid request with API key (2026-07-28 stateless: no session handshake;
+//! # each request carries its own `_meta`)
 //! curl -X POST http://localhost:8080/mcp \
 //!   -H "Content-Type: application/json" \
 //!   -H "Accept: application/json" \
+//!   -H "MCP-Protocol-Version: 2026-07-28" \
 //!   -H "X-API-Key: secret-key-123" \
-//!   -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
+//!   -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"test","version":"1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'
 //! ```
 
 use async_trait::async_trait;
@@ -184,9 +186,10 @@ async fn main() -> McpResult<()> {
     tracing::info!("  curl -X POST http://localhost:{}/mcp \\", args.port);
     tracing::info!("    -H 'Content-Type: application/json' \\");
     tracing::info!("    -H 'Accept: application/json' \\");
+    tracing::info!("    -H 'MCP-Protocol-Version: 2026-07-28' \\");
     tracing::info!("    -H 'X-API-Key: secret-key-123' \\");
     tracing::info!(
-        "    -d '{{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{{\"protocolVersion\":\"2025-11-25\",\"capabilities\":{{}},\"clientInfo\":{{\"name\":\"test\",\"version\":\"1.0\"}}}}}}'"
+        "    -d '{{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"server/discover\",\"params\":{{\"_meta\":{{\"io.modelcontextprotocol/protocolVersion\":\"2026-07-28\",\"io.modelcontextprotocol/clientInfo\":{{\"name\":\"test\",\"version\":\"1.0\"}},\"io.modelcontextprotocol/clientCapabilities\":{{}}}}}}}}'"
     );
 
     server.run().await
diff --git a/examples/minimal-server/README.md b/examples/minimal-server/README.md
@@ -21,18 +21,26 @@ The server will start on `http://127.0.0.1:8641/mcp` and provide:
 
 ## Testing the Server
 
-### 1. Initialize the Connection
+The 2026-07-28 core is stateless: there is no `initialize`/`notifications/initialized`
+handshake and no `Mcp-Session-Id`. Every request carries its own per-request `_meta`
+(`io.modelcontextprotocol/protocolVersion`, `clientInfo`, `clientCapabilities`) and the
+`MCP-Protocol-Version: 2026-07-28` header.
+
+### 1. Discover the Server
 ```bash
 curl -X POST http://127.0.0.1:8641/mcp \
   -H "Content-Type: application/json" \
+  -H "MCP-Protocol-Version: 2026-07-28" \
   -d '{
     "jsonrpc": "2.0",
     "id": 1,
-    "method": "initialize",
+    "method": "server/discover",
     "params": {
-      "protocolVersion": "2025-11-25",
-      "capabilities": {},
-      "clientInfo": {"name": "test-client", "version": "1.0.0"}
+      "_meta": {
+        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+        "io.modelcontextprotocol/clientInfo": {"name": "test-client", "version": "1.0.0"},
+        "io.modelcontextprotocol/clientCapabilities": {}
+      }
     }
   }'
 ```
@@ -41,23 +49,36 @@ curl -X POST http://127.0.0.1:8641/mcp \
 ```bash
 curl -X POST http://127.0.0.1:8641/mcp \
   -H "Content-Type: application/json" \
+  -H "MCP-Protocol-Version: 2026-07-28" \
   -d '{
     "jsonrpc": "2.0",
     "id": 2,
     "method": "tools/list",
-    "params": {}
+    "params": {
+      "_meta": {
+        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+        "io.modelcontextprotocol/clientInfo": {"name": "test-client", "version": "1.0.0"},
+        "io.modelcontextprotocol/clientCapabilities": {}
+      }
+    }
   }'
 ```
 
 ### 3. Call the Echo Tool
 ```bash
 curl -X POST http://127.0.0.1:8641/mcp \
   -H "Content-Type: application/json" \
+  -H "MCP-Protocol-Version: 2026-07-28" \
   -d '{
     "jsonrpc": "2.0",
     "id": 3,
     "method": "tools/call",
     "params": {
+      "_meta": {
+        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+        "io.modelcontextprotocol/clientInfo": {"name": "test-client", "version": "1.0.0"},
+        "io.modelcontextprotocol/clientCapabilities": {}
+      },
       "name": "echo",
       "arguments": {"text": "Hello, MCP!"}
     }
diff --git a/examples/notification-server/README.md b/examples/notification-server/README.md
@@ -63,18 +63,24 @@ In one terminal, connect to receive real-time updates:
 curl -H "Accept: text/event-stream" http://127.0.0.1:8005/mcp
 ```
 
-### 2. Initialize MCP Connection
-In another terminal, initialize the MCP connection:
+### 2. Discover the Server
+The 2026-07-28 core is stateless: there is no `initialize`/`notifications/initialized`
+handshake and no `Mcp-Session-Id`. Every request carries its own per-request `_meta`
+(`io.modelcontextprotocol/protocolVersion`, `clientInfo`, `clientCapabilities`) and the
+`MCP-Protocol-Version: 2026-07-28` header. In another terminal:
 ```bash
 curl -X POST http://127.0.0.1:8005/mcp \
   -H "Content-Type: application/json" \
+  -H "MCP-Protocol-Version: 2026-07-28" \
   -d '{
     "jsonrpc": "2.0",
-    "method": "initialize",
+    "method": "server/discover",
     "params": {
-      "protocolVersion": "2025-11-25",
-      "capabilities": {},
-      "clientInfo": {"name": "test-client", "version": "1.0.0"}
+      "_meta": {
+        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+        "io.modelcontextprotocol/clientInfo": {"name": "test-client", "version": "1.0.0"},
+        "io.modelcontextprotocol/clientCapabilities": {}
+      }
     },
     "id": "1"
   }'
@@ -85,10 +91,16 @@ Send a progress simulation request:
 ```bash
 curl -X POST http://127.0.0.1:8005/mcp \
   -H "Content-Type: application/json" \
+  -H "MCP-Protocol-Version: 2026-07-28" \
   -d '{
     "jsonrpc": "2.0",
     "method": "tools/call",
     "params": {
+      "_meta": {
+        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+        "io.modelcontextprotocol/clientInfo": {"name": "test-client", "version": "1.0.0"},
+        "io.modelcontextprotocol/clientCapabilities": {}
+      },
       "name": "simulate_progress",
       "arguments": {
         "task_name": "File Processing",
diff --git a/examples/oauth-resource-server/src/main.rs b/examples/oauth-resource-server/src/main.rs
@@ -28,12 +28,14 @@
 //! # Discover the authorization server:
 //! curl http://localhost:8080/.well-known/oauth-protected-resource
 //!
-//! # Call with a valid Bearer token:
+//! # Call with a valid Bearer token (2026-07-28 stateless: no session handshake;
+//! # each request carries its own `_meta`):
 //! curl -X POST http://localhost:8080/mcp \
 //!   -H "Content-Type: application/json" \
 //!   -H "Accept: application/json" \
+//!   -H "MCP-Protocol-Version: 2026-07-28" \
 //!   -H "Authorization: Bearer <JWT>" \
-//!   -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
+//!   -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"test","version":"1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'
 //! ```
 
 use clap::Parser;
diff --git a/examples/pagination-server/README.md b/examples/pagination-server/README.md
@@ -1,6 +1,6 @@
 # Pagination Server Example
 
-A comprehensive example demonstrating cursor-based pagination in MCP servers. This server shows how to handle large datasets efficiently using pagination with proper MCP 2025-11-25 compliant `_meta` fields.
+A comprehensive example demonstrating cursor-based pagination in MCP servers. This server shows how to handle large datasets efficiently using pagination with proper MCP 2026-07-28 compliant `_meta` fields.
 
 ## Overview
 
@@ -10,7 +10,7 @@ This example implements a complete pagination system with:
 - **Advanced search capabilities** with relevance scoring
 - **Batch processing** with progress tracking
 - **Filtering options** including active-only user filtering
-- **MCP 2025-11-25 compliant** `_meta` fields for proper pagination metadata
+- **MCP 2026-07-28 compliant** `_meta` fields for proper pagination metadata
 
 ## Features
 
@@ -27,7 +27,7 @@ This example implements a complete pagination system with:
 - **Thread-safe access** using Arc<Mutex<>> for concurrent operations
 - **Memory efficient** cursor-based navigation
 
-### 🎯 **MCP 2025-11-25 Compliance**
+### 🎯 **MCP 2026-07-28 Compliance**
 
 - **Proper `_meta` fields** with cursor, total, and has_more information
 - **Cursor management** with string-based position tracking
@@ -191,7 +191,7 @@ let next_cursor = if end_pos < total {
 };
 ```
 
-### MCP 2025-11-25 Meta Fields
+### MCP 2026-07-28 Meta Fields
 
 All paginated responses include proper `_meta` fields:
 
diff --git a/examples/prompts-server/README.md b/examples/prompts-server/README.md
diff --git a/examples/resources-server/README.md b/examples/resources-server/README.md
diff --git a/examples/resources-server/src/main.rs b/examples/resources-server/src/main.rs
diff --git a/examples/stateful-server/README.md b/examples/stateful-server/README.md
diff --git a/examples/tool-output-introspection/src/main.rs b/examples/tool-output-introspection/src/main.rs
diff --git a/examples/zero-config-getting-started/README.md b/examples/zero-config-getting-started/README.md
