Troubleshooting Java Version Compatibility in Claude Desktop Configuration with MCP Server

“The art of troubleshooting lies not in avoiding errors, but in understanding and overcoming them.” — Adapted from the wisdom of countless innovators

Troubleshooting Java Version Compatibility in Claude Desktop Configuration with MCP Server

This article provides a step-by-step guide to diagnose and resolve a Java version compatibility issue between the MCP Server and Claude Desktop. The problem arises when Claude Desktop tries to run an MCP server built with a newer Java version than what the client supports.

Overview

Job:
Configure Claude Desktop to properly connect to the MCP Server built in Java.

Issue Encountered:
Claude Desktop failed to launch the MCP Server due to a Java version mismatch. The server was built with Java 21, but Claude Desktop was inadvertently running it using Java 11.

---

Detailed Problem Analysis

Configuration File

The Claude Desktop configuration is defined in the claude_desktop_config.json file. In this file, the MCP server is configured as follows:

{
  "mcpServers": {
    "spring-ai-mcp-weather": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dlogging.pattern.console=",
        "-jar",
        "/Users/zcui/Workspace/github/aiz-mcp-server/target/aiz-mcp-server-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

Error Message

On starting the server, the following error is displayed:

2025-03-13T09:00:37.978Z [spring-ai-mcp-weather] [info] Server started and connected successfully
2025-03-13T09:00:38.138Z [spring-ai-mcp-weather] [info] Message from client: {"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"claude-ai","version":"0.1.0"}},"jsonrpc":"2.0","id":0}

Error: LinkageError occurred while loading main class org.springframework.boot.loader.launch.JarLauncher
    java.lang.UnsupportedClassVersionError: org/springframework/boot/loader/launch/JarLauncher has been compiled by a more recent version of the Java Runtime (class file version 61.0), 
    this version of the Java Runtime only recognizes class file versions up to 55.0

Key Points from the Error:

• Mismatch: The error indicates that the MCP server is compiled with Java 21 (class file version 61.0) while Claude Desktop is using Java 11 (class file version up to 55.0).
• Environment Check: Running java -version confirms that Java 21 is configured via JAVA_HOME. However, Claude Desktop does not pick this version.

---

Troubleshooting Steps

1. Analyze the Error Message:
   Understand that the error occurs because Claude Desktop attempts to run a server compiled with Java 21 using a Java 11 runtime environment.

2. Verify Java Versions:
   Execute java -version to ensure that Java 21 is set as the current version in your environment. Despite this, Claude Desktop may still be using an older Java version.

3. Inspect Potential Java Installations:
   Check the following locations for alternative Java installations that might be prioritized by Claude Desktop:
   • /usr/libexec/java_home
   • /Library/Java/JavaVirtualMachines
   • /Users/zcui/Library/Java/JavaVirtualMachines
   • /Users/zcui/.sdkman/candidates/java/current

4. Identify the Conflict:
   It was found that /usr/libexec/java_home links to a JDK in /Users/zcui/Library/Java/JavaVirtualMachines that is Java 11. This older version is being detected by Claude Desktop.

5. Recognize the Limitation:
   Claude Desktop does not parse the BASH profile to locate the correct Java version. Instead, it relies solely on /usr/libexec/java_home.

---

Resolution Steps

To resolve the Java version issue, follow these corrective actions:

1. Remove the Older JDK:
   • Delete the Java 11 installation from /Users/zcui/Library/Java/JavaVirtualMachines.
2. Prepare a New Folder for the Correct JDK:
   • Create a directory for the SDKMAN-managed JDK:

        mkdir -p /Users/zcui/Library/Java/JavaVirtualMachines/sdkman-current/Contents
   

3. Create a Symlink to the Correct JDK:
   • Link the SDKMAN-managed JDK to the new folder:

        ln -s /Users/zcui/.sdkman/candidates/java/current /Users/zcui/Library/Java/JavaVirtualMachines/sdkman-current/Contents/Home
   

4. Configure the Info.plist File:
   • Create an Info.plist file in /Users/zcui/Library/Java/JavaVirtualMachines/sdkman-current/Contents with content similar to:

        <?xml version="1.0" encoding="UTF-8"?>
        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
        <plist version="1.0">
        <dict>
            <key>CFBundleIdentifier</key>
            <string>sdkman.current</string>
            <key>CFBundleName</key>
            <string>SDKMAN Current JDK</string>
            <key>JavaVM</key>
            <dict>
                <key>JVMPlatformVersion</key>
                <string>21.0.4-amzn</string>
                <key>JVMVendor</key>
                <string>Corretto</string>
                <key>JVMVersion</key>
                <string>21.0.4</string>
            </dict>
        </dict>
        </plist>
   

   • Ensure that the version information matches your current SDKMAN JDK.
5. Verify the New Configuration:
   • Run the command /usr/libexec/java_home -V to confirm that the system now points to the SDKMAN-managed JDK.
6. Restart Claude Desktop:
   • Reboot the Claude Desktop application. It should now launch the MCP server with the correct Java 21 runtime environment.

---

Conclusion

This troubleshooting guide outlines the root cause of the Java version mismatch between the MCP server and Claude Desktop. By ensuring that the system’s /usr/libexec/java_home points to the correct JDK (Java 21 managed via SDKMAN), you can resolve the error and enable the MCP server to run as expected.

Following these steps should help eliminate the Java compatibility issue and ensure smooth operation of your MCP server with Claude Desktop. If problems persist, verify the JDK paths and configurations, or consult further documentation regarding your specific setup.

---