MCP Logging in Spring AI

1. Overview

MCP (Model Context Protocol) is an open-source, JSON-RPC-based (JavaScript Object Notation-Remote Procedure Call) protocol. It provides a standardized way for AI (Artificial Intelligence) applications to connect to external tools, services, and data sources. Therefore, it eliminates the need for custom integrations.

Logging in MCP gives servers a standardized way to send structured, severity-tagged log messages to clients. This might be especially useful while debugging an MCP server.

In this tutorial, we’ll discuss MCP logging in Spring AI. Firstly, we’ll give brief information about MCP logging. Then, we’ll discuss logging both in an MCP server and client.

2. Basic Information About MCP Logging

An MCP server pushes log messages to an MCP client as notifications/message JSON-RPC notifications. This one-way notification message from the server to the client contains a severity level, an optional logger name, and the log message.

The MCP client can send the logging/setLevel JSON-RPC request to the server to configure log-message verbosity. Consequently, the server only sends log messages that meet or exceed the requested severity level. The client can dynamically adjust log verbosity by issuing another logging/setLevel.

An important caveat is that the July 2026 spec revision (2026-07-28) formally deprecated the logging feature along with other features, in favor of newer mechanisms. However, existing implementations will continue to work for at least a year. It’s recommended that newer implementations migrate to using stderr (standard error) for the stdio (standard input/output) transport and OpenTelemetry for structured observability.

3. Maven Dependencies

Let’s start by adding the necessary Maven dependencies to our pom.xml:

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

The MCP client starter dependency enables a Spring AI application to connect to MCP servers and use their tools. On the other hand, we use the MCP server starter dependency to turn a Spring Boot application into an MCP server. The dependency lets the application expose tools and resources to other LLM (Large Language Model) applications.

We use the Spring AI BOM (Bill of Materials) to avoid the risk of version conflicts between Spring AI dependencies:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Therefore, we don’t have to specify the versions of MCP starters explicitly.

4. Logging on the Server Side

Let’s start by discussing logging in the MCP server. The server we’ll discuss exposes a tool that an MCP client can run whenever a user requests a password strength evaluation.

4.1. Tool Implementation

The PasswordStrengthService class holds the actual tool implementation, the checkStrength() method exposed by the @McpTool server annotation. It’s a Spring bean since it’s annotated with @Service:

@Service
public class PasswordStrengthService {
    ...
    @McpTool(name = "check_password_strength", 
      description = "Evaluates password strength and returns a score with recommendations.")
    public PasswordStrengthResult checkStrength(
        @McpToolParam(description = "The password to evaluate", required = true) String password,
	  McpSyncRequestContext ctx) {
        ...
    }
}

The checkStrength() method, i.e., the tool, takes two parameters. The first one is the password to be evaluated. The tool checks whether the password is at least 12 characters long, contains at least one uppercase letter, and contains at least one digit. It also checks whether the password matches common passwords such as “123456” or “qwerty”.

The second parameter is of type McpSyncRequestContext, which we’ll use for logging. The Spring AI MCP annotations framework injects it automatically. An MCP server uses an object of this special type to log messages. It doesn’t write the log messages directly to the stdout (standard output) stream. Instead, it packages them into standard MCP protocol notification payloads and sends them over the transport layer, like stdio or SSE (Server-Sent Events), to the client. We use the stdio transport in our example.

The McpSyncRequestContext interface provides several logging methods such as debug(), info(), warn(), and error(). For example, if the password matches a common password, we log it using the ctx.error(“Password found in common-password list”) call in our example:

if (COMMON_PASSWORDS.contains(password.toLowerCase())) {
    ctx.error("Password found in common-password list");
    issues.add("commonly used");
}

Therefore, on the server side, we can choose the logging level per call.

4.2. MCP Server

The McpLoggingServerApplication class provides the Spring Boot entry point for the MCP server process:

@SpringBootApplication
public class McpLoggingServerApplication {

    public static void main(String[] args) {
        SpringApplication.run(McpLoggingServerApplication.class, args);
    }
}

When the server process starts, Spring AI’s MCP server auto-configuration scans for methods annotated with @McpTool. Then, it registers and exposes the detected tools over the stdio transport. A connected client can therefore discover and call them.

We need to enable the stdio transport in the server’s configuration file, application-server.properties:

spring.ai.mcp.server.stdio=true

Besides, we must prevent the server application from printing logs to stdout. The stdout stream is dedicated to exchanging the MCP protocol’s JSON-RPC messages:

spring.main.web-application-type=none

spring.main.banner-mode=off

logging.pattern.console=

