Model Context Protocol SDK

https://modelcontextprotocol.io/sdk/
Admin
Model Context Protocol SDK provides tools and libraries for building MCP servers and clients that...
Tokens:15,058
Snippets:69
Trust Score:9.9
Update:10 months ago
Show doc for...
Tokens:
Raw
### Manage Filesystem Roots

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Provides examples for managing filesystem roots within the MCP client. This includes adding, removing, and notifying the server about changes to roots.

```java
// Add a root dynamically
client.addRoot(new Root("file:///path", "description"));

// Remove a root
client.removeRoot("file:///path");

// Notify server of roots changes
client.rootsListChangedNotification();
```

--------------------------------

### Manage Roots and Client Operations with ModelContextProtocol IO SDK

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

This example demonstrates adding and removing a root resource using the SDK, followed by closing the client connection gracefully. It employs RxJava's `then` and `doFinally` for sequential execution and cleanup. The `subscribe()` call is necessary to trigger the reactive stream.

```java
client.addRoot(new Root("file:///path", "description"))
    .then(client.removeRoot("file:///path"));
client.closeGracefully().subscribe();
```

--------------------------------

### Configure WebFlux SSE Client Transport

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Demonstrates how to initialize the McpTransport using the WebFluxSseClientTransport. This is the basic setup for establishing communication via Server-Sent Events.

```java
McpTransport transport = WebFluxSseClientTransport(webClientBuilder)
                                    .builder(webClientBuilder)
                                    .build();
```

--------------------------------

### Configure Client Capabilities

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Demonstrates how to build and configure client capabilities for the MCP client. This includes enabling support for filesystem roots, LLM sampling, and elicitation.

```java
var capabilities = ClientCapabilities.builder()
    .roots(true)      // Enable filesystem roots support with list changes notifications
    .sampling()       // Enable LLM sampling support
    .elicitation()    // Enable elicitation capability
    .build();
```

--------------------------------

### Create and Configure Asynchronous MCP Server in Java

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Illustrates the creation and configuration of an asynchronous MCP server. This includes setting server details, defining capabilities, and registering tools, resources, and prompts with reactive subscriptions. It also shows how to close the server asynchronously.

```java
McpAsyncServer asyncServer = McpServer.async(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .resources(false, true)     // Enable resource support
        .tools(true)                // Enable tool support
        .prompts(true)              // Enable prompt support
        .logging()                  // Enable logging support
        .completions()              // Enable completions support
        .build())
    .build();

// Register tools, resources, and prompts
asyncServer.addTool(asyncToolSpecification)
    .doOnSuccess(v -> logger.info("Tool registered"))
    .subscribe();

asyncServer.addResource(asyncResourceSpecification)
    .doOnSuccess(v -> logger.info("Resource registered"))
    .subscribe();

asyncServer.addPrompt(asyncPromptSpecification)
    .doOnSuccess(v -> logger.info("Prompt registered"))
    .subscribe();

// Close the server when done
asyncServer.close()
    .doOnSuccess(v -> logger.info("Server closed"))
    .subscribe();
```

--------------------------------

### Create and Configure Synchronous MCP Server in Java

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Demonstrates how to instantiate and configure a synchronous MCP server. It highlights setting server information, defining capabilities like resource and tool support, and registering handlers. The `immediateExecution` option is explained for preserving thread-locals.

```java
McpSyncServer syncServer = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .resources(false, true)  // Enable resource support
        .tools(true)             // Enable tool support
        .prompts(true)           // Enable prompt support
        .logging()               // Enable logging support
        .completions()           // Enable completions support
        .build())
    .build();

// Register tools, resources, and prompts
syncServer.addTool(syncToolSpecification);
syncServer.addResource(syncResourceSpecification);
syncServer.addPrompt(syncPromptSpecification);

// Close the server when done
syncServer.close();
```

--------------------------------

### MCP Client SDK: Synchronous API Usage (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Demonstrates how to create and use a synchronous MCP client in Java. This includes setting up custom configurations, enabling capabilities like roots and sampling, and performing operations such as listing tools, calling tools, managing resources, and interacting with prompts. It also shows how to add/remove roots and gracefully close the client connection.

```java
import java.time.Duration;
import java.util.List;
import java.util.Map;

// Create a sync client with custom configuration
McpSyncClient client = McpClient.sync(transport)
    .requestTimeout(Duration.ofSeconds(10))
    .capabilities(ClientCapabilities.builder()
        .roots(true)      // Enable roots capability
        .sampling()       // Enable sampling capability
        .elicitation()    // Enable elicitation capability
        .build())
    .sampling(request -> CreateMessageResult.builder()...build())
    .elicitation(elicitRequest -> ElicitResult.builder()...build())
    .toolsChangeConsumer((List<McpSchema.Tool> tools) -> {})
    .resourcesChangeConsumer((List<McpSchema.Resource> resources) -> {})
    .promptsChangeConsumer((List<McpSchema.Prompt> prompts) -> {})
    .loggingConsumer((LoggingMessageNotification logging) -> {})
    .progressConsumer((ProgressNotification progress) -> {})
    .build();

// Initialize connection
client.initialize();

// List available tools
ListToolsResult tools = client.listTools();

// Call a tool
CallToolResult result = client.callTool(
    new CallToolRequest("calculator",
        Map.of("operation", "add", "a", 2, "b", 3))
);

// List and read resources
ListResourcesResult resources = client.listResources();
ReadResourceResult resource = client.readResource(
    new ReadResourceRequest("resource://uri")
);

// List and use prompts
ListPromptsResult prompts = client.listPrompts();
GetPromptResult prompt = client.getPrompt(
    new GetPromptRequest("greeting", Map.of("name", "Spring"))
);

// Add/remove roots
client.addRoot(new Root("file:///path", "description"));
client.removeRoot("file:///path");

// Close client
client.closeGracefully();
```

