MCP Server Howto

🚀 Comprehensive Guide to MCP Protocol Java SDK

The MCP (Model Context Protocol) is an open standard for connecting and managing model contexts, widely used in the development of artificial intelligence and distributed systems. This guide provides detailed instructions on how to use the Java SDK for the MCP protocol in your development.

🚀 Quick Start

Creating a Client

Use the McpClient factory to create an MCP client:

import io.modelcontextprotocol.client.McpClient;

public class McpExample {
    public static void main(String[] args) {
        // Create a default MCP client instance
        try (var client = McpClient.createDefault()) {
            // Perform operations using the client
            System.out.println("MCP client created");
        }
    }
}

Creating a Server

Use the McpServer factory to create an MCP server:

import io.modelcontextprotocol.server.McpServer;

public class McpExample {
    public static void main(String[] args) {
        // Create a default MCP server instance
        try (var server = McpServer.createDefault()) {
            // Perform operations using the server
            System.out.println("MCP server created");
        }
    }
}

✨ Features

Client and Server

• Client: Responsible for initiating requests and receiving responses.
• Server: Responsible for handling client requests and returning responses.

Requests and Responses

All MCP operations are based on the request - response model. Here is a simple interaction example:

// Initiate a request
var request = createRequest();
client.sendRequest(request);

// Handle the response
client.receiveResponse().thenAccept(response -> {
    System.out.println("Received response: " + response.toString());
});

📦 Installation

Downloading the SDK

Visit the official MCP website to download the appropriate version of the MCP Java SDK for your project.

Environment Configuration

1. Add Dependencies Add the MCP SDK dependency to your project build file (e.g., pom.xml or build.gradle):

<dependency>
    <groupId>io.modelcontextprotocol</groupId>
    <artifactId>mcp-java-sdk</artifactId>
    <version>${mcp.sdk.version}</version>
</dependency>

2. Configure Environment Variables Ensure that the JDK and MCP SDK are correctly installed, and add the MCP tools to the system path.

💻 Usage Examples

Basic Usage

The above code snippets for creating clients and servers are basic usage examples.

Advanced Usage

Resource and Tool Management

Resource Templates

Use resource templates to dynamically generate resource content:

import io.modelcontextprotocol.schema.McpSchema;

public class McpExample {
    public static void main(String[] args) {
        // Create a simple resource template
        var resourceTemplate = new Template() {
            @Override
            public String getResourceId() {
                return "example_resource";
            }

            @Override
            public Map<String, Object> getParameters() {
                return Collections.emptyMap();
            }
        };

        // Apply the resource template to generate content
        McpSchema.applyTemplate(resourceTemplate);
    }
}

Tool Execution

Define and execute custom tools:

import io.modelcontextprotocol.tool.McpTool;

public class McpExample {
    public static void main(String[] args) {
        // Define a simple tool
        var tool = new Tool() {
            @Override
            public String getName() {
                return "example_tool";
            }

            @Override
            public void execute(List<String> arguments, Callback<String> callback) {
                callback.onResult("Execution completed: " + arguments);
            }
        };

        // Execute the tool and get the result
        var result = McpTool.execute(tool, List.of("arg1", "arg2"));
        System.out.println(result);
    }
}

📚 Documentation

Best Practices

General Guidelines

1. Use BOM - Always use the MCP BOM to ensure compatible versions of all components.
2. Close Connections - Always close client and server instances after processing is complete.
3. Handle Errors - Implement appropriate error handling for all MCP operations.
4. Validate Input - Validate all input data before processing.
5. Choose the Right Transport Mechanism - Select an appropriate transport method based on the usage scenario.

Client - Side

1. Reuse Clients - Create a single client instance and use it multiple times.