AOT and GraalVM Native Image Support

Spring AI MCP provides AOT (Ahead-of-Time) compilation support for GraalVM native images through runtime hints registration. This ensures that MCP schema classes and reflection-based operations work correctly in native images.

Import

import org.springframework.ai.mcp.aot.McpHints;
import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.hint.RuntimeHintsRegistrar;

McpHints

public class McpHints implements RuntimeHintsRegistrar {
    void registerHints(RuntimeHints hints, ClassLoader classLoader);
}

Runtime hints registrar that registers necessary reflection and resource hints for MCP schema classes to enable GraalVM native image compilation.

Purpose

The McpHints class automatically registers runtime hints for:

• MCP schema classes from io.modelcontextprotocol.spec.McpSchema
• Reflection hints for JSON serialization/deserialization
• Resource hints for MCP protocol specifications

Automatic Registration

Spring Boot automatically discovers and applies McpHints when building native images. No manual configuration is required when using Spring Boot's native image support.

Native Image Compilation

Prerequisites

1. GraalVM installed
2. Native image build tools configured
3. Spring Boot 3.x or later with native image support

Maven Configuration

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

<build>
    <plugins>
        <plugin>
            <groupId>org.graalvm.buildtools</groupId>
            <artifactId>native-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

Gradle Configuration

dependencies {
    implementation 'org.springframework.ai:spring-ai-mcp:1.1.2'
}

graalvmNative {
    binaries {
        main {
            // Native image configuration
        }
    }
}

Building Native Images

Using Maven

# Build native image
mvn -Pnative native:compile

# Run native image
./target/my-app

Using Gradle

# Build native image
./gradlew nativeCompile

# Run native image
./build/native/nativeCompile/my-app

What Gets Registered

The McpHints class registers runtime hints for the following MCP schema components:

• Protocol Classes: Core MCP protocol message types
• Tool Schemas: Tool definitions and call request/response types
• Prompt Schemas: Prompt definitions and get request/response types
• Resource Schemas: Resource definitions and read request/response types
• Client/Server Capabilities: Initialization and capability negotiation types
• Notification Types: Logging, progress, and list changed notifications

Verifying Native Image Support

Test Native Image Compilation

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.ai.mcp.SyncMcpToolCallbackProvider;

@SpringBootApplication
public class NativeImageTestApplication {

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

    @Bean
    public SyncMcpToolCallbackProvider mcpProvider(McpSyncClient client) {
        return SyncMcpToolCallbackProvider.builder()
            .mcpClients(client)
            .build();
    }
}

Compile and run as native image to verify MCP functionality works correctly.

Troubleshooting Native Images

Common Issues

Issue: ClassNotFoundException for MCP schema classes

Solution: Ensure spring-ai-mcp is on the classpath during native image build. The McpHints class should be automatically discovered.

Issue: JSON serialization errors for MCP types

Solution: Verify that McpHints is being applied. Check native image build logs for hint registration.

Issue: Reflection errors when calling MCP methods

Solution: Check that all MCP SDK dependencies are included in the native image build configuration.

Manual Hint Registration

If automatic registration doesn't work, you can manually register hints:

import org.springframework.aot.hint.RuntimeHints;
import org.springframework.aot.hint.RuntimeHintsRegistrar;
import org.springframework.context.annotation.ImportRuntimeHints;

@ImportRuntimeHints(CustomMcpHints.class)
@Configuration
public class McpConfiguration {
    // Your configuration
}

class CustomMcpHints implements RuntimeHintsRegistrar {
    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        // Register additional hints if needed
        McpHints mcpHints = new McpHints();
        mcpHints.registerHints(hints, classLoader);

        // Add custom hints here if needed
    }
}

Performance Considerations

Native images provide:

• Faster Startup: Near-instantaneous startup compared to JVM
• Lower Memory Footprint: Reduced memory usage for MCP operations
• Ahead-of-Time Compilation: No JIT warm-up period

Trade-offs:

• Build Time: Longer build times for native images
• Build Resources: Higher CPU and memory requirements during build
• Debugging: More complex debugging compared to JVM applications

Related Components

• Synchronous Tool Discovery - Using MCP tools in native images
• Asynchronous Tool Discovery - Async MCP operations in native images