MCP Java SDK

https://java.sdk.modelcontextprotocol.io/latest-snapshot/
Admin
MCP Java SDK is a comprehensive Java implementation of the Model Context Protocol enabling...
Tokens:36,921
Snippets:277
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Custom port with mkdocs serve -a

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/development

Start the mkdocs server on a custom port using the -a flag. Example uses localhost:3333.

```bash
mkdocs serve -a localhost:3333

```

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

### List and read resources with MCP client (sync and async)

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Shows how to list and read resources using the synchronous and asynchronous MCP client APIs. The sync example uses ListResourcesResult and ReadResourceResult, while the async example uses reactive streams with doOnNext and subscribe.

```java
// List available resources
ListResourcesResult resources = client.listResources();

// Read a resource
ReadResourceResult resource = client.readResource(
    ReadResourceRequest.builder("resource://uri").build()
);

```

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

// Read a resource asynchronously
client.readResource(ReadResourceRequest.builder("resource://uri").build())
    .subscribe();

```

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

### Install mkdocs-material

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/development

Install the mkdocs-material package using pip. Requires Python 3.x and pip.

```bash
pip install mkdocs-material

```

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

### List and call tools with MCP client (sync and async)

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Shows how to list and call tools using the synchronous and asynchronous MCP client APIs. The sync example uses ListToolsResult and CallToolResult, while the async example uses reactive streams with doOnNext and subscribe.

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

// Call a tool with a CallToolRequest
CallToolResult result = client.callTool(
    CallToolRequest.builder("calculator")
        .arguments(Map.of(
            "operation", "add",
            "a", 1,
            "b", 2
        ))
        .build()
);

```

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

// Call a tool asynchronously
client.callTool(CallToolRequest.builder("calculator")
        .arguments(Map.of(
            "operation", "add",
            "a", 1,
            "b", 2
        ))
        .build())
    .subscribe();

```

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

### List and get prompts synchronously with the Java SDK

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Use the synchronous client to list available prompt templates and retrieve a prompt with parameters. The example calls client.listPrompts() and client.getPrompt() with a GetPromptRequest built for the "greeting" template and a name argument.

```java
// List available prompt templates
ListPromptsResult prompts = client.listPrompts();

// Get a prompt with parameters
GetPromptResult prompt = client.getPrompt(
    GetPromptRequest.builder("greeting").arguments(Map.of("name", "World")).build()
);

```

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

### List and get prompts asynchronously with the Java SDK

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Use the asynchronous client to list prompt templates and retrieve a prompt. The example subscribes to the reactive streams returned by client.listPrompts() and client.getPrompt(), printing each prompt name as it arrives.

```java
// List available prompt templates asynchronously
client.listPrompts()
    .doOnNext(prompts -> prompts.prompts().forEach(prompt ->
        System.out.println(prompt.name())))
    .subscribe();

// Get a prompt asynchronously
client.getPrompt(GetPromptRequest.builder("greeting").arguments(Map.of("name", "World")).build())
    .subscribe();

```

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

### Reading binary resources

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Returns a binary resource as BlobResourceContents with base64-encoded data. The example reads a PNG file and sets the MIME type to image/png.

```java
var binaryResourceSpecification = new McpServerFeatures.SyncResourceSpecification(
    Resource.builder("file:///logo.png", "Logo")
        .description("Application logo")
        .mimeType("image/png")
        .build(),
    (exchange, request) -> {
        String base64Data = Base64.getEncoder().encodeToString(readLogoBytes());
        return ReadResourceResult.builder(List.of(
                BlobResourceContents.builder(request.uri(), base64Data)
                    .mimeType("image/png")
                    .build()))
            .build();
    }
);

```

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

### Register client logging consumer and set logging level

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Client-side setup to receive log messages from the server. The loggingConsumer prints each notification's data, and setLoggingLevel(INFO) filters out messages below INFO severity. Supported levels: DEBUG (0), INFO (1), NOTICE (2), WARNING (3), ERROR (4), CRITICAL (5), ALERT (6), EMERGENCY (7).

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

mcpClient.initialize();
mcpClient.setLoggingLevel(McpSchema.LoggingLevel.INFO);

```

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

### Preview documentation locally with mkdocs serve

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/development

Run the mkdocs development server from the project root. The local preview will be available at http://localhost:8000.

```bash
mkdocs serve

```

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

