McpClient CallToolRequest arguments are received as null on the server side

[herbertkb]

I'm trying to create a very simple Spring AI MCP Server and am having trouble with a basic unit test.

@Component
public class CountEsTool {
    Logger log = LoggerFactory.getLogger(CountEsTool.class);

    @McpTool(name = "countEs", description = "Count the number of the letter 'e' in a word.")
    public int countEs(
            @McpToolParam(description = "word", required = true) String word) {
        log.info("word={}", word);

        int count = (int) List.of(word.split("")).stream()
                    .filter(s -> s.equalsIgnoreCase("e"))
                    .count();

        log.info("word={}, count={}", word, count);
        return count;
    }
}

If I run it with mvn spring-boot:run and test it with the MCP Inspector, it works fine.

But if I try to unit test it in the same way as shown in this blog
and this example,
the argument received on the server side in the tool method is null.

@Test
void toolResult() {

    var client = McpClient
            .sync(HttpClientStreamableHttpTransport.builder("http://localhost:" + port).build())
            .build();

    client.initialize();

    assertEquals(2, client.callTool(new CallToolRequest("countEs", Map.of("word", "elephant"))));

    client.closeGracefully();
}

com.example.reproducer.CountEsTool       : word=null

The reproducer repo for my problem is here: https://github.com/herbertkb/reproducer-spring-ai-mcp-server/tree/main

[weilhuang]

@herbertkb enable maven compiler parameter names with <parameters>true</parameters> or -parameters

[MILLERMARRU]

The root cause is that Java bytecode does not retain method parameter names by default — only the types are preserved. Without parameter names, Spring AI's MCP framework cannot map the incoming JSON arguments to your @Tool-annotated method parameters by name, so they arrive as null.

Fix for Maven

Add <parameters>true</parameters> to the Maven compiler plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <parameters>true</parameters>
        <source>21</source>
        <target>21</target>
    </configuration>
</plugin>

Fix for Gradle

// build.gradle
tasks.withType(JavaCompile).configureEach {
    options.compilerArgs << '-parameters'
}

Or in Kotlin DSL:

// build.gradle.kts
tasks.withType<JavaCompile>().configureEach {
    options.compilerArgs.add("-parameters")
}

Fix for Spring Boot projects specifically

If you use spring-boot-starter-parent as your parent POM, Spring Boot 3.2+ already sets <parameters>true</parameters> by default — but only if you're using the parent. If you're using spring-boot-dependencies as a BOM (without the parent), you must add the flag yourself.

Why the MCP Inspector works but unit tests don't

MCP Inspector invokes your tool through the full MCP protocol stack, which includes an additional layer that resolves argument names differently. Unit tests calling McpClient directly hit the Java reflection layer without that resolution, so the missing parameter names become visible.

Verify the fix worked

After recompiling, you can confirm parameter names are preserved:

Method method = MyTool.class.getDeclaredMethod("myToolMethod", String.class);
System.out.println(method.getParameters()[0].getName()); // prints "word" instead of "arg0"

If it prints arg0 (or arg1, etc.) the flag is still missing. If it prints your actual parameter name, you're good.