docs: Improve MCP documentation and add getting started guide

- Fix grammar and formatting issues across MCP documentation
- Standardize transport naming to "Streamable-HTTP" throughout
- Add comprehensive "Getting Started with MCP" guide emphasizing annotation-based development
- Include video tutorials and complete tutorial resources
- Add navigation entry for new getting started guide

Signed-off-by: Mark Pollack <[email protected]>

Author: markpollack

spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc

@@ -85,7 +85,7 @@
 *** xref:api/mcp/mcp-server-boot-starter-docs.adoc[MCP Server Boot Starters]
 **** xref:api/mcp/mcp-stdio-sse-server-boot-starter-docs.adoc[STDIO and SSE MCP Servers]
 **** xref:api/mcp/mcp-streamable-http-server-boot-starter-docs.adoc[Streamable-HTTP MCP Servers]
-**** xref:api/mcp/mcp-stateless-server-boot-starter-docs.adoc[Stateless MCP Servers]
+**** xref:api/mcp/mcp-stateless-server-boot-starter-docs.adoc[Stateless Streamable-HTTP MCP Servers]
 // *** xref:api/mcp/mcp-helpers.adoc[MCP Utilities]
 *** xref:api/mcp/mcp-annotations-overview.adoc[MCP Annotations]
 **** xref:api/mcp/mcp-annotations-client.adoc[Client Annotations]
@@ -129,6 +129,7 @@
 
 * Guides
 ** https://github.com/spring-ai-community/awesome-spring-ai[Awesome Spring AI]
+** xref:guides/getting-started-mcp.adoc[Getting Started with MCP]
 ** xref:api/chat/prompt-engineering-patterns.adoc[]
 ** xref:api/effective-agents.adoc[Building Effective Agents]
 ** xref:api/cloud-bindings.adoc[Deploying to the Cloud]

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-annotations-overview.adoc

@@ -3,9 +3,8 @@
 The Spring AI MCP Annotations module provides annotation-based method handling for link:https://github.com/modelcontextprotocol/spec[Model Context Protocol (MCP)] servers and clients in Java. 
 It simplifies the creation and registration of MCP server methods and client handlers through a clean, declarative approach using Java annotations.
 
-
-The MCP Annotations enables developers to easily create and register methods for handling MCP operations using simple annotations. 
-It provides a clean, declarative approach to implementing MCP server and client functionality, reducing boilerplate code and improving maintainability.
+ The MCP Annotations enable developers to create and register MCP operation handlers using declarative annotations.
+This approach simplifies implementing MCP server and client functionality by reducing boilerplate code and improving maintainability.
 
 This library builds on top of the link:https://github.com/modelcontextprotocol/sdk-java[MCP Java SDK] to provide a higher-level, annotation-based programming model for implementing MCP servers and clients.
 

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-client-boot-starter-docs.adoc

@@ -26,7 +26,7 @@ The MCP Client Boot Starter provides:
 </dependency>
 ----
 
-The standard starter connects simultaneously to one or more MCP servers over `STDIO` (in-process), `SSE`, `Streamable Http` and `Stateless Streamable Http` transports.
+The standard starter connects simultaneously to one or more MCP servers over `STDIO` (in-process), `SSE`, `Streamable-HTTP` and `Stateless Streamable-HTTP` transports.
 The SSE and Streamable-Http transports use the JDK HttpClient-based transport implementation.
 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).
@@ -181,18 +181,18 @@ The Claude Desktop format looks like this:
 }
 ----
 
-=== Streamable Http Transport Properties
+=== Streamable-HTTP Transport Properties
 
 Used for connecting to Streamable-HTTP and Stateless Streamable-HTTP MCP servers.
 
-Properties for Streamable Http transport are prefixed with `spring.ai.mcp.client.streamable-http`:
+Properties for Streamable-HTTP transport are prefixed with `spring.ai.mcp.client.streamable-http`:
 
 [cols="3,4,3"]
 |===
 |Property |Description | Default Value
 
 |`connections`
-|Map of named Streamable Http connection configurations
+|Map of named Streamable-HTTP connection configurations
 |-
 
 |`connections.[name].url`
@@ -325,10 +325,10 @@ public class CustomMcpSyncClientCustomizer implements McpSyncClientCustomizer {
         });
 
         // Sets a custom elicitation handler for processing elicitation requests.