### Build static site with mkdocs build

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/development

Build the static site for deployment. The output is placed in the site/ directory.

```bash
mkdocs build

```

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

### Build and test with Maven wrapper

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/contribute

Build the project from source, skipping tests, and then run the tests.

```bash
./mvnw clean install -DskipTests  # skip the tests
./mvnw test                        # run tests

```

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

### Add MCP BOM to Maven or Gradle build

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/quickstart

Add the MCP BOM to your project to manage dependency versions. The Maven example imports the BOM POM, while the Gradle example uses the platform dependency handler. Replace the version number with the latest from Maven Central.

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

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

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

### Configure ServerCapabilities with resources, tools, prompts, completions, and logging

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Builds a ServerCapabilities instance enabling resource support with subscribe and listChanged, tool and prompt support with list changes notifications, completions, and logging.

```java
var capabilities = ServerCapabilities.builder()
    .resources(true, true)   // Resource support: subscribe=true, listChanged=true
    .tools(true)             // Tool support with list changes notifications
    .prompts(true)           // Prompt support with list changes notifications
    .completions()           // Enable completions support
    .logging()               // Enable logging support
    .build();
```

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

### Add Gradle dependency for `mcp-core` only

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/quickstart

Add only the core module without a JSON implementation, for example when you want to bring your own JSON serialization.

```groovy
dependencies {
    implementation "io.modelcontextprotocol.sdk:mcp-core"
}
```

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

### Enable resource subscriptions in server capabilities

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Builds a sync server with resource subscription support enabled. The resources(true, false) call sets subscribe=true and listChanged=false.

```java
McpSyncServer server = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .resources(true, false)  // subscribe=true, listChanged=false
        .build())
    .resources(myResourceSpec)
    .build();

```

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

### Add Maven dependency for `mcp-core` only

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/quickstart

Add only the core module without a JSON implementation, for example when you want to bring your own JSON serialization.

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

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

### Configure client capabilities with roots, sampling, elicitation

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Configure client capabilities for roots, sampling, and elicitation support.

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

```

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

### Create and use a synchronous MCP client

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Creates a synchronous MCP client with custom configuration, including request timeout, capabilities (roots, sampling, elicitation), and handlers. Demonstrates initialization, tool calls, resource access, prompt retrieval, root management, and graceful shutdown.

```java
// 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 -> new CreateMessageResult(response))
    .elicitation(request -> new ElicitResult(ElicitResult.Action.ACCEPT, content))
    .build();

// Initialize connection
client.initialize();

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

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

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

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

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

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

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

### Sync tool filter with addToolFilter

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Registers a synchronous tool filter that hides tools starting with 'admin-' unless the transport context indicates the caller is an admin. The filter is consulted on every listing request and never cached.

```java
McpServer.sync(transportProvider)
    .tools(publicTool, adminTool)
    .addToolFilter((transportContext, tool) ->
        !tool.name().startsWith("admin-") || isAdmin(transportContext))
    .build();

```

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

### Async API: Create server and tool with sampling

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Creates an asynchronous MCP server and defines a tool that requests language model generations via sampling. Uses Mono for reactive handling and subscribes to the tool addition. Checks client sampling support and returns an error message if unsupported.

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

// Define a tool that uses sampling
var calculatorTool = AsyncToolSpecification.builder()
    .tool(Tool.builder("ai-calculator", schema)
        .description("Performs calculations using AI")
        .build())
    .callHandler((exchange, request) -> {
        // Check if client supports sampling
        if (exchange.getClientCapabilities().sampling() == null) {
            return Mono.just(CallToolResult.builder()
                .content(List.of(new McpSchema.TextContent("Client does not support AI capabilities")))
                .build());
        }

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

        // Request sampling from the client
        return exchange.createMessage(samplingRequest)
            .map(result -> {
                String answer = ((McpSchema.TextContent) result.content()).text();
                return CallToolResult.builder()
                    .content(List.of(new McpSchema.TextContent(answer)))
                    .build();
            });
    })
    .build();

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

```

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

### Configure sampling handler and create client with sampling support

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Configure a sampling handler and create a client with sampling support. This capability allows servers to request LLM interactions through the client.

```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();