--------------------------------

### MCP Client SDK: Asynchronous API Usage (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Illustrates the usage of the asynchronous MCP client in Java, leveraging Project Reactor's Mono for non-blocking operations. It covers client initialization, capability configuration, and chaining asynchronous calls for operations like listing tools, executing tools, managing resources, and handling prompt requests. Callback methods for changes in tools, resources, and prompts are also demonstrated.

```java
import reactor.core.publisher.Mono;
import java.time.Duration;
import java.util.Map;

// Create an async client with custom configuration
McpAsyncClient client = McpClient.async(transport)
    .requestTimeout(Duration.ofSeconds(10))
    .capabilities(ClientCapabilities.builder()
        .roots(true)      // Enable roots capability
        .sampling()       // Enable sampling capability
        .elicitation()    // Enable elicitation capability
        .build())
    .sampling(request -> Mono.just(new CreateMessageResult(response)))
    .elicitation(elicitRequest -> Mono.just(ElicitResult.builder()...build()))
    .toolsChangeConsumer(tools -> Mono.fromRunnable(() -> logger.info("Tools updated: {}", tools)))
    .resourcesChangeConsumer(resources -> Mono.fromRunnable(() -> logger.info("Resources updated: {}", resources)))
    .promptsChangeConsumer(prompts -> Mono.fromRunnable(() -> logger.info("Prompts updated: {}", prompts)))
    .loggingConsumer(notification -> Mono.fromRunnable(() -> logger.info("Log: {}", notification.data())))
    .progressConsumer(progress -> Mono.fromRunnable(() -> logger.info("Progress update: {}", progress.data())))
    .build();

// Initialize connection and use features
client.initialize()
    .flatMap(initResult -> client.listTools())
    .flatMap(tools -> {
        return client.callTool(new CallToolRequest(
            "calculator",
            Map.of("operation", "add", "a", 2, "b", 3)
        ));
    })
    .flatMap(result -> {
        return client.listResources()
            .flatMap(resources ->
                client.readResource(new ReadResourceRequest("resource://uri"))
            );
    })
    .flatMap(resource -> {
        return client.listPrompts();
    });
```

--------------------------------

### Interact with Prompt System (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

This snippet demonstrates how to interact with the MCP prompt system using both synchronous and asynchronous APIs in Java. It covers listing available prompt templates and executing a prompt template with custom parameters. Ensure the MCP client is properly initialized before use.

```java
var prompts = client.listPrompts();
prompts.forEach(prompt -> System.out.println(prompt.getName()));

var response = client.executePrompt("echo", Map.of(
    "text", "Hello, World!"
));
```

```java
client.listPrompts()
    .doOnNext(prompts -> prompts.forEach(prompt ->
        System.out.println(prompt.getName())))
    .subscribe();

client.executePrompt("echo", Map.of(
        "text", "Hello, World!"
    ))
    .subscribe();
```

--------------------------------

### Access Resources using MCP Client - Sync API (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Demonstrates synchronous resource access with the MCP client. It covers listing available resources and retrieving their content using a URI template and parameters. The `getResource` method returns the resource content.

```java
// List available resources and their names
var resources = client.listResources();
resources.forEach(resource -> System.out.println(resource.getName()));

// Retrieve resource content using a URI template
var content = client.getResource("file", Map.of(
    "path", "/path/to/file.txt"
));
```

--------------------------------

### Execute Tools using MCP Client - Sync API (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Demonstrates synchronous tool execution using the MCP client. It covers listing available tools and calling a specific tool with a map of parameters. The `callTool` method returns a `CallToolResult`.

```java
// List available tools and their names
var tools = client.listTools();
tools.forEach(tool -> System.out.println(tool.getName()));

// Execute a tool with parameters
var result = client.callTool("calculator", Map.of(
    "operation", "add",
    "a", 1,
    "b", 2
));
```

--------------------------------

### Specify Prompts (Sync/Async Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Details the process of exposing prompt templates to clients via the MCP SDK. This enables standardized message formatting, parameter substitution, and context injection for AI models. Both synchronous and asynchronous handlers are supported. Prompt definitions include a name, description, and arguments.

```java
var syncPromptSpecification = new McpServerFeatures.SyncPromptSpecification(
    new Prompt("greeting", "description", List.of(
        new PromptArgument("name", "description", true)
    )),
    (exchange, request) -> {
        // Prompt implementation
        return new GetPromptResult(description, messages);
    }
);
var asyncPromptSpecification = new McpServerFeatures.AsyncPromptSpecification(
    new Prompt("greeting", "description", List.of(
        new PromptArgument("name", "description", true)
    )),
    (exchange, request) -> {
        // Prompt implementation
        return Mono.just(new GetPromptResult(description, messages));
    }
);
```

--------------------------------

### Request Autocompletion Suggestions (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

This Java code demonstrates how to request autocompletion suggestions for prompts and resource URIs using the MCP client. It shows both synchronous and asynchronous methods for sending completion requests. The `CompleteRequest` object requires a `PromptReference` and a list of `CompleteArgument` objects.

```java
CompleteRequest request = new CompleteRequest(
        new PromptReference("code_review"),
        new CompleteRequest.CompleteArgument("language", "py"));

CompleteResult result = syncMcpClient.completeCompletion(request);
```

```java
CompleteRequest request = new CompleteRequest(
        new PromptReference("code_review"),
        new CompleteRequest.CompleteArgument("language", "py"));

Mono<CompleteResult> result = mcpClient.completeCompletion(request);
```

--------------------------------

