Improve MCP documentation

Signed-off-by: Christian Tzolov <[email protected]>

Author: tzolov

spring-ai-docs/src/main/antora/modules/ROOT/images/mcp/java-mcp-client-architecture.jpg

@@ -98,7 +98,7 @@
 * xref:api/functions.adoc[Function Calling (Deprecated)]
 ** xref:api/function-callback.adoc[FunctionCallback API (Deprecated)]
 ** xref:api/tools-migration.adoc[Migrating to ToolCallback API]
-* xref:api/model-context-protocol.adoc[Model Context Protocol (MCP)]
+* xref:api/mcp/mcp-overview.adoc[Model Context Protocol (MCP)]
 ** xref:api/mcp/mcp-client-boot-starter-docs.adoc[MCP Client Boot Starters]
 ** xref:api/mcp/mcp-server-boot-starter-docs.adoc[MCP Server Boot Starters]
 ** xref:api/mcp/mcp-helpers.adoc[MCP Utilities]
@@ -115,4 +115,3 @@
 
 * Appendices
 ** xref:upgrade-notes.adoc[]
-

spring-ai-docs/src/main/antora/modules/ROOT/images/mcp/java-mcp-server-architecture.jpg

@@ -1,44 +1,43 @@
-= Spring AI MCP Client Boot Starter
+= MCP Client Boot Starter
 
 The Spring AI MCP (Model Context Protocol) Client Boot Starter provides auto-configuration for MCP client functionality in Spring Boot applications. It supports both synchronous and asynchronous client implementations with various transport options.
 
 The MCP Client Boot Starter provides:
 
+* Management of multiple client instances
 * Automatic client initialization (if enabled)
 * Support for multiple named transports
 * Integration with Spring AI's tool execution framework
-* Proper lifecycle management with automatic cleanup
+* Proper lifecycle management with automatic cleanup of resources when the application context is closed
 * Customizable client creation through customizers
 
-== Dependencies
+== Starters
 
-=== Core Starter
+=== Standard MCP Client
 
 [source,xml]
 ----
 <dependency>
     <groupId>org.springframework.ai</groupId>
     <artifactId>spring-ai-mcp-client-spring-boot-starter</artifactId>
-    <version>${spring-ai.version}</version>
 </dependency>
 ----
 
-It will connect, simultaneously, to one or more MCP Servers over `STDIO` (in-process) and/or `SSE` (remote) transports.
+The core starter connects simultaneously to one or more MCP servers over `STDIO` (in-process) and/or `SSE` (remote) transports.
 The SSE connection uses the HttpClient-based transport implementation.
-Every connection to an MCP Server creates a new MCP Client instance.
-You can opt for either `SYNC` or `ASYNC` MCP Clients (Note: you cannot mix sync and async clients).
-For more enterprise-ready deployment, it is recommended to use the WebFlux-based SSE connection using the `spring-ai-mcp-client-webflux-spring-boot-starter` starter.
+Each connection to an MCP server creates a new MCP client instance.
+You can choose either `SYNC` or `ASYNC` MCP clients (note: you cannot mix sync and async clients).
+For production deployment, we recommend using the WebFlux-based SSE connection with the `spring-ai-mcp-client-webflux-spring-boot-starter`.
 
-=== WebFlux Starter
+=== WebFlux Client
 
-Similar to the core starter, it allows configuring one or more STDIO and SSE connections, but uses WebFlux-based SSE transport implementation.
+The WebFlux starter provides similar functionality to the core starter but uses a WebFlux-based SSE transport implementation.
 
 [source,xml]
 ----
 <dependency>
     <groupId>org.springframework.ai</groupId>
     <artifactId>spring-ai-mcp-client-webflux-spring-boot-starter</artifactId>
-    <version>${spring-ai.version}</version>
 </dependency>
 ----
 
@@ -73,44 +72,14 @@ All common configuration properties are prefixed with `spring.ai.mcp.client`:
 |`20s`
 
 |`type`