```

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

### Create a sync MCP server with custom configuration

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Creates an McpSyncServer using McpServer.sync(transportProvider) with server info, capabilities (resources, tools, prompts, completions, logging), and registers tools, resources, and prompts. Close the server when done.

```java
// Create a server with custom configuration
McpSyncServer syncServer = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .resources(false, true)  // Resource support: subscribe=false, listChanged=true
        .tools(true)             // Enable tool support with list changes
        .prompts(true)           // Enable prompt support with list changes
        .completions()           // Enable completions support
        .logging()               // Enable logging support
        .build())
    .build();

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

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

```

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

### Create MCP servers with different transport providers

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Shows three server creation patterns: single-session with SSE transport, Streamable HTTP, and stateless (no session management). Each uses McpServer.sync() with a different transport provider.

```java
// Single-session server with SSE transport provider
McpSyncServer server = McpServer.sync(sseTransportProvider).build();

// Streamable HTTP server
McpSyncServer server = McpServer.sync(streamableTransportProvider).build();

// Stateless server (no session management)
McpSyncServer server = McpServer.sync(statelessTransport).build();

```

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

### McpSyncClient.initialize()

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Initializes the MCP client and negotiates the protocol version with the server. The negotiated version is returned in the InitializeResult.

```APIDOC
## [SYNC] McpSyncClient.initialize()

### Description
Initializes the MCP client and negotiates the protocol version with the server. The negotiated version is returned in the InitializeResult.

### Method
SYNC

### Endpoint
McpSyncClient.initialize()

### Parameters
None

### Request Example
```java
McpSyncClient client = McpClient.sync(transport).build();
InitializeResult initResult = client.initialize();
```

### Response
#### Success Response
- **protocolVersion** (String) - The negotiated protocol version.

#### Response Example
```java
String negotiatedVersion = initResult.protocolVersion();
```
```

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

### Create an async MCP server with custom configuration

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Creates an McpAsyncServer using McpServer.async(transportProvider) with the same capabilities as the sync version. Registration and close operations return reactive streams that must be subscribed to; logs are emitted on success.

```java
// Create an async server with custom configuration
McpAsyncServer asyncServer = McpServer.async(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .resources(false, true)  // Resource support: subscribe=false, listChanged=true
        .tools(true)             // Enable tool support with list changes
        .prompts(true)           // Enable prompt support with list changes
        .completions()           // Enable completions support
        .logging()               // Enable logging 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();

```

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

### Sync API: Create server and tool with sampling

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Creates a synchronous MCP server and defines a tool that requests language model generations via sampling. Checks client sampling support and returns an error message if unsupported. Uses CreateMessageRequest with model preferences and system prompt.

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

// Define a tool that uses sampling
var calculatorTool = SyncToolSpecification.builder()
    .tool(Tool.builder("ai-calculator", schema)
        .description("Performs calculations using AI")
        .build())
    .callHandler((exchange, request) -> {
        // Check if client supports sampling
        if (exchange.getClientCapabilities().sampling() == null) {
            return CallToolResult.builder()
                .content(List.of(new McpSchema.TextContent("Client does not support AI capabilities")))
                .build();
        }

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

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

        // Process the result
        String answer = ((McpSchema.TextContent) result.content()).text();
        return CallToolResult.builder()
            .content(List.of(new McpSchema.TextContent(answer)))
            .build();
    })
    .build();

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

```

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

### McpServer.sync(transportProvider).capabilities(...).resources(...).build()

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Builds a synchronous MCP server with resource subscription support enabled.

```APIDOC
## [SYNC] McpServer.sync(transportProvider).capabilities(...).resources(...).build()

### Description
Builds a synchronous MCP server with resource subscription support enabled.

### Method
Server builder

### Endpoint
McpServer.sync(transportProvider)

### Parameters
#### Builder Parameters
- **serverInfo** (String, String) - Required - Server name and version.
- **capabilities** (ServerCapabilities) - Required - Server capabilities, including resource subscription settings.
- **resources** (ResourceSpecification) - Required - The resource specification to register.

### Request Example
```java
McpSyncServer server = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .resources(true, false)  // subscribe=true, listChanged=false
        .build())
    .resources(myResourceSpec)
    .build();
```

### Response
#### Success Response
- **McpSyncServer** - The built synchronous MCP server instance.
```

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

### Clone the repository

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/contribute

Clone your fork of the repository and navigate into the project directory.

```bash
git clone https://github.com/YOUR-USERNAME/java-sdk.git
cd java-sdk

```

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