### Configure Server Capabilities (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Builds a ServerCapabilities object to define the features supported by the Model Context Protocol server. This includes enabling or disabling support for resources, tools, and prompts, with optional logging configuration. The .logging() method enables logging by default at INFO level.

```java
var capabilities = ServerCapabilities.builder()
    .resources(false, true)  // Resource support with list changes notifications
    .tools(true)            // Tool support with list changes notifications
    .prompts(true)          // Prompt support with list changes notifications
    .logging()              // Enable logging support (enabled by default with logging level INFO)
    .build();
```

--------------------------------

### Implement Server-Side Sampling (Java Sync API)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

This Java code demonstrates how to set up a synchronous MCP server that uses sampling. It defines a tool that checks for client sampling support, constructs a `CreateMessageRequest` with specific model preferences and a system prompt, and then calls the client to generate a message. The result is processed to return a `CallToolResult`.

```java
    // Create a server
    McpSyncServer server = McpServer.sync(transportProvider)
        .serverInfo("my-server", "1.0.0")
        .build();

    // Define a tool that uses sampling
    var calculatorTool = new McpServerFeatures.SyncToolSpecification(
        new Tool("ai-calculator", "Performs calculations using AI", schema),
        (exchange, arguments) -> {
            // Check if client supports sampling
            if (exchange.getClientCapabilities().sampling() == null) {
                return new CallToolResult("Client does not support AI capabilities", false);
            }

            // Create a sampling request
            McpSchema.CreateMessageRequest request = McpSchema.CreateMessageRequest.builder()
                .messages(List.of(new McpSchema.SamplingMessage(McpSchema.Role.USER,
                    new McpSchema.TextContent("Calculate: " + arguments.get("expression")))
                .modelPreferences(McpSchema.ModelPreferences.builder()
                    .hints(List.of(
                        McpSchema.ModelHint.of("claude-3-sonnet"),
                        McpSchema.ModelHint.of("claude")
                    ))
                    .intelligencePriority(0.8)  // Prioritize intelligence
                    .speedPriority(0.5)         // Moderate speed importance
                    .build())
                .systemPrompt("You are a helpful calculator assistant. Provide only the numerical answer.")
                .maxTokens(100)
                .build();

            // Request sampling from the client
            McpSchema.CreateMessageResult result = exchange.createMessage(request);

            // Process the result
            String answer = result.content().text();
            return new CallToolResult(answer, false);
        }
    );

    // Add the tool to the server
    server.addTool(calculatorTool);
```

--------------------------------

### Execute Tools using MCP Client - Async API (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Illustrates asynchronous tool execution using the MCP client with RxJava. It shows how to list tools and execute them, with results handled via `doOnNext` and `subscribe`. This approach is suitable for non-blocking operations.

```java
// List available tools asynchronously
client.listTools()
    .doOnNext(tools -> tools.forEach(tool ->
        System.out.println(tool.getName())))
    .subscribe();

// Execute a tool asynchronously
client.callTool("calculator", Map.of(
        "operation", "add",
        "a", 1,
        "b", 2
    ))
    .subscribe();
```

--------------------------------

### Access Resources using MCP Client - Async API (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Illustrates asynchronous resource access using the MCP client with RxJava. It shows how to list resources and retrieve their content, with results handled via `doOnNext` and `subscribe`. This enables non-blocking retrieval of server-side data.

```java
// List available resources asynchronously
client.listResources()
    .doOnNext(resources -> resources.forEach(resource ->
        System.out.println(resource.getName())))
    .subscribe();

// Retrieve resource content asynchronously
client.getResource("file", Map.of(
        "path", "/path/to/file.txt"
    ))
    .subscribe();
```

--------------------------------

### Configure Elicitation Support

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Demonstrates how to enable and configure elicitation support in the MCP client. This requires defining an elicitation handler function to process server requests for information.

```java
// Configure elicitation handler
Function<ElicitRequest, ElicitResult> elicitationHandler = request -> {
    // Elicitation implementation that interfaces with LLM
    return ElicitResult.builder()...build();
};

// Create client with elicitation support
var client = McpClient.sync(transport)
    .capabilities(ClientCapabilities.builder()
        .elicitation() // enable elicitation capability
        .build())
    .elicitation(elicitationHandler) // register elicitation handler
    .build();
```

--------------------------------

### Client-side Logging Integration (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Demonstrates how to configure a client to receive log messages from the server. It shows how to register a logging consumer, set the minimum logging level, and build the MCP client. The client will print received log messages to standard output.

```java
var mcpClient = McpClient.sync(transport)
        .loggingConsumer(notification -> {
            System.out.println("Received log message: " + notification.data());
        })
        .build();

mcpClient.initialize();

mcpClient.setLoggingLevel(McpSchema.LoggingLevel.INFO);

// Call the tool that sends logging notifications
CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("logging-test", Map.of()));
```

--------------------------------

### Create Streamable-HTTP Client Transport with WebClient (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Provides a Streamable-HTTP client transport leveraging Spring WebFlux's WebClient. This requires the `mcp-spring-webflux` dependency and a pre-configured `WebClient.Builder`.

```java
WebClient.Builder webClientBuilder = WebClient.builder()
                                    .baseUrl("http://your-mcp-server");

McpTransport transport = WebClientStreamableHttpTransport
                                    .builder(webClientBuilder)
                                    .build();
```

--------------------------------

### Add MCP Bill of Materials (BOM) (Maven)

Source: https://modelcontextprotocol.io/sdk/java/mcp-overview

This Maven snippet configures the Bill of Materials (BOM) for the MCP SDK. Using the BOM ensures consistent and tested versions of all MCP dependencies, simplifying version management.

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.modelcontextprotocol.sdk</groupId>
            <artifactId>mcp-bom</artifactId>
            <version>0.12.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

