Release Notes

[2.0.0] The Maven artifact relocations and configuration property fallbacks for the old quarkus-mcp-server-sse artifact (renamed to quarkus-mcp-server-http in 1.8.0) have been removed. Users still referencing quarkus-mcp-server-sse must switch to quarkus-mcp-server-http, and any configuration properties using the sse. prefix (e.g. quarkus.mcp.server.sse.root-path) must be updated to use the http. prefix (e.g. quarkus.mcp.server.http.root-path). (#826)

[2.0.0] JSON-RPC batching support has been removed. Batching was added in MCP 2025-03-26 and removed in 2025-06-18. The server now rejects batch (JSON array) messages with a parse error. The whenBatch() method has been removed from the McpAssured test API. (#723)

[2.0.0] McpRequest.protocolVersion() now returns McpProtocolVersion instead of String.

[2.0.0] The quarkus.mcp-server.metrics.enabled config property is now read at runtime. Since it defaults to false, applications that rely on MCP metrics without explicitly setting quarkus.mcp-server.metrics.enabled=true will stop collecting them. (#844)

[2.0.0] Tracing spans are no longer started when quarkus.mcp.server.tracing.enabled=false for the relevant MCP server configuration. Previously, the tracing enablement check only considered the default server’s setting. (#845)

[2.0.0] Stateless MCP protocol support (protocol version 2026-07-28). The server supports both stateful and stateless clients simultaneously. Stateless clients use server/discover instead of the initialize/initialized handshake. See Stateless Mode. (#824)

[2.0.0] New McpConnection.isTransient() method to check if a connection is transient (per-request, not tracked on the server).

[2.0.0] New McpProtocolVersion class as the public API for protocol version handling, with isStateless(), isKnown(), from(String), and semantic constants (FIRST_STATELESS, LATEST_STATEFUL, DEFAULT_ASSUMED).

[2.0.0] Tracing spans now include the mcp.server.name attribute, identifying the MCP server configuration that handled the request. (#845)

[2.0.0] New McpTrafficListener API for custom traffic message listeners. Unlike built-in traffic logging, custom listeners are always invoked regardless of the traffic-logging.enabled configuration. See Custom Traffic Listeners. (#860)

[2.0.0] RawMessage#id() and RawMessage#method() methods to obtain the JSON-RPC message id and method name respectively. (#860)

[2.0.0] RawMessage#asPrettyString() method to get the formatted JSON message. (#893)

[2.0.0] New Cancellation#onCancelled(Consumer<Optional<String>>) method to register a callback that is executed when a cancellation of the current MCP request is requested by the client. The consumer receives the optional cancellation reason provided by the client. Unlike check(), this push-based approach does not require polling and is useful for cancelling async operations such as CompletableFutures. See Cancellation Callback. (#866)

[2.0.0] Per-request log level via _meta field io.modelcontextprotocol/logLevel for stateless clients.

[2.0.0] New MetaKey.LOG_LEVEL and MetaKey.PROTOCOL_VERSION constants.

[2.0.0] Multi Round-Trip Requests (MRTR) support for stateless clients. Server feature methods can throw InputRequiredException to request additional input (elicitation, sampling, or roots) from the client. The client retries the original request with the gathered input via InputResponses. See Multi Round-Trip Request (MRTR). (#824)

[2.0.0] New MrtrRequest interface implemented by Elicitation, Sampling, and Roots — provides isServerInitiatedRequestSupported(), inputResponses(), requestState(), and inputRequired() builder.

[2.0.0] HTTP GET (SSE stream) and DELETE (session termination) requests from stateless clients now return 405 Method Not Allowed.

[2.0.0] subscriptions/listen support for stateless clients. Replaces resources/subscribe/resources/unsubscribe for protocol version 2026-07-28+. Clients specify a notification filter (tools, prompts, resources list changes, and resource URI subscriptions) and receive matching notifications on the subscription stream. Supported on all transports (HTTP, WebSocket, stdio). See Subscription Notifications. (#824)

[2.0.0] CompletionStage is now supported as an async return type for tool, resource, prompt, and completion methods. It is treated identically to Uni at build time and converted to Uni at runtime. (#863)

[2.0.0] New @McpParamHeader annotation that mirrors tool parameters into Mcp-Param-{Name} HTTP response headers, enabling custom header propagation from tool parameters. See Implementing Tools. (#887)

[2.0.0] Initial support for Java MCP Annotations. Both the Quarkus-specific and the standard Java MCP annotations are supported during the transitional period. (#823)

[2.0.0] The OIDC security failure handler now always ends the HTTP response, fixing a connection leak when the request body is empty (e.g. SSE stream GET requests). (#853)

[1.13.0] The audience attribute of the @Resource.Annotations annotation and the Content.Annotations record now supports multiple roles. The annotation attribute type changed from Role to Role[] and the record field type changed from Role to List<Role>. A backwards-compatible constructor accepting a single Role is provided. (#788)

Elicitation URL mode: Servers can redirect users to an external URL for sensitive interactions instead of using form-based elicitation. (#711)

OptionalInt, OptionalLong, and OptionalDouble parameters: Primitive-specialized optional types are now supported in tool and resource method signatures. (#769)

Lazy SSE initialization for Streamable HTTP: SSE initialization is deferred until an API that requires it is invoked, removing the need for "transport hints" when adding tools programmatically. (#725)

Streamable HTTP auto-init reads _meta fields: The server now reads clientInfo and clientCapabilities from _meta on each request when auto-initialization is enabled. (#796)

FeatureInfo#method(): Exposes the declaring java.lang.reflect.Method, making it easier for filters to read method-level annotations. (#809)

OIDC security failure handler: Intercepts OIDC security exceptions on Streamable HTTP connections and converts them into JSON-RPC error responses. (#775)

quarkus-mcp-server-oidc extension: Adds a Vert.x failure handler for OIDC 403 Forbidden responses with WWW-Authenticate headers as recommended by the MCP authorization spec. (#780)

[1.13.0] The CLI adapter now derives MCP tool parameter names from Picocli @Option names instead of Java field names, and prefers the longest (most descriptive) option name. (#576)

[1.13.0] Build-time validation of resource template methods now correctly considers the name attribute of @ResourceTemplateArg instead of only matching against method parameter names. (#806)

[1.13.0] Custom Jackson serializers and deserializers are now honored for @ToolArg parameters of scalar and custom types, fixing incorrect schema generation and argument conversion. (#774)

[1.13.0] Client-side 4xx HTTP errors in Streamable HTTP are now logged at WARN level instead of ERROR, avoiding false production alerts. (#760)

[1.13.1] ToolInputGuardrail.ToolInputContext#setArguments() and ToolOutputGuardrail.ToolOutputContext#setResponse() no longer accept null, avoiding NPE for guarded no-argument tool calls. (backported from 2.0.x) (#819)

[1.13.1] The quarkus.mcp-server.metrics.enabled config property is now read at runtime. Since it defaults to false, applications that rely on MCP metrics without explicitly setting quarkus.mcp-server.metrics.enabled=true will stop collecting them. (backported from 2.0.x) (#844)

[1.13.1] Tracing spans now include the mcp.server.name attribute and respect per-server tracingEnabled configuration instead of only checking the default server. (backported from 2.0.x) (#845)

[1.13.1] The OIDC security failure handler now always ends the HTTP response, fixing a connection leak when the request body is empty (e.g. SSE stream GET requests). (backported from 2.0.x) (#853)

[1.13.1] When notifications/initialized arrives with an unknown session ID and auto-initialization is enabled, the server now returns 202 instead of an unsupported method error. (backported from 2.0.x) (#878)

[1.12.1] The audience attribute of the @Resource.Annotations annotation and the Content.Annotations record now supports multiple roles. The annotation attribute type changed from Role to Role[] and the record field type changed from Role to List<Role>. A backwards-compatible constructor accepting a single Role is provided. (backported from 1.13.x) (#788)

OpenTelemetry tracing: Distributed tracing for MCP server operations is now available when quarkus-opentelemetry is present, following the OpenTelemetry semantic conventions for MCP servers. Tracing overhead is minimal when OpenTelemetry is disabled. (#703)

Transport hints: A new API allows users to disable forced SSE initialization for programmatically added features, improving performance and simplifying request processing for tools that don’t require SSE. (#715)

Per-server feature name uniqueness: Feature names (tools, resources, prompts) are now enforced as unique per server configuration instead of globally, allowing different MCP servers to define features with the same name. (#627)

McpStdioTestClient: A new test utility for STDIO-based MCP servers, available through the McpAssured API. (#721)

[1.12.0] Empty ToolAnnotations title is no longer included in the JSON response, which caused some MCP clients (e.g. IBM Bob IDE) to not display available tools. (#748)

[1.12.0] McpLog#error(Throwable, String, Object…​) now correctly delegates to logger.errorf(…​) instead of logger.infof(…​). (#744)

[1.12.0] The server now sends a proper error response when a client subscribes to or unsubscribes from a non-existent resource URI, instead of throwing an uncaught exception. (#716)

[1.12.0] The Icon class is now registered for reflection, fixing missing icons in native mode. (#706)

[1.12.0] Streamable HTTP transport no longer uses McpMetadata in the hot path, reducing unnecessary allocations in larger deployments. (#722)

[1.12.1] Custom Jackson serializers and deserializers are now honored for @ToolArg parameters of scalar and custom types, fixing incorrect schema generation and argument conversion. (backported from 1.13.x) (#774)

Multiple @McpServer bindings: The @McpServer annotation is now repeatable, allowing a single feature (tool, resource, prompt) to be bound to multiple server configurations. A configuration flag is available to enable backward compatibility mode. (#595)

Schema validator module: A new module validates all MCP client requests and notifications against the relevant MCP specification JSON schema. (#17)

Tool name validation: An optional validation of tool names according to the MCP specification rules can be enabled via configuration. (#691)

DNS rebinding protection: Streamable HTTP servers bound to localhost now have DNS rebinding protection enabled by default, with options to configure or disable it. (#657)

Disable HTTP/WebSocket transport per server: Individual HTTP or WebSocket transports can now be disabled for a specific server configuration. (#633)

Elicitation schema builders: Convenient builder APIs for elicitation schema properties, including a new IntegerSchema. (#652)

InitialResponseInfo: A new API that provides access to the initialization response details in InitialCheck implementations. (#597)

Dev UI improvements: Aligned Dev UI screens with the Dev MCP look and feel, and added internationalization support. (#615)

[1.11.0] Pagination cursor is now based on a snapshot timestamp instead of name, making it resilient to concurrent modifications. (#672)

[1.11.0] Fixed a race condition in pagination. (#686)

[1.11.0] Elicitation and sampling now work correctly in native image. (#679)

[1.11.0] Elicitation schema properties are now encoded correctly. (#645)

[1.11.0] The AudioContent return type is now encoded correctly. (#644)

[1.11.0] Build-time validation of @Icons providers now correctly handles inner classes. (#649)

[1.11.0] Fixed incorrect validation of tool default value converters. (#619)

[1.11.1] The Icon class is now registered for reflection, fixing missing icons in native mode. (backported from 1.12.x) (#706)

[1.11.1] The server now sends a proper error response when a client subscribes to or unsubscribes from a non-existent resource URI, instead of throwing an uncaught exception. (backported from 1.12.x) (#716)

[1.11.1] Streamable HTTP transport no longer uses McpMetadata in the hot path, reducing unnecessary allocations in larger deployments. (backported from 1.12.x) (#722)

[1.10.6] The audience attribute of the @Resource.Annotations annotation and the Content.Annotations record now supports multiple roles. The annotation attribute type changed from Role to Role[] and the record field type changed from Role to List<Role>. A backwards-compatible constructor accepting a single Role is provided. (backported from 1.13.x) (#788)

Metrics support: Basic metrics for MCP server operations are now available when Micrometer is present. (#589)

FilterContext: Filters can now access additional metadata from the _meta field, the request ID, and the JSON-RPC method name. (#582)

Relaxed initialization phase: The initialization phase constraints have been relaxed to allow more flexible server startup. (#586)

Resource usability improvements: Improved resource content encoding with a default ResourceContentsEncoder implementation. (#601)

[1.10.1] Fixed icons parsing when icon theme is null. (#611)

[1.10.2] Fixed incorrect validation of tool default value converters. (backported from 1.11.x) (#619)

[1.10.3] Elicitation schema properties are now encoded correctly. (backported from 1.11.x) (#645)

[1.10.3] The AudioContent return type is now encoded correctly. (backported from 1.11.x) (#644)

[1.10.3] Pagination cursor is now based on a snapshot timestamp instead of name, making it resilient to concurrent modifications. (backported from 1.11.x) (#672)

[1.10.4] Elicitation and sampling now work correctly in native image. (backported from 1.11.x) (#679)

[1.10.4] Fixed a race condition in pagination. (backported from 1.11.x) (#686)

[1.10.4] The Icon class is now registered for reflection, fixing missing icons in native mode. (backported from 1.12.x) (#706)

[1.10.5] The server now sends a proper error response when a client subscribes to or unsubscribes from a non-existent resource URI, instead of throwing an uncaught exception. (backported from 1.12.x) (#716)

[1.10.5] Streamable HTTP transport no longer uses McpMetadata in the hot path, reducing unnecessary allocations in larger deployments. (backported from 1.12.x) (#722)

[1.10.6] Empty ToolAnnotations title is no longer included in the JSON response, which caused some MCP clients (e.g. IBM Bob IDE) to not display available tools. (backported from 1.12.x) (#748)

[1.10.6] McpLog#error(Throwable, String, Object…​) now correctly delegates to logger.errorf(…​) instead of logger.infof(…​). (backported from 1.12.x) (#744)

[1.10.6] Build-time validation of resource template methods now correctly considers the name attribute of @ResourceTemplateArg instead of only matching against method parameter names. (backported from 1.13.x) (#806)

Icons for tools, resources, resource templates, and prompts: Features can now have associated icons for display in MCP clients. (#561)

Tool input/output guardrails: A new mechanism to validate or transform tool inputs before execution and tool outputs before they are returned to the client. (#556)

Elicitation updates: Support for default values in all primitive types for elicitation schemas, and updates to ElicitResult and EnumSchema. (#552)

Server/client Implementation metadata: description, icons, and websiteUrl fields are now supported in the server and client Implementation records. (#548)

Dummy initialization for Streamable HTTP: Allows performing a dummy initialization to work around clients that do not properly initialize the MCP connection. (#519)

[1.9.0] Fixed missing $defs in generated inputSchema of DefaultSchemaGenerator, breaking support for recursive and complex types. (#540)

[1.9.0] Input validation errors are now returned as tool response errors instead of JSON-RPC protocol errors. (#537)

[1.9.0] Tool error messages no longer leak internal Java class names during argument validation. (#554)

[1.9.1] FilterContext introduced — filters can now access metadata from the meta field, request ID, and JSON-RPC method name. _(backported from 1.10.x) (#582)

[1.9.1] The initialization phase constraints have been relaxed to allow more flexible server startup. (backported from 1.10.x) (#586)

The quarkus-mcp-server-sse artifact has been renamed to quarkus-mcp-server-http. Relocations and configuration fallbacks are provided for backward compatibility. (#501)

Feature metadata: Additional metadata can now be attached to feature definitions (tools, resources, prompts) via the @MetaField annotation or the programmatic API. (#503)

WrapBusinessError#unless(): A new option to conditionally skip error wrapping for specific exception types. (#505)

Tool name max length configuration: A new quarkus.mcp.server.tools.name-max-length config property to enforce tool name length limits. (#484)

LangChain4j annotation support toggle: Support for LangChain4j @Tool/@P annotations can now be disabled via configuration. (#475)

[1.8.0] Fixed Tool method returning Uni with structuredContent enabled. (#480)

[1.8.0] Fixed resource template completion when the client does not include the template name in the reference. (#494)

[1.8.0] Hibernate Validator processor no longer wraps all validated methods, only MCP feature methods. (#507)

[1.8.1] Dummy initialization for Streamable HTTP is now available. (backported from 1.9.x) (#519)

WebSocket transport: A new WebSocket-based transport for MCP communication. (#449)

Custom input schema generation: It is now possible to customize the JSON schema generation for tool inputs. (#438)

[1.7.1] Fixed Tool method returning Uni with structuredContent enabled. (backported from 1.8.x) (#479)

[1.7.2] WebSocket endpoints now use InboundProcessingMode#CONCURRENT for proper concurrent message handling. (backported from 1.8.x) (#486)

[1.7.3] WebSocket transport now ensures MCP connection is initialized before a message is consumed. (#499)

[1.7.3] Fixed HTTP transport compatibility with Quarkus 3.30+. (#491)

[1.7.3] Fixed resource template completion when the client does not include the template name in the reference. (backported from 1.8.x) (#493)

Hibernate Validator integration: A new quarkus-mcp-server-hibernate-validator module integrates Hibernate Validator for automatic validation of tool inputs, with improved input schema generation for Jakarta Validation annotations. (#431)

Instructions support: Servers can now include instructions in the initialization response. (#408)

McpException in public API: McpException has been moved to the public API for use in feature implementations. (#424)

quarkus-mcp-server-bom: Introduced a Bill of Materials artifact for dependency management. (#395)

[1.6.0] The CDI request context is now activated during Notification.Type.INITIALIZED processing. (#425)

[1.6.1] Extracted ObjectMapperCustomizer from DefaultSchemaGenerator to fix a timing issue where ObjectMapper static initialization could conflict with SchemaGeneratorConfigCustomizer implementations that depend on runtime configuration. (#445)

The deprecated ResourceInfo#sendUpdate() method has been removed. (#384)

Elicitation support: Servers can request additional input from users during tool execution. (#362)

Structured tool output: Tools can now return structured content alongside text responses. (#379)

Resource annotations: Support for annotations on resources, resource templates, and contents (audience, priority, lastModified). (#383)

Resource links in tool calls and prompts: Tool responses and prompts can now include resource links. (#370)

_meta field support: Additional metadata represented by the _meta field is now supported. (#367)

Title for features: A human-readable title field for display in UI is now supported. (#367)

CompleteContext: A new context object for completion handlers. (#367)

RawMessage: Access to the raw JSON-RPC message is now available. (#366)

Programmatic API improvements: Interfaces are now used instead of records for arguments, and cancellation support has been added. (#365, #366)

quarkus-mcp-server-bom: [1.5.1] Introduced a Bill of Materials artifact for dependency management. (backported from 1.6.x) (#396)

Request cancellation: Support for cancelling in-progress MCP requests. (#332)

McpAssured testing API: A convenient new API for testing MCP servers in integration tests. (#316)

Subsidiary SSE streams: Streamable HTTP transport now supports subsidiary SSE streams. (#330)

Pagination control: Pagination can now be disabled by setting the page size to zero or a negative value. (#327)

[1.4.0] Fixed NPE with ToolAnnotations without a title. (#331)

[1.4.0] Fixed McpLog for the Streamable HTTP transport. (#309)

[1.4.0] The legacy SSE endpoint now returns HTTP 405 for POST requests. (#326)

[1.4.1] Cancellation support added to the programmatic API. (backported from 1.5.x) (#366)

Multiple MCP server configurations: A single application can now host multiple MCP server configurations with separate endpoints. (#285)

Tool annotations: Support for MCP tool annotations (readOnlyHint, destructiveHint, etc.). (#281)

InitialCheck: A new hook to inspect and optionally reject client connections during initialization. (#294)

InitialRequest#transport(): The transport type is now available in the initial request. (#296)

Connection idle timeout: A configurable idle timeout for MCP connections. (#291)

Roots and sampling timeouts: Configurable timeouts for roots and sampling operations. (#288)

SSE query parameters: Query parameters from the SSE endpoint URL are now available in the message endpoint. (#290)

Nested tool argument schema generation: Annotation-based schema generation now supports nested argument classes. (#298)

[1.3.0] Fixed CDI request context activation for batch processing. (#277)

[1.3.1] Fixed McpLog for the Streamable HTTP transport. (#309)

[1.3.1] Subsidiary SSE messages are now properly discarded when not applicable. (#312)

Streamable HTTP transport: Initial support for the Streamable HTTP transport as defined in the MCP specification. (#240)

Filters: A mechanism to determine the set of visible and accessible features per connection. (#257)

Default values for @ToolArg and @PromptArg: Annotations now support specifying default values. (#235)

Dev UI bearer token input: The Dev UI now includes an input field for bearer token authentication. (#220)

[1.2.1] Fixed CDI request context activation for batch processing. (#277)

[1.2.2] Fixed server info capabilities incorrectly reported for prompts, resources, and templates. (#284)

CLI adapter: An early draft of the CLI adapter for exposing CLI tools as MCP tools. (#166)

Sampling support: Initial support for the MCP sampling capability. (#214)

Roots support: Initial support for the MCP roots capability. (#212)

Progress API: A new API for reporting progress of long-running tool operations. (#195)

Notification hook: A new @Notification annotation for post-initialization logic. (#212)

Dev UI completion views: The Dev UI now includes views for completion APIs. (#210)

[1.1.0] Fixed tools number argument coercion. (#187)

[1.1.0] Fixed tools input schema generation for Optional<List<String>>. (#185)

[1.1.0] Fixed naming conflict for CLI commands with the same class name. (#196)

[1.0.1] Fixed list changed notifications for the STDIO transport. (#178)

[1.0.1] Fixed tools number argument coercion. (backported from 1.1.x) (#188)

[1.0.1] Fixed tools input schema generation for Optional<List<String>>. (backported from 1.1.x) (#186)