-|Client type (SYNC or ASYNC). You can not mix client type. All clients can be either sync or async
+|Client type (SYNC or ASYNC). All clients must be either sync or async; mixing is not supported
 |`SYNC`
 
 |`root-change-notification`
 |Enable/disable root change notifications for all clients
 |`true`
 |===
 
-=== SSE Transport Properties
-
-Properties for Server-Sent Events (SSE) transport are prefixed with `spring.ai.mcp.client.sse`:
-
-[cols="2,4"]
-|===
-|Property |Description
-
-|`connections`
-|Map of named SSE connection configurations
-
-|`connections.[name].url`
-|URL endpoint for SSE communication with the MCP server
-|===
-
-Example configuration:
-[source,yaml]
-----
-spring:
-  ai:
-    mcp:
-      client:
-        sse:
-          connections:
-            server1:
-              url: http://localhost:8080
-            server2:
-              url: http://otherserver:8081
-----
-
 === Stdio Transport Properties
 
 Properties for Standard I/O transport are prefixed with `spring.ai.mcp.client.stdio`:
@@ -160,7 +129,7 @@ spring:
                 DEBUG: "true"
 ----
 
-Alternatively, you can configure stdio connections using an external JSON file using the link:https://modelcontextprotocol.io/quickstart/user[Claude Desctop format]:
+Alternatively, you can configure stdio connections using an external JSON file using the link:https://modelcontextprotocol.io/quickstart/user[Claude Desktop format]:
 
 [source,yaml]
 ----
@@ -172,7 +141,7 @@ spring:
           servers-configuration: classpath:mcp-servers.json
 ----
 
-The Claude Destop format looks like this:
+The Claude Desktop format looks like this:
 
 [source,json]
 ----
@@ -190,36 +159,102 @@ The Claude Destop format looks like this:
   }
 }
 ----
-Currently the Claude Destop supports only STDIO connection types.
+
+Currently, the Claude Desktop format supports only STDIO connection types.
+
+=== SSE Transport Properties
+
+Properties for Server-Sent Events (SSE) transport are prefixed with `spring.ai.mcp.client.sse`:
+
+[cols="2,4"]
+|===
+|Property |Description
+
+|`connections`
+|Map of named SSE connection configurations
+
+|`connections.[name].url`
+|URL endpoint for SSE communication with the MCP server
+|===
+
+Example configuration:
+[source,yaml]
+----
+spring:
+  ai:
+    mcp:
+      client:
+        sse:
+          connections:
+            server1:
+              url: http://localhost:8080
+            server2:
+              url: http://otherserver:8081
+----
 
 == Features
 
-=== Client Types
+=== Sync/Async Client Types
 
 The starter supports two types of clients:
 
-1. *Synchronous Client (SYNC)*
-   * Default client type
-   * Blocking operations
-   * Suitable for traditional request-response patterns
-
-2. *Asynchronous Client (ASYNC)*
-   * Non-blocking operations
-   * Suitable for reactive applications
-   * Must be explicitly configured using `spring.ai.mcp.client.type=ASYNC`
+* Synchronous - default client type, suitable for traditional request-response patterns with blocking operations
+* Asynchronous - suitable for reactive applications with non-blocking operations, configured using `spring.ai.mcp.client.type=ASYNC`
 
 === Client Customization
 
-The auto-configuration supports customization through:
+The auto-configuration supports client spec customization.
+Implement the `McpSyncClientCustomizer` callback interface to customize the `McpClient.SyncSpec` spec for a named server connection.
+Similarly, the `McpAsyncClientCustomizer` interface allows customizing the `McpClient.AsyncSpec` spec for asynchronous clients.
 
-* `McpSyncClientCustomizer` for synchronous clients
-* `McpAsyncClientCustomizer` for asynchronous clients
+[tabs]
+======
+Sync::
++
+[source,java]
+----
+@Component
+public class CustomMcpSyncClientCustomizer implements McpSyncClientCustomizer {
+    @Override
+    public void customize(String name, McpClient.SyncSpec spec) {
+        // Customize the sync client configuration
+        spec.requestTimeout(Duration.ofSeconds(30));
+    }
+}
+----
 
