Tools with McpSyncServerExchange/McpSyncRequestContext parameters are silently ignored in stateless mode

[ashakirin]

Problem

The McpSyncServerExchange or McpSyncRequestContext are not supported in stateless mode, they make sense only with sessions.
However, when using stateless mode (spring.ai.mcp.server.protocol=stateless), tool methods with special parameters like McpSyncServerExchange or McpSyncRequestContext are silently ignored - the tool is not registered and never called. There's no warning or error at startup.

Steps to reproduce:

1. Configure stateless MCP server:
   spring.ai.mcp.server.protocol=stateless

2. Create a tool with special parameter:

@McpTool(description = "Get items")
public List<Item> getItems(McpSyncServerExchange exchange) {
    return items;
}

3. Configure client with streamable-http:
   spring.ai.mcp.client.streamable-http.connections.server1.url=http://localhost:8081

4. Call the tool - it's not found/registered. No warning in logs.

unicorn-mcp-server.zip
unicorn-spring-ai-agent.zip

Current behavior

Tool is silently not registered.

Expected behavior (options)

1. Preferred: Register the tool and invoke it with null injected for unsupported parameters. Let the developer handle the null case:

java

   @McpTool(description = "Get items")
   public List<Item> getItems(McpSyncServerExchange exchange) {
       if (exchange != null) {
           // stateful-specific logic
       }
       return items;
   }

2. Alternative: Log a clear warning at startup:
   WARN: Tool 'getItems' uses McpSyncServerExchange which is not available in stateless mode.
   Tool will not be registered. Remove the parameter or switch to stateful mode.

The current silent behavior makes debugging difficult - developers don't know why their tool isn't being called.

Environment

• Spring AI version: 1.1.2
• Spring Boot version: 3.5.3
• Java version: 25

[chanani]

Hi @ashakirin ! I'd like to work on this issue.

Problem

Tools with McpSyncServerExchange or McpSyncRequestContext parameters are silently ignored in stateless mode, as these require session-based connections.

Proposed Solution

Add fail-fast validation during tool registration:

throw new IllegalStateException(
    String.format(
        "Tool '%s' cannot use %s in stateless mode. " +
        "Use McpTransportContext or enable session-based protocol.",
        method.getName(), 
        paramType.getSimpleName()
    )
);

Will validate: McpSyncServerExchange, McpAsyncServerExchange, McpSyncRequestContext, McpAsyncRequestContext.

I'll add tests and documentation. Does this approach work?