docs: document runtime model, ASYNC semantics, and MCP SDK milestone

Clarify singleton-per-class concurrency, pseudo-async Mono.fromCallable behavior, and 2.0.0-M3 stability expectations in README, site docs, and llms files.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: codeboyzhou

README.md

@@ -266,6 +266,36 @@ streamable:
   port: 8080
 ```
 
+### Runtime model and stability
+
+#### SYNC vs ASYNC (`type`)
+
+The `type` setting selects which **MCP Java SDK server API** the framework uses. It does **not** turn your component methods into reactive code.
+
+| `type`  | What happens                                                                                                                                                                            |
+|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `SYNC`  | Handlers invoke your `@McpTool` / `@McpPrompt` / `@McpResource` methods on the request thread.                                                                                          |
+| `ASYNC` | Handlers return Reactor `Mono` values for MCP SDK compatibility. The SDK wraps each call in `Mono.fromCallable(...)` — your method body is still a normal **blocking** Java invocation. |
+
+**ASYNC is not a non-blocking or Project Reactor programming model.** You do not implement `Mono`/`Flux` in annotated methods. Long-running or CPU-heavy work still occupies a Reactor worker thread. Use **SYNC** unless your deployment specifically requires the async MCP server API. For high concurrency, keep handlers short and tune `request-timeout`.
+
+#### Component instances and concurrency
+
+The SDK creates **one instance per component class** (no-arg constructor) and reuses it for every MCP request to methods on that class. Concurrent calls share the same object.
+
+- Prefer **stateless** component classes, or **thread-safe** mutable state only.
+- Do not store per-request data in instance fields without proper synchronization.
+- Delegate shared mutable state to thread-safe services when needed.
+
+`McpApplicationContext.from(...)` currently uses this default singleton-per-class factory. There is no built-in Spring/CDI wiring in the public API today.
+
+#### MCP Java SDK 2.x (milestone)
+
+This project builds on the official [MCP Java SDK](https://github.com/modelcontextprotocol/java-sdk) **2.0.0-M3**, a **pre-release milestone**. APIs may change before 2.0 GA — pin dependency versions and re-run tests when upgrading.
+
+- **STREAMABLE** is the recommended HTTP transport for new projects.
+- **SSE** is still supported for compatibility but is **deprecated** in MCP SDK 2.x; avoid new SSE deployments.
+
 ### Multilingual Support (i18n)
 
 Enable i18n for your MCP components:
@@ -353,7 +383,15 @@ Run the test suite:
 
 ### Q: Can I use this in production?
 
-**A:** This project is currently in active development. While it's stable for development and testing, we recommend thorough testing before production use.
+**A:** The annotated layer is stable for development and testing, but it depends on the official MCP Java SDK **2.0.0-M3** (a milestone release). Pin versions, run your own integration tests, and expect possible SDK API changes before 2.0 GA before relying on it in production.
+
+### Q: What does `type: ASYNC` mean?
+
+**A:** It selects the async MCP server API from the underlying SDK. Your `@McpTool` / `@McpPrompt` / `@McpResource` methods remain ordinary blocking Java code; the framework wraps them in `Mono.fromCallable(...)`. Use SYNC unless you specifically need the async server API.
+
+### Q: Are component classes singletons?
+
+**A:** Yes. The SDK creates one instance per component class and reuses it for all requests. Keep components stateless or thread-safe; do not keep per-request mutable state on the instance without synchronization.
 
 ### Q: What Java version is required?
 

README.zh-CN.md

@@ -268,6 +268,36 @@ streamable:
   port: 8080
 ```
 