--------------------------------

### Server-side Elicitation with Async API (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Illustrates how a server can initiate language model generations from a client using the asynchronous API. It includes a check for client elicitation support, constructs an elicitation request, and handles the asynchronous client response.

```java
McpAsyncServer server = McpServer.async(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .build();

var calculatorTool = new McpServerFeatures.AsyncToolSpecification(
    new Tool("ai-calculator", "Performs calculations using AI", schema),
    (exchange, arguments) -> {
        if (exchange.getClientCapabilities().elicitation() == null) {
            return Mono.just(new CallToolResult("Client does not support elicitation capabilities", false));
        }

        McpSchema.ElicitRequest request = McpSchema.ElicitRequest.builder()
            .message("Test message")
            .requestedSchema(
                    Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
            .build();

        return exchange.createElicitation(request)
            .map(result -> {
                Map<String, Object> answer = result.content();
                return new CallToolResult(answer, false);
            });
    }
);

server.addTool(calculatorTool)
    .subscribe();
```

--------------------------------

### Configure LLM Sampling Support

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Shows how to enable and configure LLM sampling support in the MCP client. This involves defining a sampling handler function that interfaces with an LLM.

```java
// Configure sampling handler
Function<CreateMessageRequest, CreateMessageResult> samplingHandler = request -> {
    // Sampling implementation that interfaces with LLM
    return new CreateMessageResult(response);
};

// Create client with sampling support
var client = McpClient.sync(transport)
    .capabilities(ClientCapabilities.builder()
        .sampling()
        .build())
    .sampling(samplingHandler)
    .build();
```

--------------------------------

### Add MCP Bill of Materials (BOM) (Gradle)

Source: https://modelcontextprotocol.io/sdk/java/mcp-overview

This Gradle configuration adds the MCP SDK's Bill of Materials (BOM), enabling dependency constraint management. It ensures that declared MCP modules use versions compatible with the specified BOM version.

```groovy
dependencies {
  implementation platform("io.modelcontextprotocol.sdk:mcp-bom:0.12.1")
  //...
}
```

--------------------------------

### Fetch and Process Prompts with ModelContextProtocol IO SDK

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

This snippet shows how to retrieve a prompt by its ID and process it. It utilizes RxJava's flatMap operator for asynchronous operations. Ensure the SDK client is properly initialized.

```java
client.getPrompt(new GetPromptRequest(
    "greeting",
    Map.of("name", "Spring")
))
```

--------------------------------

### Specify Resources (Sync/Async Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Defines how to specify resources for AI models, including their content and a handler function for reading them. Supports both synchronous and asynchronous operations. The resource definition includes name, description, and MIME type, while the handler interacts with McpAsyncServerExchange and McpSchema.ReadResourceRequest.

```java
var syncResourceSpecification = new McpServerFeatures.SyncResourceSpecification(
    new Resource("custom://resource", "name", "description", "mime-type", null),
    (exchange, request) -> {
        // Resource read implementation
        return new ReadResourceResult(contents);
    }
);
var asyncResourceSpecification = new McpServerFeatures.AsyncResourceSpecification(
    new Resource("custom://resource", "name", "description", "mime-type", null),
    (exchange, request) -> {
        // Resource read implementation
        return Mono.just(new ReadResourceResult(contents));
    }
);
```

--------------------------------

### Create Streamable-HTTP Client Transport with HttpClient (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Implements a framework-agnostic Streamable-HTTP client transport using only JDK APIs. This allows for communication with MCP servers over HTTP without external framework dependencies. It requires the base URL of the MCP server.

```java
McpTransport transport = HttpClientStreamableHttpTransport
                                    .builder("http://your-mcp-server")
                                    .build();
```

--------------------------------

### Configure Logging for MCP Client (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Demonstrates how to register a logging consumer and set the minimum logging level for an MCP client. This allows clients to receive and filter log messages from the server. Supported levels range from DEBUG to EMERGENCY.

```java
var mcpClient = McpClient.sync(transport)
        .loggingConsumer((LoggingMessageNotification notification) -> {
            System.out.println("Received log message: " + notification.data());
        })
        .build();

mcpClient.initialize();

mcpClient.setLoggingLevel(McpSchema.LoggingLevel.INFO);

// Call the tool that can sends logging notifications
CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("logging-test", Map.of()));
```

--------------------------------

### Register Change Consumers for MCP Client (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Illustrates how to register consumers for notifications about changes in tools, resources, and prompts. This allows clients to stay updated on the server's available components. Consumers are notified with lists of the updated items.

```java
var spec = McpClient.sync(transport);

// Adds a consumer to be notified when the available tools change, such as tools
// being added or removed.
spec.toolsChangeConsumer((List<McpSchema.Tool> tools) -> {
    // Handle tools change
});

// Adds a consumer to be notified when the available resources change, such as resources
// being added or removed.
spec.resourcesChangeConsumer((List<McpSchema.Resource> resources) -> {
    // Handle resources change
});

// Adds a consumer to be notified when the available prompts change, such as prompts
// being added or removed.
spec.promptsChangeConsumer((List<McpSchema.Prompt> prompts) -> {
    // Handle prompts change

});
```

--------------------------------

### Implement Server-Side Sampling (Java Async API)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

This Java code showcases the asynchronous implementation of server-side sampling using the MCP SDK. It sets up an `McpAsyncServer` with a tool that checks client sampling capabilities, constructs a `CreateMessageRequest`, and uses reactive streams (`Mono`) to handle the asynchronous creation of a message from the client. The response is mapped to a `CallToolResult`.

