Testing Model Context Protocol (MCP) Tools in Spring AI

1. Overview

Model Context Protocol (MCP) is an open standard protocol that defines how a large language model (LLM) discovers and invokes external tools to extend its capabilities. MCP is a client-server architecture that allows the MCP client, usually an LLM integrated application, to interact with one or more MCP servers that expose tools for invocation.

Testing tools exposed by MCP servers are crucial to validate that they are correctly registered on MCP servers and are discoverable by MCP clients. Unlike LLM responses, which are non-deterministic, MCP tools behave deterministically because they’re just normal application code, which enables us to write automated tests to verify correctness.

In this tutorial, we’ll explore how to test MCP tools on MCP servers in Spring AI using different test strategies.

2. Maven Dependencies

We’ll test the MCP tools in a Spring Boot application. Hence, we must add the Spring AI MCP server dependency to our pom.xml:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server</artifactId>
    <version>1.1.2</version>
</dependency>

We’ll also require the Spring Boot Test dependency for our testing:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

3. Creating a Sample MCP Tool

In this section, we’ll implement a simple MCP tool using Spring AI and demonstrate different testing strategies.

First, let’s create a simple ExchangeRateService that uses a third-party open-source service, Frankfurter, to fetch the currency exchange rate using an HTTP GET request. This API requires a mandatory query parameter base:

@Service
public class ExchangeRateService {
    private static final String FRANKFURTER_URL = "https://api.frankfurter.dev/v1/latest?base={base}";

    private final RestClient restClient;

    public ExchangeRateService(RestClient.Builder restClientBuilder) {
        this.restClient = restClientBuilder.build();
    }

    public ExchangeRateResponse getLatestExchangeRate(String base) {
        if (base == null || base.isBlank()) {
            throw new IllegalArgumentException("base is required");
        }
        return restClient.get()
          .uri(FRANKFURTER_URL, base.trim().toUpperCase())
          .retrieve()
          .body(ExchangeRateResponse.class);
    }
}

The API response looks something similar to:

{
  "amount": 1,
  "base": "GBP",
  "date": "2026-03-06",
  "rates": {
    "AUD": 1.9034,
    "BRL": 7.0366,
    ......
  }
}

Thus, we create the following Java record to map the JSON response:

public record ExchangeRateResponse(double amount, String base, String date, Map<String, Double> rates) {
}

Now, let’s create an MCP tool that invokes the ExchangeRateService to return currency exchange rates based on the base currency.

The tool description explains what the parameter is for, such that MCP clients know what they should provide when calling it:

@Component
public class ExchangeRateMcpTool {
    private final ExchangeRateService exchangeRateService;

    public ExchangeRateMcpTool(ExchangeRateService exchangeRateService) {
        this.exchangeRateService = exchangeRateService;
    }

    @McpTool(description = "Get latest exchange rates for a base currency")
    public ExchangeRateResponse getExchangeRate(
        @McpToolParam(description = "Base currency code, e.g. GBP, USD", required = true) String base) {
        return exchangeRateService.getLatestExchangeRate(base);
    }
}

4. Unit Test

We could verify the ExchangeRateMcpTool logic in isolation by unit test. Therefore, we mock the external dependency so that we can provide a mocked response.

The verification process is fairly simple to validate that the service gets invoked correctly, and also the response is returned as expected:

class ExchangeRateMcpToolUnitTest {
    @Test
    void whenBaseIsNotBlank_thenGetExchangeRateShouldReturnResponse() {
        ExchangeRateService exchangeRateService = mock(ExchangeRateService.class);
        ExchangeRateResponse expected = new ExchangeRateResponse(1.0, "GBP", "2026-03-08",
          Map.of("USD", 1.27, "EUR", 1.17));
        when(exchangeRateService.getLatestExchangeRate("gbp")).thenReturn(expected);

        ExchangeRateMcpTool tool = new ExchangeRateMcpTool(exchangeRateService);
        ExchangeRateResponse actual = tool.getExchangeRate("gbp");

        assertThat(actual).isEqualTo(expected);
        verify(exchangeRateService).getLatestExchangeRate("gbp");
    }
}

5. Creating an MCP Test Client

