MCP Server: Gap Analysis & Implementation Plan (Spec 2025-11-25) #248

jmesnil · 2026-05-07T08:53:43Z

jmesnil
May 7, 2026
Maintainer

The latest MCP Spec is at https://modelcontextprotocol.io/specification/2025-11-25 and there is some work to be done to support its Server features (provided by the mcp-server layer of the AI feature pack).

I asked Claude to generate a plan to fill the gaps and implement the remaining server features.
Please find below its output for discussion. I'm planning to convert the different tasks in GitHub issues so that we can start working on it:

Context

The WildFly MCP feature pack implements an MCP server against protocol version 2025-03-26. The latest spec (2025-11-25) introduces several new fields and features. This plan identifies every gap in the server-side implementation and proposes concrete steps to close them. MCP Client features, experimental Tasks, and OAuth 2.1 are out of scope but noted for future work.

Gap Summary

#	Gap	Priority	Spec Section
1	Protocol version still `2025-03-26`	High	Lifecycle
2	Tool annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) not emitted in `tools/list`	High	Tools
3	Tool `title` not emitted in `tools/list`	Medium	Tools
4	Tool `outputSchema` + `structuredContent` not supported	Medium	Tools
5	`isError` field not set in tool error results	Medium	Tools
6	Prompt `title` not emitted in `prompts/list`	Medium	Prompts
7	Resource `title` and `size` not emitted in `resources/list`	Medium	Resources
8	Resource `annotations` (`audience`, `priority`, `lastModified`) not emitted	Medium	Resources
9	Resource template `title` not emitted in `resources/templates/list`	Medium	Resources
10	Resource template `annotations` not emitted	Medium	Resources
11	`listChanged` not declared in capabilities for tools/prompts/resources	Medium	Capabilities
12	`notifications/tools/list_changed` not sent	Low	Tools
13	`notifications/prompts/list_changed` not sent	Low	Prompts
14	`notifications/resources/list_changed` not sent	Low	Resources
15	`notifications/resources/updated` not sent (subscribe is a no-op)	Low	Resources
16	Progress notifications (`notifications/progress`) not supported	Medium	Utilities
17	Logging notifications (`notifications/message`) not sent to clients	Medium	Logging
18	Log level not stored per connection	Medium	Logging
19	`MCP-Protocol-Version` header not validated on HTTP requests	Medium	Transport
20	AudioContent not handled by ContentMapper	Low	Content
21	ResourceLink content type not supported	Low	Content
22	Deferred: Tasks (experimental)	Future	Tasks
23	Deferred: OAuth 2.1 Protected Resource Metadata	Future	Auth

Implementation Plan

Step 1: Update protocol version

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/MCPMessageHandler.java

Change line 55:

this.serverInfo.put("protocolVersion", "2025-03-26");

to:

this.serverInfo.put("protocolVersion", "2025-11-25");

Step 2: Extend metadata records to carry new fields

File: wildfly-mcp/injection/src/main/java/org/wildfly/extension/mcp/injection/tool/MethodMetadata.java

Add new fields to the record:

title (String) -- human-readable display name for tools, prompts, resources, resource templates
size (int, default -1) -- resource size in bytes
readOnlyHint (Boolean) -- tool annotation
destructiveHint (Boolean) -- tool annotation
idempotentHint (Boolean) -- tool annotation
openWorldHint (Boolean) -- tool annotation
audience (String) -- resource annotation (e.g. "user", "assistant")
priority (double) -- resource annotation
lastModified (String) -- resource annotation (ISO 8601)
structuredContent (boolean) -- whether tool returns structured content
outputSchemaType (String) -- class name for output schema generation

To avoid breaking the record constructor signature everywhere, introduce a builder or a new extended record. The cleanest approach: add the fields to MethodMetadata with default values by using a secondary constructor or converting to a class with a builder. Since MethodMetadata is used in ~10 places, I recommend keeping the record but adding the new fields at the end with defaults.

File: wildfly-mcp/injection/src/main/java/org/wildfly/extension/mcp/injection/tool/MCPFeatureMetadata.java

No changes needed -- it delegates to MethodMetadata for new fields.