```java
    // Create a server
    McpAsyncServer server = McpServer.async(transportProvider)
        .serverInfo("my-server", "1.0.0")
        .build();

    // Define a tool that uses sampling
    var calculatorTool = new McpServerFeatures.AsyncToolSpecification(
        new Tool("ai-calculator", "Performs calculations using AI", schema),
        (exchange, arguments) -> {
            // Check if client supports sampling
            if (exchange.getClientCapabilities().sampling() == null) {
                return Mono.just(new CallToolResult("Client does not support AI capabilities", false));
            }

            // Create a sampling request
            McpSchema.CreateMessageRequest request = McpSchema.CreateMessageRequest.builder()
                .content(new McpSchema.TextContent("Calculate: " + arguments.get("expression")))
                .modelPreferences(McpSchema.ModelPreferences.builder()
                    .hints(List.of(
                        McpSchema.ModelHint.of("claude-3-sonnet"),
                        McpSchema.ModelHint.of("claude")
                    ))
                    .intelligencePriority(0.8)  // Prioritize intelligence
                    .speedPriority(0.5)         // Moderate speed importance
                    .build())
                .systemPrompt("You are a helpful calculator assistant. Provide only the numerical answer.")
                .maxTokens(100)
                .build();

            // Request sampling from the client
            return exchange.createMessage(request)
                .map(result -> {
                    // Process the result
                    String answer = result.content().text();
                    return new CallToolResult(answer, false);
                });
        }
    );

    // Add the tool to the server
    server.addTool(calculatorTool)
        .subscribe();
```

--------------------------------

### Server-side Elicitation with Sync API (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Demonstrates how a server can request language model generations from a client using the synchronous API. It checks for client elicitation support, builds an elicitation request, and processes the client's response.

```java
McpSyncServer server = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .build();

var calculatorTool = new McpServerFeatures.SyncToolSpecification(
    new Tool("ai-calculator", "Performs calculations using AI", schema),
    (exchange, arguments) -> {
        if (exchange.getClientCapabilities().elicitation() == null) {
            return new CallToolResult("Client does not support elicitation capabilities", false);
        }

        McpSchema.ElicitRequest request = McpSchema.ElicitRequest.builder()
									.message("Test message")
									.requestedSchema(
											Map.of("type", "object", "properties", Map.of("message", Map.of("type", "string"))))
									.build();

        McpSchema.ElicitResult result = exchange.createElicitation(request);

        Map<String, Object> answer = result.content();
        return new CallToolResult(answer, false);
    }
);

server.addTool(calculatorTool);
```

--------------------------------

### Add Spring WebMVC Transport (Gradle)

Source: https://modelcontextprotocol.io/sdk/java/mcp-overview

This Gradle snippet adds Spring WebMVC-based server transports for Streamable-HTTP and SSE, compatible with servlet-based applications using the MCP SDK.

```groovy
// Optional: Spring WebMVC-based SSE and Streamable-HTTP server transports
dependencies {
  implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webmvc")
}
```

--------------------------------

### Create SSE Client Transport with WebClient (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Implements a Server-Sent Events (SSE) client transport using Spring WebFlux's WebClient. This integration requires the `mcp-spring-webflux` dependency and a properly configured `WebClient.Builder` for establishing the connection.

```java
WebClient.Builder webClientBuilder = WebClient.builder()
                                    .baseUrl("http://your-mcp-server");


```

--------------------------------

### Create SSE Client Transport with HttpClient (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Implements a framework-agnostic Server-Sent Events (SSE) client transport using only JDK APIs. This transport is designed for efficient, one-way communication from the server to the client. It requires the base URL of the MCP server.

```java
McpTransport transport = HttpClientSseClientTransport
                                    .builder("http://your-mcp-server")
                                    .build();
```

--------------------------------

### Configure WebFlux Streamable HTTP Server Transport (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Sets up a WebFluxStreamableServerTransportProvider for bidirectional communication via Streamable HTTP. Requires the `mcp-spring-webflux` dependency. It configures message endpoints and provides a RouterFunction for integrating with Spring WebFlux. Dependencies: ObjectMapper, WebFluxStreamableServerTransportProvider.

```java
@Configuration
class McpConfig {
    @Bean
    WebFluxStreamableServerTransportProvider webFluxStreamableServerTransportProvider(ObjectMapper mapper) {
      	return this.mcpStreamableServerTransportProvider = WebFluxStreamableServerTransportProvider.builder()
                .objectMapper(mapper)
                .messageEndpoint("/mcp")
                .build();
    }

    @Bean
    RouterFunction<?> mcpRouterFunction(WebFluxStreamableServerTransportProvider transportProvider) {
        return transportProvider.getRouterFunction();
    }
}
```

--------------------------------

### Define Synchronous Tool Specification (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Defines a synchronous tool specification for the Model Context Protocol. It includes a Tool object with its name, description, and a JSON schema for parameters, along with a handler function that executes the tool's logic synchronously. The handler receives the exchange and arguments, returning a CallToolResult.

```java
// Sync tool specification
var schema = "{\"type\" : \"object\",\"id\" : \"urn:jsonschema:Operation\",\"properties\" : {\"operation\" : {\"type\" : \"string\"},\"a\" : {\"type\" : \"number\"},\"b\" : {\"type\" : \"number\"}}}";
var syncToolSpecification = new McpServerFeatures.SyncToolSpecification(
    new Tool("calculator", "Basic calculator", schema),
    (exchange, arguments) -> {
        // Tool implementation
        return new CallToolResult(result, false);
    }
);
```

--------------------------------

### Add Core MCP Dependency (Maven)

Source: https://modelcontextprotocol.io/sdk/java/mcp-overview