+### 运行时模型与稳定性
+
+#### SYNC 与 ASYNC（`type`）
+
+`type` 配置项决定框架使用哪一种 **MCP Java SDK 服务端 API**，**不会**把你的组件方法变成响应式代码。
+
+| `type`  | 行为                                                                                                            |
+|---------|---------------------------------------------------------------------------------------------------------------|
+| `SYNC`  | 在请求线程上直接调用 `@McpTool` / `@McpPrompt` / `@McpResource` 方法。                                                     |
+| `ASYNC` | 为兼容 MCP SDK 的异步 API，handler 返回 Reactor `Mono`。SDK 用 `Mono.fromCallable(...)` 包装调用 — 方法体仍是普通的 **阻塞式** Java 调用。 |
+
+**ASYNC 不是非阻塞或 Project Reactor 编程模型。** 注解方法中无需也不应返回 `Mono`/`Flux`。耗时或 CPU 密集的逻辑仍会占用 Reactor 工作线程。除非部署环境明确要求 async MCP 服务端 API，否则优先使用 **SYNC**。高并发场景请保持 handler 简短，并合理设置 `request-timeout`。
+
+#### 组件实例与并发
+
+SDK 为每个组件类创建 **唯一实例**（无参构造），该类上所有 MCP 请求共享该对象。
+
+- 组件类应 **无状态**，或仅持有 **线程安全** 的可变状态。
+- 不要在实例字段中存放未同步的 per-request 数据。
+- 需要共享可变状态时，请委托给线程安全的服务层。
+
+当前 `McpApplicationContext.from(...)` 使用默认的单例-per-class 工厂；公开 API 尚未内置 Spring/CDI 集成。
+
+#### MCP Java SDK 2.x（里程碑版本）
+
+本项目基于官方 [MCP Java SDK](https://github.com/modelcontextprotocol/java-sdk) **2.0.0-M3**，属于 **预发布里程碑**。2.0 正式版发布前 API 可能变更 — 请锁定依赖版本，升级后重新跑集成测试。
+
+- 新项目 HTTP 传输推荐 **STREAMABLE**。
+- **SSE** 仍可兼容使用，但在 MCP SDK 2.x 中已 **弃用**，不建议新部署采用。
+
 ### 多语言支持（i18n）
 
 为 MCP 组件启用国际化：
@@ -355,7 +385,15 @@ Windows 下可使用 `mvnw.cmd clean test`。
 
 ### 问：可以用于生产环境吗？
 
-**答：** 项目仍在积极开发中。用于开发与测试已较稳定，生产使用前建议充分验证。
+**答：** 注解层用于开发与测试已较稳定，但依赖官方 MCP Java SDK **2.0.0-M3**（里程碑版本）。生产使用前请锁定依赖版本、跑完自己的集成测试，并关注 2.0 正式版发布前可能的 SDK API 变更。
+
+### 问：`type: ASYNC` 是什么意思？
+
+**答：** 表示使用底层 SDK 的 async MCP 服务端 API。你的 `@McpTool` / `@McpPrompt` / `@McpResource` 方法仍是普通阻塞 Java 代码，框架会用 `Mono.fromCallable(...)` 包装。无特殊需求时请优先使用 SYNC。
+
+### 问：组件类是单例吗？
+
+**答：** 是。SDK 为每个组件类创建一个实例并在所有请求间复用。请保持组件无状态或线程安全，不要在实例字段中存放未同步的 per-request 可变状态。
 
 ### 问：需要什么 Java 版本？
 

docs/components.md

@@ -267,6 +267,18 @@ public int add(
 
 After defining MCP components, they will be automatically registered to the server. You just need to ensure that the component classes are in the package scanning path of the server application.
 
+### One instance per component class
+
+The SDK creates a single object per component class (via its no-arg constructor) and invokes all annotated methods on that class through the same instance. **Concurrent requests share one object**, so:
+
+- Keep component classes stateless when possible.
+- Any mutable instance fields must be thread-safe, or you must synchronize access.
+- Do not treat instance fields as per-request storage.
+
+### SYNC vs ASYNC server type
+
+Setting `type: ASYNC` in `mcp-server.yml` uses the async MCP server API from the underlying SDK. Handlers are implemented with `Mono.fromCallable(...)` around your blocking method — **ASYNC mode is not Project Reactor**. Your `@McpTool`, `@McpPrompt`, and `@McpResource` methods remain ordinary synchronous Java code.
+
 ### Specify Package Path
 
 If you need to specify a specific package path, you can use the following methods:

docs/getting-started.md

@@ -188,6 +188,25 @@ streamable:
 | `streamable.keep-alive-interval`  | Keep-alive interval (ms)                  | `20000`        |
 | `streamable.port`                 | HTTP port for STREAMABLE mode             | `8080`         |
 
+## Runtime model and stability
+
+### SYNC vs ASYNC (`type`)
+
+The `type` property selects the MCP Java SDK server API (`SYNC` or `ASYNC`). It does **not** make your annotated methods reactive.
+
+- **SYNC** — methods run on the request thread.
+- **ASYNC** — the SDK exposes async handlers that wrap your method in `Mono.fromCallable(...)`. Your code is still **blocking** Java; you do not return `Mono` from `@McpTool` / `@McpPrompt` / `@McpResource` methods.
+
+Use **SYNC** by default. Choose **ASYNC** only when your deployment requires the async MCP server API. Long work still blocks a Reactor worker thread under ASYNC.
+
+### Component instances and concurrency
+
+The SDK creates **one instance per component class** and reuses it for all requests. Concurrent MCP calls share that object. Keep components **stateless** or **thread-safe**; avoid unsynchronized per-request instance fields.
+
+### MCP Java SDK 2.x (milestone)
+
+This SDK depends on MCP Java SDK **2.0.0-M3** (pre-release). Pin versions and retest when upgrading. Prefer **STREAMABLE** over deprecated **SSE** for new HTTP deployments.
+
 ## Profile-based Configuration
 
 You can use profiles for different environments:

docs/index.md

@@ -55,6 +55,12 @@ This SDK is especially suitable for the following scenarios:
 | **SSE**        | Server-Sent Events (HTTP-based)     | Real-time web applications (deprecated)      |
 | **STREAMABLE** | HTTP streaming                      | Web applications, recommended for production |
 
+## Runtime notes
+
+- **ASYNC vs SYNC** — `type: ASYNC` selects the async MCP server API; your annotated methods stay blocking Java wrapped in `Mono.fromCallable(...)`. See [Getting Started — Runtime model](./getting-started.md#runtime-model-and-stability).
+- **Singleton components** — one instance per component class, shared across concurrent requests; keep handlers stateless or thread-safe.
+- **MCP SDK 2.0.0-M3** — built on a pre-release milestone; pin versions and prefer **STREAMABLE** over deprecated **SSE**.
+
 ## 📖 Getting Started
 
 Want to get started quickly? Check out the [Getting Started Guide](./getting-started.md) to learn how to build your first MCP server in 5 minutes.

llms-full.txt

@@ -517,8 +517,11 @@ public String createUser(
 ## Important Notes
 
 1. **Deprecated API**: The `McpServers` class is deprecated. Use `McpApplication.run()` instead.
-2. **Deprecated Mode**: SSE mode is deprecated. Use STREAMABLE mode for new projects.
-3. **Default Required**: The default `required` value for `@McpToolParam`, `@McpPromptParam`, and `@McpJsonSchemaProperty` is `true`.
+2. **Deprecated Mode**: SSE mode is deprecated in MCP SDK 2.x. Use STREAMABLE mode for new HTTP projects.
+3. **MCP SDK milestone**: This project depends on MCP Java SDK **2.0.0-M3** (pre-release). Pin versions and retest when upgrading.
+4. **ASYNC is not reactive**: `type: ASYNC` selects the async MCP server API; handlers wrap blocking Java methods in `Mono.fromCallable(...)`. Annotated methods do not return `Mono`/`Flux`.
+5. **Singleton components**: One instance per component class is shared across concurrent requests. Keep components stateless or thread-safe.
+6. **Default Required**: The default `required` value for `@McpToolParam`, `@McpPromptParam`, and `@McpJsonSchemaProperty` is `true`.
 
 ## Links
 

llms.txt

@@ -128,7 +128,10 @@ change-notification:
 ## Important Notes
 
 - The `McpServers` class is deprecated, use `McpApplication.run()` instead
-- SSE mode is deprecated, use STREAMABLE for production
+- SSE mode is deprecated in MCP SDK 2.x; use STREAMABLE for new HTTP deployments
+- Built on MCP Java SDK **2.0.0-M3** (milestone) — pin versions and retest when upgrading
+- `type: ASYNC` uses the async MCP server API; annotated methods stay blocking Java wrapped in `Mono.fromCallable(...)` — not Project Reactor
+- One instance per component class is created and shared across concurrent requests — keep components stateless or thread-safe
 - Components are auto-registered via package scanning
 
 ## Links

src/main/java/com/github/thought2code/mcp/annotated/server/component/DefaultMcpComponentInstanceFactory.java

@@ -9,8 +9,7 @@
  * Default component instance factory used by the SDK.
  *
  * <p>The factory creates component instances lazily through their no-argument constructor and
- * caches one instance per component class. Callers may also register prebuilt instances to preserve
- * application state or bridge into another object lifecycle.
+ * caches one instance per component class for the lifetime of the application context.
  *
  * @author codeboyzhou
  */