Step 3: Extract new annotation fields during deployment scanning

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/deployment/MCPServerDependencyProcessor.java

3a. `processTools()` -- extract from `@Tool` annotation:

title from annotation.value("title")
annotations nested annotation: readOnlyHint, destructiveHint, idempotentHint, openWorldHint
structuredContent from annotation.value("structuredContent")
outputSchema.from class name

3b. `processPrompts()` -- extract from `@Prompt` annotation:

title from annotation.value("title")

3c. `processResources()` -- extract from `@Resource` annotation:

title from annotation.value("title")
size from annotation.value("size")
annotations nested annotation: audience, priority, lastModified

3d. `processResourceTemplates()` -- extract from `@ResourceTemplate` annotation:

title from annotation.value("title")
annotations nested annotation: audience, priority, lastModified

Step 4: Emit new fields in protocol responses

4a. `tools/list` response

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/ToolMessageHandler.java -- toolsList()

For each tool, add to the JSON response:

"title" if non-empty
"annotations" object with readOnlyHint, destructiveHint, idempotentHint, openWorldHint (only include fields that differ from spec defaults)
"outputSchema" if structuredContent is true -- generate schema from the return type

4b. `tools/call` response

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/ToolMessageHandler.java -- toolsCall()

If structuredContent is true on the tool metadata: serialize the return value as JSON into a structuredContent field, and also include a TextContent fallback in content[]
When a tool throws an exception caught by the handler: set "isError": true in the result alongside the error content

4c. `prompts/list` response

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/PromptMessageHandler.java -- promptsList()

Add "title" if non-empty.

4d. `resources/list` response

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/ResourceMessageHandler.java -- resourcesList()

Add "title", "size" (if >= 0), and "annotations" (audience/priority/lastModified) if non-default.

4e. `resources/templates/list` response

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/ResourceTemplateMessageHandler.java -- resourceTemplatesList()

Add "title" and "annotations" if non-default.

Step 5: Declare `listChanged` in capabilities

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/MCPMessageHandler.java

Update the capabilities declaration:

capabilities.put("tools", Map.of("listChanged", true));
capabilities.put("prompts", Map.of("listChanged", true));
capabilities.put("resources", Map.of("subscribe", true, "listChanged", true));

This declares that the server may send list-changed notifications. The actual sending mechanism is Step 8.

Step 6: Implement per-connection log level and logging notifications

6a. Store log level on connection

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/api/MCPConnection.java

Add McpLog.LogLevel logLevel() and void setLogLevel(McpLog.LogLevel level) methods.

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/ServerSentEventResponder.java

Add a logLevel field (default: McpLog.LogLevel.WARNING), implement the new methods.

6b. Update `setLogLevel` handler

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/MCPMessageHandler.java -- setLogLevel()

Store the level on the connection: connection.setLogLevel(logLevel).

6c. Provide `McpLog` for injection into tools

Create an injectable McpLog implementation that tools can receive (similar to ElicitationSender). When a tool calls log.info("message"), the server sends a notifications/message notification to the client via the responder, if the level is >= the connection's configured level.

New file: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/McpLogImpl.java

This wraps the connection's responder and sends:

{"jsonrpc": "2.0", "method": "notifications/message", "params": {"level": "info", "logger": "toolName", "data": "message"}}

Update ToolMessageHandler.buildArguments() to inject McpLog parameters (same pattern as ElicitationSender).

Step 7: Implement progress notifications

7a. Extract `progressToken` from `tools/call` request

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/ToolMessageHandler.java -- toolsCall()

Read params._meta.progressToken from the message. If present, create a ProgressTracker (from SDK) and make it available for injection.

7b. Provide `Progress` for injection into tools

Similar to ElicitationSender and McpLog, tools can declare a Progress parameter. The implementation sends notifications/progress messages to the client.

Update ToolMessageHandler.buildArguments() to inject Progress parameters.

Update MCPServerDependencyProcessor.processTools() to recognize Progress parameter type (same as ElicitationSender).

Step 8: Implement list-changed and resource-updated notifications

8a. Infrastructure for sending notifications to all connections

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/api/ConnectionManager.java

Add a method to broadcast a notification to all active connections:

