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)

[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.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)