### Negotiate protocol version with initialize()

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

During initialize(), the client sends the list of protocol versions its transport supports (newest first) and the server picks one it also supports. The negotiated version is returned on the InitializeResult.

```java
McpSyncClient client = McpClient.sync(transport).build();

InitializeResult initResult = client.initialize();
String negotiatedVersion = initResult.protocolVersion();

```

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

### client.listResources() (async)

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Lists the resources available on the MCP server asynchronously. Returns a `Mono<ListResourcesResult>` that emits the resource definitions.

```APIDOC
## [ASYNC] client.listResources()

### Description
Lists the resources available on the MCP server asynchronously. Returns a `Mono<ListResourcesResult>` that emits the resource definitions.

### Method
Async API method

### Endpoint
`client.listResources()`

### Parameters
None

### Response
#### Success Response
- **resources** (List<McpSchema.Resource>) - The list of available resources.

#### Response Example
```java
client.listResources()
    .doOnNext(resources -> resources.resources().forEach(resource ->
        System.out.println(resource.name())))
    .subscribe();
```
```

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

### Project structure tree

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/development

Shows the directory layout of the documentation project, including the docs/ folder and mkdocs.yml configuration file.

```text
docs/
├── index.md            # Overview page
├── quickstart.md       # Quickstart guide
├── client.md           # MCP Client documentation
├── server.md           # MCP Server documentation
├── contributing.md     # Contributing guide
├── development.md      # This page
├── images/             # Images and diagrams
└── stylesheets/        # Custom CSS
mkdocs.yml              # MkDocs configuration

```

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

### client.listTools() (async)

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Lists the tools available on the MCP server asynchronously. Returns a `Mono<ListToolsResult>` that emits the tool definitions.

```APIDOC
## [ASYNC] client.listTools()

### Description
Lists the tools available on the MCP server asynchronously. Returns a `Mono<ListToolsResult>` that emits the tool definitions.

### Method
Async API method

### Endpoint
`client.listTools()`

### Parameters
None

### Response
#### Success Response
- **tools** (List<McpSchema.Tool>) - The list of available tools.

#### Response Example
```java
client.listTools()
    .doOnNext(tools -> tools.tools().forEach(tool ->
        System.out.println(tool.name())))
    .subscribe();
```
```

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

### Configure Logging Consumer and Set Logging Level

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Registers a logging consumer, initializes the client, sets the minimum logging level to INFO, and calls a tool that sends logging notifications. Messages below the set level are filtered out.

```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(CallToolRequest.builder("logging-test").build());
```

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

### Create and use an asynchronous MCP client

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Creates an asynchronous MCP client using reactive Mono chains. Configures capabilities, sampling, elicitation, and change/progress consumers, then chains initialization, tool calls, resource reads, prompt retrieval, root management, and graceful shutdown.

```java
// 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(request -> Mono.just(new ElicitResult(ElicitResult.Action.ACCEPT, content)))
    .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);
    }))
    .progressConsumer(progress -> Mono.fromRunnable(() -> {
        logger.info("Progress: {}", progress);
    }))
    .build();

// Initialize connection and use features
client.initialize()
    .flatMap(initResult -> client.listTools())
    .flatMap(tools -> {
        return client.callTool(CallToolRequest.builder("calculator")
            .arguments(Map.of("operation", "add", "a", 2, "b", 3))
            .build());
    })
    .flatMap(result -> {
        return client.listResources()
            .flatMap(resources ->
                client.readResource(ReadResourceRequest.builder("resource://uri").build())
            );
    })
    .flatMap(resource -> {
        return client.listPrompts()
            .flatMap(prompts ->
                client.getPrompt(GetPromptRequest.builder("greeting")
                    .arguments(Map.of("name", "Spring"))
                    .build())
            );
    })
    .flatMap(prompt -> {
        return client.addRoot(new Root("file:///path", "description"))
            .then(client.removeRoot("file:///path"));
    })
    .doFinally(signalType -> {
        client.closeGracefully().subscribe();
    })
    .subscribe();
```

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

### client.listResources()

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Lists the resources available on the MCP server. Returns a `ListResourcesResult` containing the resource definitions.

