Package io.modelcontextprotocol.server

Interface McpServer

public interface McpServer
Factory class for creating Model Context Protocol (MCP) servers. MCP servers expose tools, resources, and prompts to AI models through a standardized interface.

This class serves as the main entry point for implementing the server-side of the MCP specification. The server's responsibilities include:

  • Exposing tools that models can invoke to perform actions
  • Providing access to resources that give models context
  • Managing prompt templates for structured model interactions
  • Handling client connections and requests
  • Implementing capability negotiation

Thread Safety: Both synchronous and asynchronous server implementations are thread-safe. The synchronous server processes requests sequentially, while the asynchronous server can handle concurrent requests safely through its reactive programming model.

Error Handling: The server implementations provide robust error handling through the McpError class. Errors are properly propagated to clients while maintaining the server's stability. Server implementations should use appropriate error codes and provide meaningful error messages to help diagnose issues.

The class provides factory methods to create either:

  • McpAsyncServer for non-blocking operations with CompletableFuture responses
  • McpSyncServer for blocking operations with direct responses

Example of creating a basic synchronous server: 


 McpServer.sync(transport)
     .serverInfo("my-server", "1.0.0")
     .tool(new Tool("calculator", "Performs calculations", schema),
           args -> new CallToolResult("Result: " + calculate(args)))
     .build();
Example of creating a basic asynchronous server: 

 McpServer.async(transport)
     .serverInfo("my-server", "1.0.0")
     .tool(new Tool("calculator", "Performs calculations", schema),
           args -> Mono.just(new CallToolResult("Result: " + calculate(args))))
     .build();

Example with comprehensive asynchronous configuration: 


 McpServer.async(transport)
     .serverInfo("advanced-server", "2.0.0")
     .capabilities(new ServerCapabilities(...))
     // Register tools
     .tools(
         new McpServerFeatures.AsyncToolRegistration(calculatorTool,
             args -> Mono.just(new CallToolResult("Result: " + calculate(args)))),
         new McpServerFeatures.AsyncToolRegistration(weatherTool,
             args -> Mono.just(new CallToolResult("Weather: " + getWeather(args))))
     )
     // Register resources
     .resources(
         new McpServerFeatures.AsyncResourceRegistration(fileResource,
             req -> Mono.just(new ReadResourceResult(readFile(req)))),
         new McpServerFeatures.AsyncResourceRegistration(dbResource,
             req -> Mono.just(new ReadResourceResult(queryDb(req))))
     )
     // Add resource templates
     .resourceTemplates(
         new ResourceTemplate("file://{path}", "Access files"),
         new ResourceTemplate("db://{table}", "Access database")
     )
     // Register prompts
     .prompts(
         new McpServerFeatures.AsyncPromptRegistration(analysisPrompt,
             req -> Mono.just(new GetPromptResult(generateAnalysisPrompt(req)))),
         new McpServerFeatures.AsyncPromptRegistration(summaryPrompt,
             req -> Mono.just(new GetPromptResult(generateSummaryPrompt(req))))
     )
     .build();
Author:
Christian Tzolov, Dariusz Jędrzejczyk
See Also:

  • Method Details

    • sync

      static McpServer.SyncSpec sync(ServerMcpTransport transport)
      Starts building a synchronous MCP server that provides blocking operations. Synchronous servers process each request to completion before handling the next one, making them simpler to implement but potentially less performant for concurrent operations.
      Parameters:
      transport - The transport layer implementation for MCP communication
      Returns:
      A new instance of McpServer.SyncSpec for configuring the server.

    • async

      static McpServer.AsyncSpec async(ServerMcpTransport transport)
      Starts building an asynchronous MCP server that provides blocking operations. Asynchronous servers can handle multiple requests concurrently using a functional paradigm with non-blocking server transports, making them more efficient for high-concurrency scenarios but more complex to implement.
      Parameters:
      transport - The transport layer implementation for MCP communication
      Returns:
      A new instance of McpServer.SyncSpec for configuring the server.