void broadcast(JsonObject notification);

8b. Send `notifications/tools/list_changed`, `notifications/prompts/list_changed`, `notifications/resources/list_changed`

These would be triggered when the registry changes (e.g., hot deployment of a new WAR). The WildFly deployment processor could fire these on deploy/undeploy. This is inherently tied to WildFly's deployment lifecycle.

For now, provide the infrastructure (broadcast method) and wire it into the deployment lifecycle hooks.

8c. Resource subscription tracking and `notifications/resources/updated`

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/ResourceMessageHandler.java

Currently resourcesSubscribe and resourcesUnsubscribe are no-ops. Add actual subscription tracking:

Maintain a Map<String, Set<MCPConnection>> of URI -> subscribed connections
On resources/subscribe: add the connection to the set
On resources/unsubscribe: remove the connection
Provide a method notifyResourceUpdated(String uri) that sends notifications/resources/updated to all subscribed connections

This method would be called by application code (via a CDI event or API) when a resource changes.

Step 9: Validate `MCP-Protocol-Version` header

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/StreamableHttpHandler.java

After initialization (when a session ID is already set), validate the MCP-Protocol-Version header on incoming POST requests. If the header is present and doesn't match the negotiated version, return HTTP 400.

Step 10: Handle AudioContent and ResourceLink in ContentMapper

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/api/ContentMapper.java

Add handling for AudioContent (from SDK model) in processResultAsText()
The SDK model already has AudioContent.class -- just ensure it's recognized as a ContentBlock

ResourceLink is not yet in the SDK model (mcp-model-1.0.0-Beta1), so this can be deferred until the SDK adds it.

Step 11: Tool error results with `isError: true`

File: wildfly-mcp/subsystem/src/main/java/org/wildfly/extension/mcp/server/ToolMessageHandler.java -- toolsCall() Runnable

When a tool invocation throws an exception (caught in the catch blocks), instead of sending a JSON-RPC error, send a successful result with isError: true:

{"content": [{"type": "text", "text": "Error: ..."}], "isError": true}

This distinguishes protocol errors (JSON-RPC error response) from tool execution errors (result with isError flag), per the spec.

Files to Modify (Summary)

File	Changes
`injection/tool/MethodMetadata.java`	Add `title`, `size`, tool annotations, resource annotations, `structuredContent`, `outputSchemaType` fields
`deployment/MCPServerDependencyProcessor.java`	Extract new annotation fields from `@Tool`, `@Prompt`, `@Resource`, `@ResourceTemplate`
`server/MCPMessageHandler.java`	Update protocol version, declare `listChanged` in capabilities, store log level on connection
`server/ToolMessageHandler.java`	Emit `title`, `annotations`, `outputSchema` in tools/list; handle `structuredContent` + `isError` in tools/call; inject `McpLog` and `Progress`
`server/PromptMessageHandler.java`	Emit `title` in prompts/list
`server/ResourceMessageHandler.java`	Emit `title`, `size`, `annotations` in resources/list; implement subscription tracking
`server/ResourceTemplateMessageHandler.java`	Emit `title`, `annotations` in resources/templates/list
`server/StreamableHttpHandler.java`	Validate `MCP-Protocol-Version` header
`server/ServerSentEventResponder.java`	Add `logLevel` field and accessors
`api/MCPConnection.java`	Add `logLevel()`/`setLogLevel()` methods
`api/ConnectionManager.java`	Add `broadcast()` method
`api/ContentMapper.java`	Handle AudioContent
New: `server/McpLogImpl.java`	Injectable McpLog that sends `notifications/message` to clients

Out of Scope (Future Work)

Tasks (experimental): The 2025-11-25 spec introduces task-augmented requests (tasks/get, tasks/result, tasks/list, tasks/cancel). Deferred for a later stage.
OAuth 2.1: The spec defines the server as an OAuth 2.1 resource server with Protected Resource Metadata (RFC 9728). The current OIDC support is sufficient for now; full OAuth 2.1 compliance deferred.
Icons: The spec supports icons arrays on Tool, Prompt, Resource, ResourceTemplate, and serverInfo. The SDK annotation @Tool(icon=...) supports a single icon. Supporting this is straightforward but cosmetic -- defer unless needed.
Batch JSON-RPC: The Streamable HTTP transport should support receiving an array of JSON-RPC messages in a single POST. Currently only single objects are handled.
SSE Resumability: Supporting Last-Event-ID for SSE reconnection. The lastEventId counter exists but isn't used for replay.
Origin header validation: DNS rebinding protection. Important for production but orthogonal to protocol feature compliance.