```APIDOC
## [SYNC] client.listResources()

### Description
Lists the resources available on the MCP server. Returns a `ListResourcesResult` containing the resource definitions.

### Method
Sync API method

### Endpoint
`client.listResources()`

### Parameters
None

### Response
#### Success Response
- **resources** (List<McpSchema.Resource>) - The list of available resources.

#### Response Example
```java
ListResourcesResult resources = client.listResources();
```
```

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

### Configure Elicitation Handlers and Build Client

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Configures form and URL elicitation handlers and builds a synchronous MCP client with elicitation enabled. The handlers return an ElicitResult with an action (ACCEPT, DECLINE, or CANCEL) and the user-provided content.

```java
// Configure form elicitation handler
Function<ElicitFormRequest, ElicitResult> formElicitationHandler = request -> {
    // Present the request to the user and collect their response
    // The request contains a message and a schema describing the expected input
    Map<String, Object> userResponse = collectUserInput(request.message(), request.requestedSchema());
    return new ElicitResult(ElicitResult.Action.ACCEPT, userResponse);
};

// Configure URL elicitation handler
Function<ElicitUrlRequest, ElicitResult> urlElicitationHandler = request -> {
    // Prompt the user to visit the URL
    // e.g. openBrowser(request.url());
    return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of());
};

// Create client with elicitation support
var client = McpClient.sync(transport)
    .capabilities(ClientCapabilities.builder()
        .elicitation(true, true) // enables both form and URL elicitation
        .build())
    .elicitation(formElicitationHandler)
    .urlElicitation(urlElicitationHandler)
    .build();
```

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

### client.listTools()

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Lists the tools available on the MCP server. Returns a `ListToolsResult` containing the tool definitions.

```APIDOC
## [SYNC] client.listTools()

### Description
Lists the tools available on the MCP server. Returns a `ListToolsResult` containing the tool definitions.

### Method
Sync API method

### Endpoint
`client.listTools()`

### Parameters
None

### Response
#### Success Response
- **tools** (List<McpSchema.Tool>) - The list of available tools.

#### Response Example
```java
ListToolsResult tools = client.listTools();
```
```

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

### Subscribe and unsubscribe to resource updates (sync and async)

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Shows how to subscribe and unsubscribe to resource updates using the synchronous and asynchronous MCP client APIs. Requires the server to advertise resources.subscribe support; the SDK re-reads the resource on notification and delivers updated contents to the registered consumer.

```java
McpSyncClient client = McpClient.sync(transport)
    .resourcesUpdateConsumer(contents -> {
        // called with the updated resource contents after each notification
        System.out.println("Resource updated: " + contents);
    })
    .build();

client.initialize();

// Subscribe to a specific resource URI
client.subscribeResource(McpSchema.SubscribeRequest.builder("custom://resource").build());

// ... later, stop receiving updates
client.unsubscribeResource(McpSchema.UnsubscribeRequest.builder("custom://resource").build());

```

```java
McpAsyncClient client = McpClient.async(transport)
    .resourcesUpdateConsumer(contents -> Mono.fromRunnable(() -> {
        System.out.println("Resource updated: " + contents);
    }))
    .build();

client.initialize()
    .then(client.subscribeResource(McpSchema.SubscribeRequest.builder("custom://resource").build()))
    .subscribe();

// ... later, stop receiving updates
client.unsubscribeResource(McpSchema.UnsubscribeRequest.builder("custom://resource").build())
    .subscribe();

```

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

### Add Gradle dependencies for Jackson 2.x support

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/quickstart

Use Jackson 2.x instead of Jackson 3.x by adding `mcp-core` and `mcp-json-jackson2` dependencies.

```groovy
dependencies {
    implementation "io.modelcontextprotocol.sdk:mcp-core"
    implementation "io.modelcontextprotocol.sdk:mcp-json-jackson2"
}
```

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

### Sync completion specification for a prompt reference

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Registers a synchronous completion handler for a prompt reference named "greeting". The handler receives the partial argument value and returns matching suggestions wrapped in a CompleteResult.

```java
// Sync completion specification
var syncCompletionSpec = new McpServerFeatures.SyncCompletionSpecification(
    new McpSchema.PromptReference("greeting"),  // Reference to a prompt
    (exchange, request) -> {
        String argName = request.argument().name();
        String partial = request.argument().value();
        // Return matching suggestions
        List<String> suggestions = findMatches(partial);
        return new McpSchema.CompleteResult(
            new McpSchema.CompleteResult.CompleteCompletion(suggestions, suggestions.size(), false)
        );
    }
);

```

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