Setting spring.main.web-application-type to none prevents Spring Boot from starting a web server. This means that no web-related startup logs are emitted. Setting spring.main.banner-mode to off suppresses the Spring Boot banner that is normally printed to stdout on startup. Finally, logging.pattern.console= strips the pattern formatting in logs.

5. Handling Logs on the Client Side

Let’s now discuss logging in the MCP client.

5.1. MCP Client

Similar to McpLoggingServerApplication, the McpLoggingClientApplication class provides the Spring Boot entry point for the MCP client process:

@SpringBootApplication
public class McpLoggingClientApplication {

    public static void main(String[] args) {
        SpringApplication.run(McpLoggingClientApplication.class, args);
    }
}

On startup, the client boot starter reads the spring.ai.mcp.client.stdio.connections.* properties in the application-client.properties file and launches the server as a child process. For example, the configuration property spring.ai.mcp.client.stdio.connections.password-strength-logging-server.args specifies which arguments the client passes to the server when spawning it. The stdio segment in these configuration properties selects the stdio transport for the named connection, password-strength-logging-server.

The spring.ai.mcp.client.type=SYNC configuration property selects the synchronous client implementation, i.e., McpSyncClient. Therefore, client calls block until the server responds.

5.2. Logging Handler

To capture the notification logs sent by the server on the client side, we have to use the @McpLogging client annotation:

@Component public class PasswordStrengthMcpClientHandlers {
    ...
    @McpLogging(clients = "password-strength-logging-server")
    public void handleLoggingMessage(McpSchema.LoggingMessageNotification notification) {
        LOGGER.info("Received server logging notification [{}]: {}"
          , notification.level(), notification.data());
        receivedLogs.add(notification);
    }
    ...
} 

@McpLogging is a Spring AI MCP annotation that registers a method as a notification handler for a specific MCP client connection. The handler’s name is handleLoggingMessage() in our example. The connection’s name is password-strength-logging-server, which matches the ID configured for the stdio connection in the server’s configuration file, application-server.properties:

spring.ai.mcp.server.name= password-strength-logging-server

The handler’s parameter, notification, is the deserialized payload of an MCP logging notification. Its level() method prints the log severity (e.g., DEBUG, ERROR). Its data() method, on the other hand, contains the actual log sent by the server.

We’ve already seen that the server can choose the logging level per call since the McpSyncRequestContext interface provides several logging methods such as warn() and error(). However, the client can set the server’s logging level. Therefore, the server can filter out notification messages at a specific level and below:

mcpSyncClient.setLoggingLevel(McpSchema.LoggingLevel.WARNING);

Here, this client-side call instructs the server to filter out anything below WARNING. For example, the server doesn’t send notifications with DEBUG or INFO levels.

6. An Example

When we send “weak“ as the password to be evaluated by the MCP server, the logging handler prints the following list of log messages:

Received server logging notification [WARNING]: Password shorter than recommended 12 characters
Received server logging notification [WARNING]: Password missing uppercase letters
Received server logging notification [WARNING]: Password missing digits
Received server logging notification [INFO]: Final score: 25

This is expected since the password “weak“ is shorter than 12 characters and doesn’t contain uppercase letters and digits. It only satisfies the common password criterion. Therefore, it gets a final score of 25 out of 100.

Our example consists of only an MCP server and client. But if the client were an LLM-orchestrated agent, a list of transactions similar to the following list would have occurred:

• User -> Client: The user asks the following question: “How strong is the password weak?”
• Client -> LLM: The client sends the user’s message to the LLM together with the tool information received from the MCP server at session start
• LLM -> Client: The LLM doesn’t call the server itself. Instead, it returns a response that indicates that it wants to call the tool checkStrength with password=weak
• Client -> Server: The client issues the actual JSON-RPC request over the stdio transport
• Server -> Client: The server returns the response we saw earlier as a JSON-RPC response
• Client -> LLM: The client forwards the tool result back to the conversation and asks the LLM to continue
• LLM –> User: The LLM generates a natural-language answer synthesizing the structured result from the tool, something like: “That password is very weak. It’s only 4 characters long — you’ll need at least 12 — and it doesn’t include any uppercase letters or digits. I can make suggestions if you like.“

7. Conclusion

In this article, we discussed MCP logging in Spring AI. Firstly, we learned about how logging works within the MCP ecosystem. Then, we examined the details of MCP logging on an MCP server evaluating a password’s strength. We saw that we can use the logging methods in the McpSyncRequestContext interface to print log messages at different severity levels.

Then, we discussed logging on the MCP client. We learned that we can use a handler annotated with @McpLogging for handling logs. Finally, we saw an example using the server and client and discussed the interaction between an LLM, the client, and the server when a user asks for an evaluation of a password’s strength.

As usual, the complete source code for the examples is available over on GitHub.