-== Usage Example
+Async::
++
+[source,java]
+----
+@Component
+public class CustomMcpAsyncClientCustomizer implements McpAsyncClientCustomizer {
+    @Override
+    public void customize(String name, McpClient.AsyncSpec spec) {
+        // Customize the async client configuration
+        spec.requestTimeout(Duration.ofSeconds(30));
+    }
+}
+----
+======
+
+The MCP client auto-configuration automatically detects and applies any customizers found in the application context.
+
+=== Transport Support
 
-1. Add the appropriate starter dependency to your project.
+The auto-configuration supports multiple transport types:
+
+* Standard I/O (Stdio) (activated by the `spring-ai-mcp-client-spring-boot-starter`)
+* SSE HTTP (activated by the `spring-ai-mcp-client-spring-boot-starter`)
+* SSE WebFlux (activated by the `spring-ai-starter-mcp-client-webflux`)
 
-2. Configure the client in `application.properties` or `application.yml`:
+=== Integration with Spring AI
+
+The starter automatically configures tool callbacks that integrate with Spring AI's tool execution framework, allowing MCP tools to be used as part of AI interactions.
+
+== Usage Example
+
+Add the appropriate starter dependency to your project and configure the client in `application.properties` or `application.yml`:
 
 [source,yaml]
 ----
@@ -250,8 +285,8 @@ spring:
                 API_KEY: your-api-key
                 DEBUG: "true"
 ----
-+
-3. The MCP client beans will be automatically configured and available for injection:
+
+The MCP client beans will be automatically configured and available for injection:
 
 [source,java]
 ----
@@ -264,75 +299,14 @@ private List<McpSyncClient> mcpSyncClients;  // For sync client
 private List<McpAsyncClient> mcpAsyncClients;  // For async client
 ----
 
-== Transport Support
-
-The auto-configuration supports multiple transport types:
-
-* Standard I/O (Stdio)
-* SSE HTTP
-* SSE WebFlux (requires `spring-ai-starter-mcp-client-webflux`)
-
-At least one transport must be available for the clients to be created.
-
-== Integration with Spring AI
-
-The starter automatically configures tool callbacks that integrate with Spring AI's tool execution framework, allowing MCP tools to be used as part of AI interactions.
-
-== Lifecycle Management
-
-The auto-configuration includes proper lifecycle management:
-
-* Automatic initialization of clients (if enabled)
-* Proper cleanup of resources when the application context is closed
-* Management of multiple client instances
-
-== Best Practices
-
-1. Choose the appropriate client type based on your application's needs:
-   * Use SYNC client for traditional applications
-   * Use ASYNC client for reactive applications
-
-2. Configure appropriate timeout values based on your use case:
-[source,yaml]
-----
-spring:
-  ai:
-    mcp:
-      client:
-        request-timeout: 30s
-----
-+
-3. Use customizers for advanced client configuration:
+Additionally, the registered MCP Tools with all MCP clients are provided as a list of ToolCallback instances:
 
 [source,java]
 ----
-@Component
-public class MyMcpClientCustomizer implements McpSyncClientCustomizer {
-    @Override
-    public void customize(String name, McpClient.SyncSpec clientSpec) {
-        // Custom configuration
-    }
-}
+@Autowired
+private List<ToolCallback> toolCallbacks;
 ----
 
-== Troubleshooting
-
-Common issues and solutions:
-
-1. *Client Not Created*
-   * Verify that at least one transport is available
-   * Check if the client is enabled in configuration
-   * Ensure required dependencies are present
-
-2. *Timeout Issues*
-   * Adjust the `request-timeout` property
-   * Check network connectivity
-   * Verify server response times
-
-3. *Integration Issues*
-   * Ensure proper transport configuration
-   * Check client initialization status
-
 == Additional Resources
 
 * link:https://docs.spring.io/spring-ai/reference/[Spring AI Documentation]