### ClientCapabilities.elicitation

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Enable form and URL elicitation support on the client.

```APIDOC
## Enable Elicitation Capabilities

### Description
Enable form and URL elicitation support on the client by setting the `elicitation` capability to `true` for both forms and URLs.

### Method
Builder method

### Endpoint
`ClientCapabilities.builder().elicitation(boolean, boolean)`

### Parameters
- **formElicitation** (boolean) - Required - Set to `true` to enable form elicitation.
- **urlElicitation** (boolean) - Required - Set to `true` to enable URL elicitation.

### Request Example
```java
ClientCapabilities.builder()
    .elicitation(true, true)
    .build()
```
```

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

### client.listTools(cursor)

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Lists the tools available on the MCP server with pagination. Accepts an optional opaque cursor string and returns a page of results with a `nextCursor` for subsequent pages.

```APIDOC
## [SYNC] client.listTools(cursor)

### Description
Lists the tools available on the MCP server with pagination. Accepts an optional opaque cursor string and returns a page of results with a `nextCursor` for subsequent pages.

### Method
Sync API method

### Endpoint
`client.listTools(cursor)`

### Parameters
#### Query Parameters
- **cursor** (String) - Optional - Opaque cursor for pagination. Pass `null` for the first page.
- **_meta** (Map<String,Object>) - Optional - Request metadata to pass through to the server.

### Response
#### Success Response
- **tools** (List<McpSchema.Tool>) - The list of tools on this page.
- **nextCursor** (String) - Non-null if more pages remain; `null` when all pages have been retrieved.

#### Response Example
```java
List<McpSchema.Tool> allTools = new ArrayList<>();
String cursor = null;
do {
    ListToolsResult page = client.listTools(cursor);
    allTools.addAll(page.tools());
    cursor = page.nextCursor();
} while (cursor != null);
```
```

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

### Request form elicitation with SyncToolSpecification

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Creates a tool that checks if the client supports elicitation, sends a form request asking for boolean confirmation, and returns a result based on whether the user accepts or declines.

```java
var tool = SyncToolSpecification.builder()
    .tool(Tool.builder("confirm-action", schema)
        .description("Confirms an action with the user")
        .build())
    .callHandler((exchange, request) -> {
        // Check if client supports elicitation
        if (exchange.getClientCapabilities().elicitation() == null) {
            return CallToolResult.builder()
                .content(List.of(new McpSchema.TextContent("Client does not support elicitation")))
                .build();
        }

        // Request user confirmation
        ElicitRequest elicitRequest = ElicitFormRequest.builder("Do you want to proceed with this action?", Map.of(
                "type", "object",
                "properties", Map.of("confirmed", Map.of("type", "boolean"))
            ))
            .build();

        ElicitResult result = exchange.elicit(elicitRequest);

        if (result.action() == ElicitResult.Action.ACCEPT) {
            // User accepted
            return CallToolResult.builder()
                .content(List.of(new McpSchema.TextContent("Action confirmed")))
                .build();
        } else {
            return CallToolResult.builder()
                .content(List.of(new McpSchema.TextContent("Action declined")))
                .build();
        }
    })
    .build();
```

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

### SyncToolSpecification with mixed content

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Shows how to build a tool specification that returns a CallToolResult containing text, image, audio, and embedded resource content.

```APIDOC
## SyncToolSpecification.builder()

### Description
Builds a synchronous tool specification with a call handler that returns a CallToolResult containing mixed content types (text, image, audio, embedded resource).

### Method
builder()

### Endpoint
N/A (SDK method)

### Parameters
#### Builder Parameters
- **tool** (Tool) - Required - The tool definition with name and input schema.
- **callHandler** (BiFunction<Exchange, Request, CallToolResult>) - Required - The handler that processes the tool call and returns a CallToolResult.

### Request Example
```java
var syncToolSpecification = SyncToolSpecification.builder()
    .tool(Tool.builder("generate-report", schema)
        .description("Generates a report with mixed content")
        .build())
    .callHandler((exchange, request) -> {
        var text = TextContent.builder("Report summary:").build();
        var image = ImageContent.builder(base64PngData, "image/png").build();
        var audio = AudioContent.builder(base64WavData, "audio/wav").build();
        var resourceContents = TextResourceContents.builder("report://details", "Full details...")
            .mimeType("text/plain")
            .build();
        var embeddedResource = EmbeddedResource.builder(resourceContents).build();
        return CallToolResult.builder()
            .content(List.of(text, image, audio, embeddedResource))
            .isError(false)
            .build();
    })
    .build();