If we want to test the MCP tools end-to-end, we could create an MCP client that connects to the MCP server.

HTTP-based MCP servers expose different endpoints depending on the protocol configuration property spring.ai.mcp.server.protocol in the application.yml. Spring AI uses the SSE by default if we don’t set the property explicitly:

In addition to the different endpoints, each protocol requires a different McpClientTransport instance to create the McpSyncClient.

Since Spring AI does not provide a factory class that automatically creates the client based on the protocol, we create a test component, TestMcpClientFactory, handling the McpSyncClient creation, to simplify our testing:

@Component
public class TestMcpClientFactory {
    private final String protocol;

    public TestMcpClientFactory(@Value("${spring.ai.mcp.server.protocol:sse}") String protocol) {
        this.protocol = protocol;
    }

    public McpSyncClient create(String baseUrl) {
        String resolvedProtocol = protocol.trim().toLowerCase();
        return switch (resolvedProtocol) {
            case "sse" -> McpClient.sync(HttpClientSseClientTransport.builder(baseUrl)
              .sseEndpoint("/sse")
              .build()
            ).build();
            case "streamable" -> McpClient.sync(HttpClientStreamableHttpTransport.builder(baseUrl)
              .endpoint("/mcp")
              .build()
            ).build();
            default -> throw new IllegalArgumentException("Unknown MCP protocol: " + protocol);
        };
    }
}

We support the SSE and streamable protocol only in our factory class to demonstrate the idea.

6. Verifying Tool Registration

The MCP server exposes an HTTP endpoint to list all available tools that MCP clients can invoke. As such, we could initialize an MCP client to verify the tool’s registration on the MCP server.

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class ExchangeRateMcpToolIntegrationTest {
    @LocalServerPort
    private int port;

    @Autowired
    private TestMcpClientFactory testMcpClientFactory;

    @MockBean
    private ExchangeRateService exchangeRateService;

    private McpSyncClient client;

    @BeforeEach
    void setUp() {
        client = testMcpClientFactory.create("http://localhost:" + port);
        client.initialize();
    }

    @AfterEach
    void cleanUp() {
        client.closeGracefully();
    }
}

Once we initialize an MCP client, we invoke the client listTools() method to find out all tools that an MCP server has registered:

@Test
void whenMcpClientListTools_thenTheToolIsRegistered() {
    boolean registered = client.listTools().tools().stream()
      .anyMatch(tool -> Objects.equals(tool.name(), "getLatestExchangeRate"));
    assertThat(registered).isTrue();
}

The test returns a list of registered tools, and we assert that getLatestExchangeRate is one of them to confirm successful registration.

7. Testing Tool Invocation

In addition, we could also verify the MCP tool by invoking it from an MCP client. We mock the ExchangeRateService in this test to avoid making a genuine HTTP call to the Frankfurter API.

The invocation flow includes discovering the tools from the MCP server, building a CallToolRequest with all required arguments, and calling it to obtain the response from the server:

@Test
void whenMcpClientCallTool_thenTheToolReturnsMockedResponse() {
    when(exchangeRateService.getLatestExchangeRate("GBP")).thenReturn(
      new ExchangeRateResponse(1.0, "GBP", "2026-03-08", Map.of("USD", 1.27))
    );

    McpSchema.Tool exchangeRateTool = client.listTools().tools().stream()
      .filter(tool -> "getLatestExchangeRate".equals(tool.name()))
      .findFirst()
      .orElseThrow();

    String argumentName = exchangeRateTool.inputSchema().properties().keySet().stream()
      .findFirst()
      .orElseThrow();

    McpSchema.CallToolResult result = client.callTool(
      new McpSchema.CallToolRequest("getLatestExchangeRate", Map.of(argumentName, "GBP"))
    );

    assertThat(result).isNotNull();
    assertThat(result.isError()).isFalse();
    assertTrue(result.toString().contains("GBP"));
}

The assertions ensure the tool call returns a valid response without errors.

8. Conclusions

In this article, we created a sample MCP server tool, validated its correctness, ensured the MCP server registered with it, and tested the tool invocation via an MCP client.

With both unit tests and integration tests in place, we can be confident that the tool is working correctly and is exposed properly so that MCP clients can invoke it.