[tzolov]

Adds a server for the 2026-07-28 ("modern") MCP revision next to the existing STDIO, SSE, STREAMABLE and STATELESS servers, activated with spring.ai.mcp.server.protocol=MODERN. The revision drops initialize and sessions: server/discover is a cacheable request, every request carries the protocol version and the client capabilities in _meta, server-initiated input (elicitation, sampling, roots) is a multiround-trip request, and change notifications go over subscriptions/listen.

The integration builds on the modern API of MCP Java SDK 2.2.0 (io.modelcontextprotocol.modern), in particular the McpSyncTool/McpSyncPrompt/McpSyncResource features with repositories (modelcontextprotocol/java-sdk#1282) and required client capabilities (modelcontextprotocol/java-sdk#1283).

What is in the change

• Transports - WebMvcModernServerTransport and WebFluxMcpTransport serve the revision over a single POST endpoint: header/body consistency checks, JSON-RPC error to HTTP status mapping, bounded body reading, server-sent event streaming with keep-alives and an early header commit, and subscriptions/listen. The WebFlux transport runs sync handlers on boundedElastic and cancels in-flight work on client
  disconnect.
• Repositories (spring-ai-mcp) - In-memory repositories for tools, prompts, resources and completions with runtime add/remove, change broadcasts and key-cursor paging. SyncResourceEntry and SyncResourceTemplateEntry pair a resource definition with its handler, which the SDK's McpSyncResource does not carry. A legacy/modern McpSchemaConverter, ToolCallback adaptation and a header-based transport context convention complete the module.
• Annotations (spring-ai-mcp-annotations) - Modern method callbacks for @McpTool, @McpResource, @McpPrompt and @McpComplete implementing the SDK handler interfaces, and providers that build the SDK types from annotated beans. Methods may declare McpModernSyncRequestContext for the request data and the MRTR fields (inputResponses, requestState), and the SDK McpSyncNotifier for progress; a method streams if and only if it declares the notifier.
• Required client capabilities - requiredCapabilities on @McpTool, @McpPrompt and @McpResource lists the McpClientCapability values a method cannot work without; the server answers -32021 before the method runs. A runtime check on InputRequiredResult remains as the safety net.
• Definition attributes - @McpIcon with icons on the three annotations, @McpArg(title), @McpResource(size, ttlMs, cacheScope) and @McpToolParam(header = true), which emits the x-mcp-header schema keyword. The attributes are wired on the legacy, stateless and modern providers alike; the modern-only ones are ignored with a warning elsewhere.
• Auto-configuration - Publishes the scanned primitives as list beans (List<McpSyncTool> etc.), builds an in-memory repository per primitive unless a repository bean of the SDK interface is defined, wires McpServer with the features, the change feed and the request state codec, and registers the transports. New properties under spring.ai.mcp.server.modern.* (endpoint, list and discover TTLs, page size, request state secret and TTL).
• Documentation - A reference page for the modern server (mcp-modern-server-boot-starter-docs.adoc) and the new attributes on the annotations page.

Example

@McpTool(name = "delete_task", description = "Deletes a task after asking the user to confirm",
        requiredCapabilities = McpClientCapability.ELICITATION_FORM)
public CallToolOutcome deleteTask(McpSyncNotifier notifier, McpModernSyncRequestContext ctx,
        @McpToolParam(description = "Task id") String id) {
    Optional<ElicitResponse> answer = ctx.inputResponse("confirm", ElicitResponse.class);
    if (answer.isEmpty()) {
        notifier.progress(10, 100.0, "asking for confirmation");
        return InputRequiredResult.builder()
            .elicit("confirm", ElicitFormRequest.builder("Delete task " + id + "?", CONFIRM_SCHEMA).build())
            .requestState(id)
            .build();
    }
    ...
}

Annotated tools, resources and prompts of a STATELESS server migrate with the property change alone; the session-bound calls of a STREAMABLE server (ctx.elicit, ctx.sample, ctx.progress, client logging) are rewritten as above. Working samples for both migrations are in spring-projects/spring-ai-examples#151 (model-context-protocol/modern-migration).

Scope and follow-ups

• Only the synchronous API type is supported; type=ASYNC with protocol=MODERN fails at startup.
• Per-request client logging is not exposed, as the revision deprecates it (SEP-2577).
• Per-caller visibility of primitives is done by wrapping a repository bean; no filter interface yet.

Dependencies

mcp.sdk.version moves from 2.1.0 to 2.2.0-SNAPSHOT. The PR can be merged once MCP Java SDK 2.2.0 (or its first M/RC) is released and the version is updated.

[dimitarproynov]

As mentioned in the meeting this will only generate headaches for us. Let users implement it, as we cannot ever have a full white or black list.

[tzolov]

Agreed, and done in 8d514d2: the extractor is gone, and so is the context-headers property that briefly replaced it. The transport context is empty unless the application defines a McpTransportContextExtractor bean. McpTransportContexts.fromHeaders(names, lookup) stays as a helper for such a bean, and the reference page shows one in the per-caller filtering example.