```

### Response
#### Success Response
- **CallToolResult** - The result object containing a list of content items and an error flag.

#### Response Example
```java
CallToolResult.builder()
    .content(List.of(text, image, audio, embeddedResource))
    .isError(false)
    .build();
```

### Notes
- `ImageContent.builder(data, mimeType)` and `AudioContent.builder(data, mimeType)` take base64-encoded binary data.
- `EmbeddedResource.builder(resourceContents)` wraps either a `TextResourceContents` or `BlobResourceContents`.
```

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

### Sync prompt specification

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Defines a synchronous prompt specification named 'greeting' with a required 'name' argument. The handler returns a GetPromptResult with messages and description.

```java
// Sync prompt specification
var syncPromptSpecification = new McpServerFeatures.SyncPromptSpecification(
    Prompt.builder("greeting")
        .description("description")
        .arguments(List.of(
            PromptArgument.builder("name")
                .description("description")
                .required(true)
                .build()
        ))
        .build(),
    (exchange, request) -> {
        // Prompt implementation
        return GetPromptResult.builder(messages).description(description).build();
    }
);

```

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

### Add Maven dependencies for Jackson 2.x support

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/quickstart

Use Jackson 2.x instead of Jackson 3.x by adding `mcp-core` and `mcp-json-jackson2` dependencies.

```xml
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-core</artifactId>
</dependency>
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-json-jackson2</artifactId>
</dependency>
```

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

### Create a feature branch

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/contribute

Create a new branch for your feature work.

```bash
git checkout -b feature/your-feature-name

```

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

### Register tool directly on server builder with toolCall

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Registers a tool directly on the McpServer builder using the toolCall convenience method, providing a Tool definition and a call handler.

```java
var server = McpServer.sync(transportProvider)
    .toolCall(
        Tool.builder("echo", schema).description("Echoes input").build(),
        (exchange, request) -> CallToolResult.builder()
            .content(List.of(new McpSchema.TextContent(request.arguments().get("text").toString())))
            .build()
    )
    .build();
```

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

### McpServer.async(transportProvider).addToolFilter(...)

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Registers an asynchronous tool filter to control tool advertisement per request.

```APIDOC
## [ASYNC] McpServer.async(transportProvider).addToolFilter(...)

### Description
Registers an asynchronous tool filter on an MCP server to control which tools are advertised in the `tools/list` response per request. The filter receives the `McpTransportContext` and returns a `Mono<Boolean>` to indicate whether the tool should be listed.

### Method
Async builder method

### Endpoint
N/A (SDK builder method)

### Parameters
#### Filter Lambda
- **transportContext** (McpTransportContext) - Required - The context extracted from the current request.
- **tool** (McpTool) - Required - The tool being evaluated.

### Request Example
```java
McpServer.async(transportProvider)
    .tools(publicTool, adminTool)
    .addToolFilter((transportContext, tool) -> {
        if (!tool.name().startsWith("admin-")) {
            return Mono.just(true);
        }
        return isAdmin(transportContext); // Mono<Boolean>
    })
    .build();
```

### Response
#### Success Response
- **Mono<Boolean>** (Mono<Boolean>) - `Mono.just(true)` to advertise, `Mono.just(false)` to hide, or `Mono.empty()` to omit the tool.

#### Response Example
N/A (returns Mono<Boolean> from lambda)
```

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

### Paginate through tools with cursor until nextCursor is null

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/client

Pagination loop for listTools that collects all tools by following the nextCursor until it becomes null. The same pattern applies to listResources, listResourceTemplates, and listPrompts.

```java
List<McpSchema.Tool> allTools = new ArrayList<>();
String cursor = null;
do {
    ListToolsResult page = client.listTools(cursor);
    allTools.addAll(page.tools());
    cursor = page.nextCursor();
} while (cursor != null);

```

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

### McpServerFeatures.SyncResourceTemplateSpecification

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Creates a synchronous resource template specification with a handler function for reading parameterized resources.