Verification

Unit tests: Extend existing tests in testsuite/mcp/ to verify new fields appear in tools/list, prompts/list, resources/list, resources/templates/list responses
Integration test: Create a tool with @Tool(title="...", annotations=@Annotations(readOnlyHint=true)) and verify the response includes the new fields
Structured content test: Create a tool with @Tool(structuredContent=true) returning a POJO and verify structuredContent + outputSchema in the response
Logging test: Call logging/setLevel then trigger a tool that logs via McpLog, verify notifications/message is received
Progress test: Call a tool with _meta.progressToken, verify notifications/progress is sent
Protocol version: Verify initialize response returns "protocolVersion": "2025-11-25"

jmesnil · 2026-05-07T09:22:52Z

jmesnil
May 7, 2026
Maintainer Author

I have created an "epic" in #249 to track the implementation of the server features for MCP 2025-11-25 and will convert this plan into subissues

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

MCP Server: Gap Analysis & Implementation Plan (Spec 2025-11-25) #248

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Uh oh!

MCP Server: Gap Analysis & Implementation Plan (Spec 2025-11-25) #248

Uh oh!

jmesnil May 7, 2026 Maintainer

Context

Gap Summary

Implementation Plan

Step 1: Update protocol version

Step 2: Extend metadata records to carry new fields

Step 3: Extract new annotation fields during deployment scanning

3a. processTools() -- extract from @Tool annotation:

3b. processPrompts() -- extract from @Prompt annotation:

3c. processResources() -- extract from @Resource annotation:

3d. processResourceTemplates() -- extract from @ResourceTemplate annotation:

Step 4: Emit new fields in protocol responses

4a. tools/list response

4b. tools/call response

4c. prompts/list response

4d. resources/list response

4e. resources/templates/list response

Step 5: Declare listChanged in capabilities

Step 6: Implement per-connection log level and logging notifications

6a. Store log level on connection

6b. Update setLogLevel handler

6c. Provide McpLog for injection into tools

Step 7: Implement progress notifications

7a. Extract progressToken from tools/call request

7b. Provide Progress for injection into tools

Step 8: Implement list-changed and resource-updated notifications

8a. Infrastructure for sending notifications to all connections

8b. Send notifications/tools/list_changed, notifications/prompts/list_changed, notifications/resources/list_changed

8c. Resource subscription tracking and notifications/resources/updated

Step 9: Validate MCP-Protocol-Version header

Step 10: Handle AudioContent and ResourceLink in ContentMapper

Step 11: Tool error results with isError: true

Files to Modify (Summary)

Out of Scope (Future Work)

Verification

Replies: 1 comment

Uh oh!

jmesnil May 7, 2026 Maintainer Author

jmesnil
May 7, 2026
Maintainer

3a. `processTools()` -- extract from `@Tool` annotation:

3b. `processPrompts()` -- extract from `@Prompt` annotation:

3c. `processResources()` -- extract from `@Resource` annotation:

3d. `processResourceTemplates()` -- extract from `@ResourceTemplate` annotation:

4a. `tools/list` response

4b. `tools/call` response

4c. `prompts/list` response

4d. `resources/list` response

4e. `resources/templates/list` response

Step 5: Declare `listChanged` in capabilities

6b. Update `setLogLevel` handler

6c. Provide `McpLog` for injection into tools

7a. Extract `progressToken` from `tools/call` request

7b. Provide `Progress` for injection into tools

8b. Send `notifications/tools/list_changed`, `notifications/prompts/list_changed`, `notifications/resources/list_changed`

8c. Resource subscription tracking and `notifications/resources/updated`

Step 9: Validate `MCP-Protocol-Version` header

Step 11: Tool error results with `isError: true`

jmesnil
May 7, 2026
Maintainer Author