-				spec.elicitation((ElicitRequest request) -> {
+        spec.elicitation((ElicitRequest request) -> {
           // handle elicitation
-					return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
-				});
+          return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
+        });
 
         // Adds a consumer to be notified when progress notifications are received.
         spec.progressConsumer((ProgressNotification progress) -> {
@@ -384,8 +384,8 @@ The MCP client auto-configuration automatically detects and applies any customiz
 The auto-configuration supports multiple transport types:
 
 * Standard I/O (Stdio) (activated by the `spring-ai-starter-mcp-client` and `spring-ai-starter-mcp-client-webflux`)
-* (HttpClient) HTTP/SSE and StreamableHTTP (activated by the `spring-ai-starter-mcp-client`)
-* (WebFlux) HTTP/SSE and StreamableHTTP (activated by the `spring-ai-starter-mcp-client-webflux`)
+* (HttpClient) HTTP/SSE and Streamable-HTTP (activated by the `spring-ai-starter-mcp-client`)
+* (WebFlux) HTTP/SSE and Streamable-HTTP (activated by the `spring-ai-starter-mcp-client-webflux`)
 
 === Tool Filtering
 
@@ -592,8 +592,7 @@ If no custom converter bean is provided, the default converter is used automatic
 The MCP ToolCallback auto-configuration is enabled by default, but can be disabled with the `spring.ai.mcp.client.toolcallback.enabled=false` property.
 
 When disabled, no `ToolCallbackProvider` bean is created from the available MCP tools.
-If you need a fine grained control for selecting the which MCP tools to use, consider using the xref:/api/mcp/mcp-client-boot-starter-docs.adoc#_tool_filtering[Tool Filtering].
-
+bsafdsa
 == MCP Client Annotations
 
 The MCP Client Boot Starter automatically detects and registers annotated methods for handling various MCP client operations:

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-overview.adoc

@@ -1,27 +1,50 @@
 = Model Context Protocol (MCP)
 
-The link:https://modelcontextprotocol.org/docs/concepts/architecture[Model Context Protocol] (MCP) is a standardized protocol that enables AI models to interact with external tools and resources in a structured way. 
+TIP: **New to MCP?** Start with our xref:guides/getting-started-mcp.adoc[Getting Started with MCP] guide for a quick introduction and hands-on examples.
+
+The link:https://modelcontextprotocol.org/docs/concepts/architecture[Model Context Protocol] (MCP) is a standardized protocol that enables AI models to interact with external tools and resources in a structured way.
+Think of it as a bridge between your AI models and the real world - allowing them to access databases, APIs, file systems, and other external services through a consistent interface.
 It supports multiple transport mechanisms to provide flexibility across different environments.
 
 The link:https://modelcontextprotocol.io/sdk/java/mcp-overview[MCP Java SDK] provides a Java implementation of the Model Context Protocol, enabling standardized interaction with AI models and tools through both synchronous and asynchronous communication patterns.
 
-Spring AI extends the MCP Java SDK with Spring Boot integration, providing both xref:api/mcp/mcp-client-boot-starter-docs.adoc[Client] and xref:api/mcp/mcp-server-boot-starter-docs.adoc[Server] starters and xref:api/mcp/mcp-annotations-overview.adoc[MCP Annotations] for simplified development.
+Spring AI embraces MCP with comprehensive support through dedicated Boot Starters and MCP Java Annotations, making it easier than ever to build sophisticated AI-powered applications that can seamlessly connect to external systems.
+This means Spring developers can participate in both sides of the MCP ecosystem - building AI applications that consume MCP servers and creating MCP servers that expose Spring-based services to the wider AI community.
 Bootstrap your AI applications with MCP support using link:https://start.spring.io[Spring Initializer].
 
 == MCP Java SDK Architecture
 
 TIP: This section provides an overview for the link:https://modelcontextprotocol.io/sdk/java/mcp-overview[MCP Java SDK architecture]. 
 For the Spring AI MCP integration, refer to the xref:#_spring_ai_mcp_integration[Spring AI MCP Boot Starters] documentation.
 
-The Java MCP implementation follows a three-layer architecture:
+The Java MCP implementation follows a three-layer architecture that separates concerns for maintainability and flexibility:
 
-|===
-|  |
-^a| image::mcp/mcp-stack.svg[MCP Stack Architecture]
-a| * *Client/Server Layer*: The McpClient handles client-side operations while the McpServer manages server-side protocol operations. Both utilize McpSession for communication management.
-* *Session Layer (McpSession)*: Manages communication patterns and state through the McpClientSession and McpServerSession implementations.
-* *Transport Layer (McpTransport)*: Handles JSON-RPC message serialization and deserialization with support for multiple transport implementations.
-|===
+.MCP Stack Architecture
+image::mcp/mcp-stack.svg[MCP Stack Architecture, align=center]
+
+=== Client/Server Layer (Top)
+
+The top layer handles the main application logic and protocol operations:
+
+* *McpClient* - Manages client-side operations and server connections
+* *McpServer* - Handles server-side protocol operations and client requests
+* Both components utilize the session layer below for communication management
+
+=== Session Layer (Middle)
+
+The middle layer manages communication patterns and maintains connection state:
+
+* *McpSession* - Core session management interface
+* *McpClientSession* - Client-specific session implementation
+* *McpServerSession* - Server-specific session implementation
+
+=== Transport Layer (Bottom)
+
+The bottom layer handles the actual message transport and serialization:
+
+* *McpTransport* - Manages JSON-RPC message serialization and deserialization
+* Supports multiple transport implementations (STDIO, HTTP/SSE, Streamable-HTTP, etc.)
+* Provides the foundation for all higher-level communication
 
 |===
 | link:https://modelcontextprotocol.io/sdk/java/mcp-client[MCP Client] |
@@ -122,8 +145,8 @@ Key features include:
 * xref:api/mcp/mcp-annotations-server.adoc[Server Annotations]: `@McpTool`, `@McpResource`, `@McpPrompt`, `@McpComplete`
 * xref:api/mcp/mcp-annotations-client.adoc[Client Annotations]: `@McpLogging`, `@McpSampling`, `@McpElicitation`, `@McpProgress`
 * xref:api/mcp/mcp-annotations-special-params.adoc[Special Parameters]: `McpSyncServerExchange`, `McpAsyncServerExchange`, `McpTransportContext`, `McpMeta`
-* **Automatic Discovery**: Annotation scanning with configurable package inclusion/exclusion
-* **Spring Boot Integration**: Seamless integration with MCP Boot Starters
+* *Automatic Discovery*: Annotation scanning with configurable package inclusion/exclusion
+* *Spring Boot Integration*: Seamless integration with MCP Boot Starters
 
 == Additional Resources
 

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-server-boot-starter-docs.adoc

@@ -72,7 +72,7 @@ They are ideal for microservices architectures and cloud-native deployments. To
 
 == Sync/Async Server API Options
 
-The MCP Server API supports imperative (e.g. synchronous) and reactive (e.g. asynchronous) programming models.
+The MCP Server API supports imperative (i.e. synchronous) and reactive (e.g. asynchronous) programming models.
 
 * **Synchronous Server** - The default server type implemented using `McpSyncServer`.
 It is designed for straightforward request-response patterns in your applications.

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/mcp/mcp-stateless-server-boot-starter-docs.adoc

@@ -1,7 +1,7 @@
 
-== Stateless MCP Servers
+== Stateless Streamable-HTTP MCP Servers
 
-Stateless MCP servers are designed for simplified deployments where session state is not maintained between requests. 
+Stateless Streamable-HTTP MCP servers are designed for simplified deployments where session state is not maintained between requests. 
 These servers are ideal for microservices architectures and cloud-native deployments.
 
 TIP: Set the `spring.ai.mcp.server.protocol=STATELESS` property

spring-ai-docs/src/main/antora/modules/ROOT/pages/guides/getting-started-mcp.adoc

@@ -0,0 +1,163 @@
+= Getting Started with Model Context Protocol (MCP)
+
+The Model Context Protocol (MCP) standardizes how AI applications interact with external tools and resources.
+
+Spring joined the MCP ecosystem early as a key contributor, helping to develop and maintain the link:https://github.com/modelcontextprotocol/java-sdk[official MCP Java SDK] that serves as the foundation for Java-based MCP implementations. Building on this contribution, Spring AI provides comprehensive MCP support through Boot Starters and annotations, making it easy to build both MCP servers and clients.
+
+== Introduction Video
+
+**link:https://www.youtube.com/watch?v=FLpS7OfD5-s[Introduction to Model Context Protocol (MCP) - YouTube]**
+
+Start here for an introductory overview of the Model Context Protocol, explaining core concepts and architecture.
+
+== Complete Tutorial and Source Code
+
+**📖 Blog Tutorial:** link:https://spring.io/blog/2025/09/16/connect-your-ai-to-everything-spring-ais-mcp-boot-starters[Connect Your AI to Everything: Spring AI's MCP Boot Starters]
+
+**💻 Complete Source Code:** link:https://github.com/tzolov/spring-ai-mcp-blogpost[MCP Weather Example Repository]
+
+The tutorial provides comprehensive coverage of MCP development with Spring AI, including production-ready examples, advanced features, and deployment patterns. All code examples below are taken from this tutorial.
+
+== Quick Start
+
+The fastest way to get started is with Spring AI's annotation-based approach. The following examples are from the blog tutorial:
+
+=== Simple MCP Server
+
+[source,java]
+----
+@Service
+public class WeatherService {
+
+    @McpTool(description = "Get current temperature for a location")
+    public String getTemperature(
+            @McpToolParam(description = "City name", required = true) String city) {
+        return String.format("Current temperature in %s: 22°C", city);
+    }
+}
+----
+
+Add the dependency and configure:
+
+[source,xml]
+----
+<dependency>
+    <groupId>org.springframework.ai</groupId>
+    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
+</dependency>
+----
+
+[source,properties]
+----
+spring.ai.mcp.server.protocol=STREAMABLE
+----
+
+=== Simple MCP Client
+
+[source,java]
+----
+@Bean
+public CommandLineRunner demo(ChatClient chatClient, ToolCallbackProvider mcpTools) {
+    return args -> {
+        String response = chatClient
+            .prompt("What's the weather like in Paris?")
+            .toolCallbacks(mcpTools)
+            .call()
+            .content();
+        System.out.println(response);
+    };
+}
+----
+
+Configure the client connection:
+
+[source,yaml]
+----
+spring:
+  ai:
+    mcp:
+      client:
+        streamable-http:
+          connections:
+            weather-server:
+              url: http://localhost:8080
+----
+
+== Learning Resources
+
+=== Implementation Video
+
+**link:https://www.youtube.com/watch?v=hmEVUtulHTI[Spring AI Model Context Protocol (MCP) Integration - YouTube]**
+
+A comprehensive video walkthrough of Spring AI's MCP integration, covering both server and client implementations.
+
+== Additional Examples Repository
+
+Beyond the tutorial examples, the link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol[Spring AI Examples] repository contains numerous MCP implementations.
+
+=== Recommended Starting Points
+
+*Annotation-based examples* (recommended for best developer experience):
+
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-annotations-server[MCP Annotations Server] - Comprehensive annotation patterns
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-annotations/mcp-annotations-server[Complete Annotations Example] - All annotation features
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sampling/annotations/mcp-sampling-server-annotations[Sampling with Annotations] - Advanced bidirectional AI
+
+=== By Use Case
+
+**Weather Services:**
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-webflux-server[WebFlux Weather Server]
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-webmvc-oauth2-server[OAuth2 Secured Weather Server]
+
+**Data Integration:**
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/sqlite/chatbot[SQLite AI Chatbot]
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/filesystem[Filesystem Access Server]
+
+**Web Integration:**
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/web-search/brave-chatbot[Brave Search Chatbot]
+
+**Client Examples:**
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/client-starter/starter-default-client[Basic MCP Client]
+* link:https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/mcp-annotations/mcp-annotations-client[Annotations Client]
+
+== Key Concepts
+
+**MCP Servers** expose capabilities (tools, resources, prompts) to AI applications.
+**MCP Clients** connect AI applications to MCP servers.
+
+**Transport Options:**
+* *STDIO* - Desktop applications, IDE integrations
+* *Streamable-HTTP* - Production deployments, microservices
+* *SSE* - Real-time web applications
+* *Stateless* - Serverless environments
+
+**Why Annotations?**
+* Declarative approach - focus on business logic
+* Automatic JSON schema generation
+* Type-safe parameter handling
+* Spring Boot auto-configuration
+* Minimal boilerplate code
+
+== Community Resources
+
+* link:https://github.com/spring-ai-community/awesome-spring-ai[Awesome Spring AI] - Community examples and resources
+* link:https://modelcontextprotocol.org/[Official MCP Specification]
+* link:https://github.com/modelcontextprotocol/java-sdk[Official MCP Java SDK] - Java SDK developed by the Spring team
+* link:https://modelcontextprotocol.io/sdk/java/mcp-overview[MCP Java SDK Documentation]
+
+== Reference Documentation
+
+* xref:api/mcp/mcp-overview.adoc[MCP Overview and Architecture]
+* xref:api/mcp/mcp-annotations-overview.adoc[MCP Annotations Guide]
+* xref:api/mcp/mcp-server-boot-starter-docs.adoc[Server Boot Starters]
+* xref:api/mcp/mcp-client-boot-starter-docs.adoc[Client Boot Starters]
+
+== Next Steps
+
+1. Read the complete blog tutorial linked above
+2. Clone and explore the tutorial source code repository
+3. Watch the video tutorial for a visual walkthrough
+4. Try the annotation-based examples
+5. Explore the additional examples repository
+6. Read the reference documentation for advanced features
+7. Join the community and share your implementations