java-sdk/docs/ref-server.md

MCP Server Reference

McpServer Factory

org.springframework.ai.mcp.server.McpServer

The McpServer class serves as a factory for creating Model Context Protocol (MCP) servers. It provides the main entry point for establishing MCP servers, offering both synchronous and asynchronous server implementations.

Overview

The server factory uses a builder pattern for flexible configuration, allowing you to customize various aspects of the server including server information, capabilities, tools, resource providers, and prompt providers.

Server Types

The factory can create two types of servers:

• McpAsyncServer for non-blocking operations
• McpSyncServer for blocking operations

Builder Configuration

Basic Usage

McpServer.using(transport)
    .serverInfo("my-server", "1.0.0")
    .addTool(new MyToolHandler())
    .async(); // or .sync()

Builder Methods

using(McpTransport transport)

public static Builder using(McpTransport transport)

Start building an MCP server with the specified transport.

serverInfo(Implementation serverInfo)

public Builder serverInfo(McpSchema.Implementation serverInfo)

Set the server implementation information.

serverInfo(String name, String version)

public Builder serverInfo(String name, String version)

Set the server implementation information using name and version.

serverCapabilities(ServerCapabilities capabilities)

public Builder serverCapabilities(McpSchema.ServerCapabilities serverCapabilities)

Set the server capabilities configuration.

addTool(ToolHandler handler)

public <T extends McpAsyncServer.ToolHandler> Builder addTool(T toolHandler)

Add a tool handler to the server.

tool(Tool tool, Function<Map<String, Object>, CallToolResult> handler)

public Builder tool(McpSchema.Tool tool, Function<Map<String, Object>, McpSchema.CallToolResult> handler)

Add a tool with its handler function.

addTools(List handlers)

public Builder addTools(List<ToolHandler> toolHandlers)

Add multiple tool handlers to the server.

resourcesProvider(Function<String, List> provider)

public Builder resourcesProvider(Function<String, List<McpSchema.Resource>> resourcesProvider)

Set the resources provider function.

promptsProvider(Function<String, List> provider)

public Builder promptsProvider(Function<String, List<McpSchema.Prompt>> promptsProvider)

Set the prompts provider function.

sync()

public McpSyncServer sync()

Build and return a synchronous MCP server.

async()

public AsyncServerBuilder async()

Build and return an asynchronous server builder.

Usage Examples

Creating a Basic Server

McpTransport transport = // obtain transport instance
McpServer.using(transport)
    .serverInfo("my-server", "1.0.0")
    .sync();

Creating a Server with Tools

McpServer.using(transport)
    .serverInfo("calculation-server", "1.0.0")
    .tool(
        new McpSchema.Tool("calculate", "Performs calculations", Map.of(
            "operation", Map.of("type", "string"),
            "numbers", Map.of("type", "array")
        )),
        args -> {
            // Handle calculation
            return new McpSchema.CallToolResult(/* result */);
        }
    )
    .async();

Creating a Server with Resources and Prompts

McpServer.using(transport)
    .serverInfo("content-server", "1.0.0")
    .resourcesProvider(cursor -> {
        // Return list of resources based on cursor
        return List.of(/* resources */);
    })
    .promptsProvider(cursor -> {
        // Return list of prompts based on cursor
        return List.of(/* prompts */);
    })
    .sync();

Implementation Notes

• The server factory uses a builder pattern for configuration
• Default server info is "mcp-server" version "1.0.0" if not specified
• Tool handlers must be thread-safe as they may be called concurrently
• The synchronous server is implemented as a wrapper around the asynchronous server
• Resource and prompt providers use cursor-based pagination
• The AsyncServerBuilder allows adding tools after server creation

Tool Handler Interface

public interface ToolHandler {
    String getName();
    String getDescription();
    Map<String, Object> getInputSchema();
    McpSchema.CallToolResult call(Map<String, Object> arguments);
}

Tool handlers implement this interface to define:

• Tool name and description
• Input schema for validation
• Execution logic in the call method