This snippet shows how to add the core Model Context Protocol (MCP) functionality to your project using Maven. The core module includes default transport implementations for STDIO, SSE, and Streamable-HTTP, and does not require external web frameworks.

```xml
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>
</dependency>
```

--------------------------------

### Add Spring WebMVC Transport (Maven)

Source: https://modelcontextprotocol.io/sdk/java/mcp-overview

This Maven dependency provides Spring WebMVC-based SSE and Streamable-HTTP server transports for servlet-based applications using the MCP SDK.

```xml
<!-- Optional: Spring WebMVC-based SSE and Streamable-HTTP server transports -->
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webmvc</artifactId>
</dependency>
```

--------------------------------

### Define Asynchronous Tool Specification (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Defines an asynchronous tool specification for the Model Context Protocol. It includes a Tool object with its name, description, and a JSON schema for parameters, alongside an asynchronous handler function using Reactor's Mono. The handler receives the exchange and arguments, returning a Mono<CallToolResult> for non-blocking execution.

```java
// Async tool specification
var schema = "{\"type\" : \"object\",\"id\" : \"urn:jsonschema:Operation\",\"properties\" : {\"operation\" : {\"type\" : \"string\"},\"a\" : {\"type\" : \"number\"},\"b\" : {\"type\" : \"number\"}}}";
var asyncToolSpecification = new McpServerFeatures.AsyncToolSpecification(
    new Tool("calculator", "Basic calculator", schema),
    (exchange, arguments) -> {
        // Tool implementation
        return Mono.just(new CallToolResult(result, false));
    }
);
```

--------------------------------

### Configure Streamable-HTTP Server Transport (Servlet)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Configures an HttpServletStreamableServerTransportProvider for the MCP SSE transport using the Servlet API. It supports bidirectional communication and asynchronous message handling. Dependencies include Spring WebMVC and Servlet 6.0 async support. Lacks resumability due to no session storage.

```java
@Configuration
@EnableWebMvc
public class McpServerConfig implements WebMvcConfigurer {

    @Bean
    public HttpServletStreamableServerTransportProvider servletStreamableMcpSessionTransport() {
        return HttpServletStreamableServerTransportProvider.builder()
          .objectMapper(new ObjectMapper())
          .contextExtractor(TEST_CONTEXT_EXTRACTOR)
          .mcpEndpoint(MESSAGE_ENDPOINT)
          .keepAliveInterval(Duration.ofSeconds(1))
          .build();
    }

    //(Optionally) To use it with a Spring Web application, you can register it as a Servlet bean
    @Bean
    public ServletRegistrationBean customServletBean(HttpServletStreamableServerTransportProvider transportProvider) {
        return new ServletRegistrationBean(transportProvider);
    }
}
```

--------------------------------

### Customize HTTP Requests with HttpClient (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Allows customization of HTTP requests for Streamable-HTTP and SSE transports. You can provide a static `HttpRequest.Builder` to set default headers or dynamically modify requests before they are sent using `McpSyncHttpClientRequestCustomizer` or `McpAsyncHttpClientRequestCustomizer`.

```java
var requestBuilder = HttpRequest
    .newBuilder()
    .header("X-Custom-Header", "some header value");

HttpClientStreamableHttpTransport
    .builder("https://mcp.example.com")
    .requestBuilder(requestBuilder)
    .build();
```

```java
// Sync Customizer
class MyRequestCustomizer implements McpSyncHttpClientRequestCustomizer {
    @Override
    public void customize(HttpRequest.Builder builder, String method,
        URI endpoint, String body, McpTransportContext context) {
        // ... custom logic ...
        var token = obtainAccessToken(context);
        builder.header("Authorization", "Bearer " + token);
    }
}

// Async Customizer
class MyAsyncRequestCustomizer implements McpAsyncHttpClientRequestCustomizer {
    @Override
    public Publisher<HttpRequest.Builder> customize(HttpRequest.Builder builder,
        String method, URI endpoint, String body, McpTransportContext context) {
        // ... custom logic ...
        Mono<String> token = obtainAccessToken(context);
        return token.map(t ->
            builder.copy()
                .header("Authorization", "Bearer " + t)
        );
    }
}

HttpClientStreamableHttpTransport
    .builder("https://mcp.example.com")
    .httpRequestCustomizer(new MyRequestCustomizer()) // sync
    .asyncHttpRequestCustomizer(new MyAsyncRequestCustomizer()) // OR async
    .build();
```

--------------------------------

### Customize WebClient HTTP Requests with Default Headers

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Shows how to customize outgoing HTTP requests by providing a custom WebClient.Builder. This allows setting default headers for all requests, useful for authentication tokens.

```java
var webClientBuilder = WebClient.builder()
        .defaultHeader("X-Custom-Header", "some header value");

McpTransport transport = WebClientStreamableHttpTransport
                                .builder(webClientBuilder)
                                .build();
```

--------------------------------

### Create STDIO Client Transport using Java

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Establishes an in-process communication channel for MCP clients. This transport is suitable for scenarios where the client and server run within the same process. It requires specifying the server executable and its arguments.

```java
ServerParameters params = ServerParameters.builder("npx")
    .args("-y", "@modelcontextprotocol/server-everything", "dir")
    .build();
McpTransport transport = new StdioClientTransport(params);
```

--------------------------------

### WebMVC SSE Server Transport Configuration

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Configures the Server-Sent Events (SSE) transport for WebMVC. It initializes the transport provider and the router function, enabling reactive HTTP streaming and handling concurrent connections through SSE endpoints.

