Beans with @McpTool, @McpResource, @McpPrompt and @McpComplete methods, as well as ToolCallback and ToolCallbackProvider beans, are exposed exactly as on the stateless server. Methods keep their return types. Results typed with the legacy McpSchema classes are converted to the modern schema on the way out, so one set of beans can serve both server generations.

The conversion is a compatibility floor, not a ceiling. Every primitive also accepts the modern types directly, and those pass through untouched:

Use the modern types whenever a feature has no legacy equivalent: multi round-trip requests on any primitive, and per-response cache hints on resource reads.

For resources whose cache hints are static, set them on the annotation instead. ttlMs (default 0, not cacheable) and cacheScope (default PRIVATE) are applied to every legacy return value the callback converts. A method that returns a modern ReadResourceResult keeps the hints it built itself. On a legacy server these attributes are ignored with a warning at startup.

Bidirectional parameters of the session-based servers (McpSyncServerExchange, McpSyncRequestContext) are not available, as there is no session to call back on. Methods that declare them are skipped with a warning.

A tool, resource, prompt or completion method can declare a McpModernSyncRequestContext parameter. It gives access to the protocol version, the client capabilities and info, the request _meta, the progress token, the transport context and the multi round-trip fields. Declaring it does not change the shape of the response: the method still answers with a plain JSON result.

On the modern protocol a handler chooses the shape of its response, a single result or a stream of notifications that ends with the result, and the server never turns one into the other. Annotated methods make the same choice through their signature: a tool, resource or prompt method that declares the SDK McpSyncNotifier parameter is served as a streaming response (text/event-stream), and the notifications it pushes reach the client before the result. A method without that parameter is a plain result, whatever else it declares. Completion methods are always plain results and cannot declare the notifier.

To ask the client for input, return an InputRequiredResult from a tool, resource or prompt method. The client retries the call with the answers, which the context exposes through inputResponses() and inputResponse(key, type); the latter returns null on the first call, before the client has answered. The requestState you attach is sealed by the server and verified on retry, so it cannot be tampered with.

Methods that only need the raw fields can declare the modern request type (CallToolRequest, ReadResourceRequest or GetPromptRequest) instead of the context.

A modern client declares its capabilities in every request, and a server may only ask for input whose capability the request declares. Declare the capabilities a method cannot work without in requiredCapabilities on @McpTool, @McpResource or @McpPrompt:

The server checks the attribute before the method runs and answers a request that lacks any of the capabilities with JSON-RPC error -32021 Missing required client capability, listing the missing ones. The method does not run, and a method that declares McpSyncNotifier does not open a stream.

Input the method can do without needs no entry; ask for it only when ctx.clientCapabilities() declares it, for example supportsSampling(), and fall back otherwise.

A method that returns an InputRequiredResult asking for an undeclared capability is still answered with -32021, but only after it has run. The first time this happens for a method, a warning recommends the attribute. A method that declares requiredCapabilities but returns a type that cannot carry an InputRequiredResult is reported with a warning at startup. The attribute covers roots, sampling and form and URL elicitation; a method that depends on an experimental or extension capability is registered programmatically with the SDK ClientCapabilities. The legacy servers ignore the attribute with a warning, as they do for the resource cache hints.

Each primitive is served by an SDK repository bean: McpSyncToolRepository, McpSyncResourceRepository, McpSyncPromptRepository and McpSyncCompletionRepository. A repository lists definitions and finds a definition together with its handler: McpSyncTool, McpSyncPrompt and McpSyncResource are the SDK’s pairs of definition and handler, and the server validates the request and dispatches to the handler itself. Unless you define a bean of that type yourself, the auto-configuration registers an in-memory repository per primitive (InMemorySyncToolRepository, InMemorySyncResourceRepository, InMemorySyncPromptRepository, InMemorySyncCompletionRepository) and the McpChangeFeed that backs subscriptions/listen. Inject an in-memory repository to add or remove primitives at runtime; the matching list-changed notification is broadcast to listening clients. Call InMemorySyncResourceRepository.resourceUpdated(uri) to notify subscribers of a resource change.