```APIDOC
## [SYNC] McpServerFeatures.SyncResourceTemplateSpecification

### Description
Creates a synchronous resource template specification that allows servers to expose parameterized resources using URI templates.

### Method
Sync resource template specification constructor

### Endpoint
McpServerFeatures.SyncResourceTemplateSpecification

### Parameters
#### Constructor Parameters
- **resourceTemplate** (ResourceTemplate) - Required - The resource template definition with URI template, name, description, and MIME type.
- **handler** (BiFunction<Exchange, ReadResourceRequest, ReadResourceResult>) - Required - The handler function that reads the resource at the requested URI.

### Request Example
```java
var resourceTemplateSpec = new McpServerFeatures.SyncResourceTemplateSpecification(
    ResourceTemplate.builder("file://{path}", "File Resource")
        .description("Access files by path")
        .mimeType("application/octet-stream")
        .build(),
    (exchange, request) -> {
        // Read the file at the requested URI
        return ReadResourceResult.builder(contents).build();
    }
);
```

### Response
#### Success Response
- **ReadResourceResult** - The result of the resource read operation.
```

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

### McpServerFeatures.SyncResourceSpecification

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Creates a synchronous resource specification with a handler function for reading resources.

```APIDOC
## [SYNC] McpServerFeatures.SyncResourceSpecification

### Description
Creates a synchronous resource specification that provides context to AI models by exposing data such as file contents, database records, API responses, system information, and application state.

### Method
Sync resource specification constructor

### Endpoint
McpServerFeatures.SyncResourceSpecification

### Parameters
#### Constructor Parameters
- **resource** (Resource) - Required - The resource definition with URI, name, description, and MIME type.
- **handler** (BiFunction<Exchange, ReadResourceRequest, ReadResourceResult>) - Required - The handler function that implements the resource read operation.

### Request Example
```java
var syncResourceSpecification = new McpServerFeatures.SyncResourceSpecification(
    Resource.builder("custom://resource", "name")
        .description("description")
        .mimeType("text/plain")
        .build(),
    (exchange, request) -> {
        // Resource read implementation
        return ReadResourceResult.builder(contents).build();
    }
);
```

### Response
#### Success Response
- **ReadResourceResult** - The result of the resource read operation.

#### Response Example
```java
ReadResourceResult.builder(contents).build()
```
```

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

### Create HttpServletStreamableServerTransportProvider

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Creates a Servlet-based Streamable HTTP server transport, included in the core mcp module. Supports efficient bidirectional HTTP communication, session management, keep-alive pings (default every 30 minutes, configurable via keepAliveInterval), idle session eviction (default every 30 minutes, configurable via sessionSweepInterval), security validation, and graceful shutdown.

```java
HttpServletStreamableServerTransportProvider transportProvider =
    HttpServletStreamableServerTransportProvider.builder()
        .jsonMapper(jsonMapper)
        .mcpEndpoint("/mcp")
        .build();

```

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

### Sync completion specification for a resource template argument

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Registers a synchronous completion handler for a resource template reference "file://{path}". The handler suggests values for the template's URI parameters, such as matching file paths.

```java
// Sync completion specification for a resource template argument
var syncResourceCompletionSpec = new McpServerFeatures.SyncCompletionSpecification(
    new McpSchema.ResourceReference("file://{path}"),  // Reference to a resource template
    (exchange, request) -> {
        String argName = request.argument().name();
        String partial = request.argument().value();
        // Return matching suggestions, e.g. matching file paths
        List<String> suggestions = findMatchingPaths(partial);
        return new McpSchema.CompleteResult(
            new McpSchema.CompleteResult.CompleteCompletion(suggestions, suggestions.size(), false)
        );
    }
);

```

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

### Async completion specification for a prompt reference

Source: https://java.sdk.modelcontextprotocol.io/latest-snapshot/server

Registers an asynchronous completion handler for a prompt reference named "greeting". The handler returns a Mono wrapping the CompleteResult with matching suggestions.

```java
// Async completion specification
var asyncCompletionSpec = new McpServerFeatures.AsyncCompletionSpecification(
    new McpSchema.PromptReference("greeting"),
    (exchange, request) -> {
        String argName = request.argument().name();
        String partial = request.argument().value();
        List<String> suggestions = findMatches(partial);
        return Mono.just(new McpSchema.CompleteResult(
            new McpSchema.CompleteResult.CompleteCompletion(suggestions, suggestions.size(), false)
        ));
    }
);

```
Tokens:
Raw