```java
@Configuration
@EnableWebMvc
class McpConfig {
    @Bean
    WebMvcSseServerTransportProvider webMvcSseServerTransportProvider(ObjectMapper mapper) {
        return new WebMvcSseServerTransportProvider(mapper, "/mcp/message");
    }

    @Bean
    RouterFunction<ServerResponse> mcpRouterFunction(WebMvcSseServerTransportProvider transportProvider) {
        return transportProvider.getRouterFunction();
    }
}
```

--------------------------------

### Add Core MCP Dependency (Gradle)

Source: https://modelcontextprotocol.io/sdk/java/mcp-overview

This Gradle snippet adds the core Model Context Protocol (MCP) functionality to your project. It leverages platform dependencies for managing the core module and its built-in transport implementations.

```groovy
dependencies {
  implementation platform("io.modelcontextprotocol.sdk:mcp")
  //...
}
```

--------------------------------

### Configure Progress Consumer for MCP Client (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Shows how to register a progress consumer to receive progress updates from the server using the MCP client. This is useful for tracking the status of long-running operations. The consumer receives `ProgressNotification` objects.

```java
var mcpClient = McpClient.sync(transport)
        .progressConsumer((ProgressNotification progress) -> {
            System.out.println("Received progress update: " + progress.data());
        })
        .build();

mcpClient.initialize();

// Call the tool that can sends progress notifications
CallToolResult result = mcpClient.callTool(new McpSchema.CallToolRequest("progress-test", Map.of()));
```

--------------------------------

### Synchronous Completion Specification in Java

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Defines and registers a synchronous completion specification for MCP servers. It takes a prompt reference and a handler function that processes completion requests and returns a CompleteResult. This is used when building MCP server capabilities.

```java
var syncCompletionSpecification = new McpServerFeatures.SyncCompletionSpecification(
			new McpSchema.PromptReference("code_review"), (exchange, request) -> {

            // completion implementation ...

            return new McpSchema.CompleteResult(
                new CompleteResult.CompleteCompletion(
                  List.of("python", "pytorch", "pyside"),
                  10, // total
                  false // hasMore
                ));
          }
    );

    // Create a sync server with completion capabilities
    var mcpServer = McpServer.sync(mcpServerTransportProvider)
      .capabilities(ServerCapabilities.builder()
        .completions() // enable completions support
          // ...
        .build())
      // ...
      .completions(new McpServerFeatures.SyncCompletionSpecification( // register completion specification
          new McpSchema.PromptReference("code_review"), syncCompletionSpecification))
      .build();
```

--------------------------------

### Add Spring WebFlux Transport (Gradle)

Source: https://modelcontextprotocol.io/sdk/java/mcp-overview

This Gradle dependency declaration integrates Spring WebFlux-based transports (SSE, Streamable-HTTP) for the MCP SDK. It allows for reactive application development and efficient client communication.

```groovy
// Optional: Spring WebFlux-based SSE and Streamable-HTTP client and server transports
dependencies {
  implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webflux")
}
```

--------------------------------

### Configure SSE Server Transport using Servlet API (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Configures the Server-Sent Events (SSE) transport for the Model Context Protocol using the Servlet API. This implementation supports asynchronous message handling, session management, distinct SSE and message endpoints, error handling, and graceful shutdown. It requires the ObjectMapper and defines message and keep-alive intervals.

```java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.time.Duration;

@Configuration
@EnableWebMvc
public class McpServerConfig implements WebMvcConfigurer {

    @Bean
    public HttpServletSseServerTransportProvider servletSseServerTransportProvider() {
        return HttpServletSseServerTransportProvider.builder()
            .objectMapper(new ObjectMapper())
            .messageEndpoint("/mcp/message")
            .keepAliveInterval(Duration.ofSeconds(1))
            .build();
    }

    //(Optionally) To use it with a Spring Web application, you can register it as a Servlet bean
    @Bean
    public ServletRegistrationBean customServletBean(HttpServletSseServerTransportProvider transportProvider) {
        return new ServletRegistrationBean(transportProvider);
    }
}
```

--------------------------------

### Configure Stateless Streamable HTTP Server Transport (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Implements a stateless transport for microservices using WebFlux, providing unidirectional communication. It's designed for cloud-native deployments where session state is not maintained. Dependencies: ObjectMapper, WebFluxStatelessServerTransport, McpServer.

```java
@Configuration
class McpConfig {
    @Bean
    WebFluxStatelessServerTransport webFluxStatelessServerTransport(ObjectMapper mapper) {
      	return this.mcpStatelessServerTransport = WebFluxStatelessServerTransport.builder()
                .objectMapper(mapper)
                .messageEndpoint("/mcp")
                .build();
    }

    @Bean
    RouterFunction<?> mcpRouterFunction(WebFluxStatelessServerTransport transportProvider) {
        return transportProvider.getRouterFunction();
    }

    @Bean
    public McpStatelessSyncServer prepareSyncServerBuilder(WebFluxStatelessServerTransport statelessServerTransport) {
      return McpServer.sync(statelessServerTransport)
              //...
              .build();
    }

}
```

--------------------------------

### Add Spring WebFlux Transport (Maven)

Source: https://modelcontextprotocol.io/sdk/java/mcp-overview

This Maven dependency enables Spring WebFlux-based SSE and Streamable-HTTP client and server transports for the MCP SDK. It's suitable for reactive applications and high-throughput scenarios.

```xml
<!-- Optional: Spring WebFlux-based SSE and Streamable-HTTP client and server transports -->
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webflux</artifactId>
</dependency>
```

--------------------------------

### WebFlux SSE Server Transport Configuration

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Configures the Server-Sent Events (SSE) transport for WebFlux. It sets up the transport provider and the message routing function. This implementation provides reactive HTTP streaming and handles concurrent client connections.

