Address review comments and improve docs structure and content

Resolves: #127

Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>

Author: tzolov

README.md

@@ -20,9 +20,9 @@ For comprehensive guides and SDK API documentation
 - [Java MCP Server](https://modelcontextprotocol.github.io/java-sdk/server/) - Learn how to implement and configure a MCP servers.
 
 #### Spring AI MCP documentation
-[Spring AI MCP](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html) extends the MCP Java SDK with Spring Boot integration, providing both [client](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) and [server](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html) starters. 
-The [MCP Annotations](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-annotations-overview.html) - provides annotation-based method handling for MCP servers and clients in Java.
-The [MCP Security](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-security.html) - provides comprehensive OAuth 2.0 and API key-based security support for Model Context Protocol implementations in Spring AI.
+[Spring AI MCP](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) extends the MCP Java SDK with Spring Boot integration, providing both [client](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-client-boot-starter-docs.html) and [server](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-server-boot-starter-docs.html) starters. 
+The [MCP Annotations](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-annotations-overview.html) - provides annotation-based method handling for MCP servers and clients in Java.
+The [MCP Security](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-security.html) - provides comprehensive OAuth 2.0 and API key-based security support for Model Context Protocol implementations in Spring AI.
 Bootstrap your AI applications with MCP support using [Spring Initializer](https://start.spring.io).
 
 ## Development
@@ -143,7 +143,7 @@ MCP supports both clients (applications consuming MCP servers) and servers (appl
 
 * **Why**: The JDK HttpClient is built-in, portable, and supports streaming responses. This keeps the default lightweight with no extra dependencies.
 
-* **How we expose it**: MCP Client APIs are transport-agnostic. The core module ships with JDK HttpClient transport. Spring WebClient-based transport is available in [Spring AI](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html) 2.0+.
+* **How we expose it**: MCP Client APIs are transport-agnostic. The core module ships with JDK HttpClient transport. Spring WebClient-based transport is available in [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+.
 
 * **How it fits the SDK**: This ensures all applications can talk to MCP servers out of the box, while allowing richer integration in Spring and other environments.
 
@@ -153,7 +153,7 @@ MCP supports both clients (applications consuming MCP servers) and servers (appl
 
 * **Why**: Servlet is the most widely deployed Java server API, providing broad reach across blocking and non-blocking models without additional dependencies.
 
-* **How we expose it**: Server APIs are transport-agnostic. Core includes Servlet support. Spring WebFlux and WebMVC server transports are available in [Spring AI](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html) 2.0+.
+* **How we expose it**: Server APIs are transport-agnostic. Core includes Servlet support. Spring WebFlux and WebMVC server transports are available in [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+.
 
 * **How it fits the SDK**: This allows developers to expose MCP servers in the most common Java environments today, while enabling other transport implementations such as Netty, Vert.x, or Helidon.
 
@@ -177,7 +177,7 @@ The SDK is organized into modules to separate concerns and allow adopters to bri
 * `mcp` – Convenience bundle (core + Jackson 3)
 * `mcp-test` – Shared testing utilities
 
-Spring integrations (WebClient, WebFlux, WebMVC) are now part of [Spring AI](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`).
+Spring integrations (WebClient, WebFlux, WebMVC) are now part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`).
 
 For example, a minimal adopter may depend only on `mcp` (core + Jackson), while a Spring-based application can use the Spring AI `mcp-spring-webflux` or `mcp-spring-webmvc` artifacts for deeper framework integration.
 

docs/blog/index.md

@@ -1 +1 @@
-# Blog
+# News

docs/blog/posts/spring-transport-migration.md

@@ -19,8 +19,8 @@ The MCP Client is a key component in the Model Context Protocol (MCP) architectu
 !!! tip
     The core `io.modelcontextprotocol.sdk:mcp` module provides STDIO, SSE, and Streamable HTTP client transport implementations without requiring external web frameworks.
 
-    The Spring-specific WebFlux transport (`mcp-spring-webflux`) is now part of [Spring AI](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`) and is no longer shipped by this SDK.
-    See the [MCP Client Boot Starter](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) documentation for Spring-based client setup.
+    The Spring-specific WebFlux transport (`mcp-spring-webflux`) is now part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`) and is no longer shipped by this SDK.
+    See the [MCP Client Boot Starter](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-client-boot-starter-docs.html) documentation for Spring-based client setup.
 
 The client provides both synchronous and asynchronous APIs for flexibility in different application contexts.
 
@@ -136,26 +136,20 @@ The client provides both synchronous and asynchronous APIs for flexibility in di
 
 The transport layer handles the communication between MCP clients and servers, providing different implementations for various use cases. The client transport manages message serialization, connection establishment, and protocol-specific communication patterns.
 
-=== "STDIO"
+### STDIO
 
-    Creates transport for process-based communication using stdin/stdout:
+Creates transport for process-based communication using stdin/stdout:
 
-    ```java
-    ServerParameters params = ServerParameters.builder("npx")
-        .args("-y", "@modelcontextprotocol/server-everything", "dir")
-        .build();
-    McpTransport transport = new StdioClientTransport(params);
-    ```
-
-=== "SSE (HttpClient)"
-
-    Creates a framework-agnostic (pure Java API) SSE client transport. Included in the core `mcp` module:
+```java
+ServerParameters params = ServerParameters.builder("npx")
+    .args("-y", "@modelcontextprotocol/server-everything", "dir")
+    .build();
+McpTransport transport = new StdioClientTransport(params);
+```
 
-    ```java
-    McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");
-    ```
+### Streamable HTTP
 
-=== "Streamable HTTP"
+=== "Streamable HttpClient"
 
     Creates a Streamable HTTP client transport for efficient bidirectional communication. Included in the core `mcp` module:
 
@@ -173,16 +167,36 @@ The transport layer handles the communication between MCP clients and servers, p
     - Custom HTTP request customization
     - Multiple protocol version negotiation
 
-=== "SSE (WebFlux)"
+=== "Streamable WebClient (external)"
+
+    Creates Streamable HTTP WebClient-based client transport. Requires the `mcp-spring-webflux` dependency from [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`):
+
+    ```java
+    McpTransport transport = WebFluxSseClientTransport
+        .builder(WebClient.builder().baseUrl("http://your-mcp-server"))
+        .build();
+    ```
+
+### SSE HTTP (Legacy)
 
-    Creates WebFlux-based SSE client transport. Requires the `mcp-spring-webflux` dependency from [Spring AI](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`):
+=== "SSE HttpClient"
+
+    Creates a framework-agnostic (pure Java API) SSE client transport. Included in the core `mcp` module:
+
+    ```java
+    McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");
+    ```
+=== "SSE WebClient (external)"
+
+    Creates WebFlux-based SSE client transport. Requires the `mcp-spring-webflux` dependency from [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`):
 
     ```java
     WebClient.Builder webClientBuilder = WebClient.builder()
         .baseUrl("http://your-mcp-server");
     McpTransport transport = new WebFluxSseClientTransport(webClientBuilder);
     ```
 
+
 ## Client Capabilities
 
 The client can be configured with various capabilities:
@@ -423,3 +437,160 @@ The prompt system enables interaction with server-side prompt templates. These t
     client.getPrompt(new GetPromptRequest("greeting", Map.of("name", "World")))
         .subscribe();
     ```
+
+## MCP Security
+
+The [MCP Security](https://github.com/spring-ai-community/mcp-security) community library provides OAuth 2.0 authorization support for Spring AI MCP clients. It supports both `HttpClient`-based and `WebClient`-based (WebFlux) MCP clients used with the [Spring AI MCP Client Boot Starter](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-client-boot-starter-docs.html).
+
+!!! note
+    This is a community project (`org.springaicommunity`), not officially part of the MCP Java SDK. It requires Spring AI 2.0.x (`mcp-client-security` version 0.1.x). For Spring AI 1.1.x, use version 0.0.6.
+
+### Add Dependency
+
+=== "Maven"
+
+    ```xml
+    <dependency>
+        <groupId>org.springaicommunity</groupId>
+        <artifactId>mcp-client-security</artifactId>
+        <version>0.1.1</version>
+    </dependency>
+    ```
+
+=== "Gradle"
+
+    ```groovy
+    implementation("org.springaicommunity:mcp-client-security:0.1.1")
+    ```
+
+### Authorization Flows
+
+Three OAuth 2.0 flows are available:
+
+- **Authorization Code** — For user-present scenarios. The client sends requests with a bearer token on behalf of the user. Use `OAuth2AuthorizationCodeSyncHttpRequestCustomizer` (HttpClient) or `McpOAuth2AuthorizationCodeExchangeFilterFunction` (WebClient).
+- **Client Credentials** — For machine-to-machine communication without a user in the loop. Use `OAuth2ClientCredentialsSyncHttpRequestCustomizer` (HttpClient) or `McpOAuth2ClientCredentialsExchangeFilterFunction` (WebClient).
+- **Hybrid** — For mixed scenarios where some calls (e.g., `tools/list` on startup) use client credentials, while user-specific calls (e.g., `tools/call`) use authorization code tokens. Use `OAuth2HybridSyncHttpRequestCustomizer` (HttpClient) or `McpOAuth2HybridExchangeFilterFunction` (WebClient).
+
+!!! tip
+    Use the **Hybrid** flow when Spring AI's autoconfiguration initializes MCP clients on startup (listing tools before a user is present), but tool calls are user-authenticated.
+
+### Setup
+
+Add the following to `application.properties`:
+
+```properties
+# Ensure MCP clients are sync
+spring.ai.mcp.client.type=SYNC
+# Disable auto-initialization (most MCP servers require authentication on every request)
+spring.ai.mcp.client.initialized=false
+
+# Authorization Code client registration (for user-present flows)
+spring.security.oauth2.client.registration.authserver.client-id=<CLIENT_ID>
+spring.security.oauth2.client.registration.authserver.client-secret=<CLIENT_SECRET>
+spring.security.oauth2.client.registration.authserver.authorization-grant-type=authorization_code
+spring.security.oauth2.client.registration.authserver.provider=authserver
+
+# Client Credentials registration (for machine-to-machine or hybrid flows)
+spring.security.oauth2.client.registration.authserver-client-credentials.client-id=<CLIENT_ID>
+spring.security.oauth2.client.registration.authserver-client-credentials.client-secret=<CLIENT_SECRET>
+spring.security.oauth2.client.registration.authserver-client-credentials.authorization-grant-type=client_credentials
+spring.security.oauth2.client.registration.authserver-client-credentials.provider=authserver
+
+# Authorization server issuer URI
+spring.security.oauth2.client.provider.authserver.issuer-uri=<ISSUER_URI>
+```
+
+Then activate OAuth2 client support in a security configuration class:
+
+```java
+@Configuration
+@EnableWebSecurity
+class SecurityConfiguration {
+
+    @Bean
+    SecurityFilterChain securityFilterChain(HttpSecurity http) {
+        return http
+                .authorizeHttpRequests(auth -> auth.anyRequest().permitAll())
+                .oauth2Client(Customizer.withDefaults())
+                .build();
+    }
+}
+```
+
+### HttpClient-Based Client
+
+When using `spring-ai-starter-mcp-client`, the transport is backed by the JDK's `HttpClient`. Expose a `McpSyncHttpClientRequestCustomizer` bean and an `AuthenticationMcpTransportContextProvider` on the client:
+
+```java
+@Configuration
+class McpConfiguration {
+
+    @Bean
+    McpSyncClientCustomizer syncClientCustomizer() {
+        return (name, syncSpec) ->
+                syncSpec.transportContextProvider(
+                        new AuthenticationMcpTransportContextProvider()
+                );
+    }
+
+    @Bean
+    McpSyncHttpClientRequestCustomizer requestCustomizer(
+            OAuth2AuthorizedClientManager clientManager
+    ) {
+        // "authserver" must match the registration name in application.properties
+        return new OAuth2AuthorizationCodeSyncHttpRequestCustomizer(
+                clientManager,
+                "authserver"
+        );
+    }
+}
+```
+
+Replace `OAuth2AuthorizationCodeSyncHttpRequestCustomizer` with `OAuth2ClientCredentialsSyncHttpRequestCustomizer` or `OAuth2HybridSyncHttpRequestCustomizer` for the corresponding flow.
+
+### WebClient-Based Client
+
+When using `spring-ai-starter-mcp-client-webflux`, the transport is backed by Spring's reactive `WebClient`. Expose a `WebClient.Builder` bean configured with an `ExchangeFilterFunction`:
+
+```java
+@Configuration
+class McpConfiguration {
+
+    @Bean
+    McpSyncClientCustomizer syncClientCustomizer() {
+        return (name, syncSpec) ->
+                syncSpec.transportContextProvider(
+                        new AuthenticationMcpTransportContextProvider()
+                );
+    }
+
+    @Bean
+    WebClient.Builder mcpWebClientBuilder(OAuth2AuthorizedClientManager clientManager) {
+        // "authserver" must match the registration name in application.properties
+        return WebClient.builder().filter(
+                new McpOAuth2AuthorizationCodeExchangeFilterFunction(
+                        clientManager,
+                        "authserver"
+                )
+        );
+    }
+}
+```
+
+Replace `McpOAuth2AuthorizationCodeExchangeFilterFunction` with `McpOAuth2ClientCredentialsExchangeFilterFunction` or `McpOAuth2HybridExchangeFilterFunction` for the corresponding flow.
+
+When using the chat client's `.stream()` method, Reactor does not preserve thread-locals. Inject the authentication into the Reactor context manually:
+
+```java
+chatClient
+    .prompt("<your prompt>")
+    .stream()
+    .content()
+    .contextWrite(AuthenticationMcpTransportContextProvider.writeToReactorContext());
+```
+
+### Known Limitations
+
+- Only `McpSyncClient` is supported; async clients are not.
+- Set `spring.ai.mcp.client.initialized=false` when servers require authentication on every request, as Spring AI autoconfiguration will otherwise attempt to list tools on startup without a token.
+- The SSE transport is supported by the client module (unlike the server module).