```java
WebFluxSseServerTransportProvider webFluxSseServerTransportProvider(ObjectMapper mapper) {
    return new WebFluxSseServerTransportProvider(mapper, "/mcp/message");
}

@Bean
RouterFunction<?> mcpRouterFunction(WebFluxSseServerTransportProvider transportProvider) {
    return transportProvider.getRouterFunction();
}
```

--------------------------------

### Create STDIO Server Transport Provider (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Instantiates a StdioServerTransportProvider for in-process communication using standard input/output streams. It handles bidirectional JSON-RPC messages with non-blocking processing and serialization. Dependencies: ObjectMapper.

```java
StdioServerTransportProvider transportProvider = new StdioServerTransportProvider(new ObjectMapper());
```

--------------------------------

### Server-side Logging Implementation (Java)

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Illustrates how to send structured log messages from within a server-side tool handler using the `McpAsyncServerExchange` object. It shows enabling logging capabilities for the server and defining a tool that sends DEBUG level log messages.

```java
var tool = new McpServerFeatures.AsyncToolSpecification(
    new McpSchema.Tool("logging-test", "Test logging notifications", emptyJsonSchema),
    (exchange, request) -> {

      exchange.loggingNotification( // Use the exchange to send log messages
          McpSchema.LoggingMessageNotification.builder()
            .level(McpSchema.LoggingLevel.DEBUG)
            .logger("test-logger")
            .data("Debug message")
            .build())
        .block();

      return Mono.just(new CallToolResult("Logging test completed", false));
    });

var mcpServer = McpServer.async(mcpServerTransportProvider)
  .serverInfo("test-server", "1.0.0")
  .capabilities(
    ServerCapabilities.builder()
      .logging() // Enable logging support
      .tools(true)
      .build())
  .tools(tool)
  .build();
```

--------------------------------

### WebMVC Stateless Streamable-HTTP Server Transport Configuration

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Configures a stateless Streamable-HTTP server transport for WebMVC. This is ideal for microservices and cloud-native deployments as it simplifies session management. It supports unidirectional client-to-server communication.

```java
@Configuration
@EnableWebMvc
static class McpConfig {

  @Bean
  public WebMvcStatelessServerTransport webMvcStatelessServerTransport() {

    return WebMvcStatelessServerTransport.builder()
      .objectMapper(new ObjectMapper())
      .messageEndpoint(MESSAGE_ENDPOINT)
      .build();

  }

  @Bean
  public RouterFunction<ServerResponse> routerFunction(WebMvcStatelessServerTransport statelessServerTransport) {
    return statelessServerTransport.getRouterFunction();
  }

  @Bean
  public McpStatelessSyncServer prepareSyncServerBuilder(WebMvcStatelessServerTransport statelessServerTransport) {
    return McpServer.sync(statelessServerTransport)
            //...
            .build();
  }
}
```

--------------------------------

### Asynchronous Completion Specification in Java

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Defines and registers an asynchronous completion specification for MCP servers using Project Reactor's Mono. It accepts a prompt reference and an asynchronous handler function returning a Mono of CompleteResult. This is used when configuring async MCP server capabilities.

```java
var asyncCompletionSpecification = new McpServerFeatures.AsyncCompletionSpecification(
			new McpSchema.PromptReference("code_review"), (exchange, request) -> {

            // completion implementation ...

            return Mono.just(new McpSchema.CompleteResult(
                new CompleteResult.CompleteCompletion(
                  List.of("python", "pytorch", "pyside"),
                  10, // total
                  false // hasMore
                )));
          }
    );

    // Create a async server with completion capabilities
    var mcpServer = McpServer.async(mcpServerTransportProvider)
      .capabilities(ServerCapabilities.builder()
        .completions() // enable completions support
          // ...
        .build())
      // ...
      .completions(new McpServerFeatures.AsyncCompletionSpecification( // register completion specification
          new McpSchema.PromptReference("code_review"), asyncCompletionSpecification))
      .build();
```

--------------------------------

### Dynamically Modify HTTP Requests with ExchangeFilterFunction

Source: https://modelcontextprotocol.io/sdk/java/mcp-client

Illustrates dynamic modification of HTTP requests using ExchangeFilterFunction. This enables runtime computation of requests and access to Reactor context for obtaining information like authorization tokens.

```java
WebClient.builder()
    .filter((request, next) -> {
        return Mono.deferContextual(ctx -> {
            var transportContext = ctx.get(McpTransportContext.KEY);
            var otherInfo = ctx.get("your-context-key");
            Mono<String> token = obtainAccessToken(transportContext, otherInfo);
            return token.map(t -> {
                var newRequest = ClientRequest.from(request)
                    .header("Authorization", "Bearer " + t)
                    .build();
                // Ensure you call next.exchange to execute the HTTP request
                return next.exchange(newRequest);
            });
        });
    });
```

--------------------------------

### WebMVC Streamable-HTTP Server Transport Configuration

Source: https://modelcontextprotocol.io/sdk/java/mcp-server

Configures the Streamable-HTTP transport for WebMVC. This implementation requires the 'mcp-spring-webmvc' dependency and enables bidirectional communication via Streamable-HTTP endpoints. It also handles message routing and session management.

```java
@Configuration
@EnableWebMvc
class McpConfig {
    @Bean
    WebMvcStreamableServerTransportProvider webMvcStreamableHttpServerTransportProvider(ObjectMapper mapper) {
        return new WebMvcStreamableServerTransportProvider(mapper, "/mcp/message");
    }

    @Bean
    RouterFunction<ServerResponse> mcpRouterFunction(WebMvcStreamableServerTransportProvider transportProvider) {
        return transportProvider.getRouterFunction();
    }
}
```
Tokens:
Raw