LangChain4j MCP Server Implementation Patterns

Implement Model Context Protocol (MCP) servers with LangChain4j to extend AI capabilities with standardized tools, resources, and prompt templates.

When to Use

Use this skill when building:

• AI applications requiring external tool integration
• Enterprise MCP servers with multi-domain support (GitHub, databases, APIs)
• Dynamic tool providers with context-aware filtering
• Resource-based data access systems for AI models
• Prompt template servers for standardized AI interactions
• Scalable AI agents with resilient tool execution
• Multi-modal AI applications with diverse data sources
• Spring Boot applications with MCP integration
• Production-ready MCP servers with security and monitoring

Quick Start

Basic MCP Server

Create a simple MCP server with one tool:

MCPServer server = MCPServer.builder()
    .server(new StdioServer.Builder())
    .addToolProvider(new SimpleWeatherToolProvider())
    .build();

server.start();

Spring Boot Integration

Configure MCP server in Spring Boot:

@Bean
public MCPSpringConfig mcpServer(List<ToolProvider> tools) {
    return MCPSpringConfig.builder()
        .tools(tools)
        .server(new StdioServer.Builder())
        .build();
}

Core Concepts

MCP Architecture

MCP standardizes AI application connections:

• Tools: Executable functions (database queries, API calls)
• Resources: Data sources (files, schemas, documentation)
• Prompts: Pre-configured templates for tasks
• Transport: Communication layer (stdio, HTTP, WebSocket)

AI Application ←→ MCP Client ←→ Transport ←→ MCP Server ←→ External Service

Key Components

• MCPServer: Main server instance with configuration
• ToolProvider: Tool specification and execution interface
• ResourceListProvider/ResourceReadHandler: Resource access
• PromptListProvider/PromptGetHandler: Template management
• Transport: Communication mechanisms (stdio, HTTP)

Implementation Patterns

Tool Provider Pattern

Create tools with proper schema validation:

class WeatherToolProvider implements ToolProvider {

    @Override
    public List<ToolSpecification> listTools() {
        return List.of(ToolSpecification.builder()
            .name("get_weather")
            .description("Get weather for a city")
            .inputSchema(Map.of(
                "type", "object",
                "properties", Map.of(
                    "city", Map.of("type", "string", "description", "City name")
                ),
                "required", List.of("city")
            ))
            .build());
    }

    @Override
    public String executeTool(String name, String arguments) {
        // Parse arguments and execute tool logic
        return "Weather data result";
    }
}

Resource Provider Pattern

Provide static and dynamic resources:

class CompanyResourceProvider
    implements ResourceListProvider, ResourceReadHandler {

    @Override
    public List<McpResource> listResources() {
        return List.of(
            McpResource.builder()
                .uri("policies")
                .name("Company Policies")
                .mimeType("text/plain")
                .build()
        );
    }

    @Override
    public String readResource(String uri) {
        return loadResourceContent(uri);
    }
}

Prompt Template Pattern

Create reusable prompt templates:

class PromptTemplateProvider
    implements PromptListProvider, PromptGetHandler {

    @Override
    public List<Prompt> listPrompts() {
        return List.of(
            Prompt.builder()
                .name("code-review")
                .description("Review code for quality")
                .build()
        );
    }

    @Override
    public String getPrompt(String name, Map<String, String> args) {
        return applyTemplate(name, args);
    }
}

Transport Configuration

Stdio Transport

Local process communication:

McpTransport transport = new StdioMcpTransport.Builder()
    .command(List.of("npm", "exec", "@modelcontextprotocol/server-everything"))
    .logEvents(true)
    .build();

HTTP Transport

Remote server communication:

McpTransport transport = new HttpMcpTransport.Builder()
    .sseUrl("http://localhost:3001/sse")
    .logRequests(true)
    .logResponses(true)
    .build();

Client Integration

MCP Client Setup

Connect to MCP servers:

McpClient client = new DefaultMcpClient.Builder()
    .key("my-client")
    .transport(transport)
    .cacheToolList(true)
    .build();

// List available tools
List<ToolSpecification> tools = client.listTools();

Tool Provider Integration

Bridge MCP servers to LangChain4j AI services:

McpToolProvider provider = McpToolProvider.builder()
    .mcpClients(mcpClient)
    .failIfOneServerFails(false)
    .filter((client, tool) -> filterByPermissions(tool))
    .build();

// Integrate with AI service
AIAssistant assistant = AiServices.builder(AIAssistant.class)
    .chatModel(chatModel)
    .toolProvider(provider)
    .build();

Security & Best Practices

Tool Security

Implement secure tool filtering:

McpToolProvider secureProvider = McpToolProvider.builder()
    .mcpClients(mcpClient)
    .filter((client, tool) -> {
        if (tool.name().startsWith("admin_") && !isAdmin()) {
            return false;
        }
        return true;
    })
    .build();

Resource Security

Apply access controls to resources:

public boolean canAccessResource(String uri, User user) {
    return resourceService.hasAccess(uri, user);
}

Error Handling

Implement robust error handling:

try {
    String result = mcpClient.executeTool(request);
} catch (McpException e) {
    log.error("MCP execution failed: {}", e.getMessage());
    return fallbackResult();
}

Advanced Patterns

Multi-Server Configuration

Configure multiple MCP servers:

@Bean
public List<McpClient> mcpClients(List<ServerConfig> configs) {
    return configs.stream()
        .map(this::createMcpClient)
        .collect(Collectors.toList());
}

@Bean
public McpToolProvider multiServerProvider(List<McpClient> clients) {
    return McpToolProvider.builder()
        .mcpClients(clients)
        .failIfOneServerFails(false)
        .build();
}

Dynamic Tool Discovery

Runtime tool filtering based on context:

McpToolProvider contextualProvider = McpToolProvider.builder()
    .mcpClients(clients)
    .filter((client, tool) -> isToolAllowed(user, tool, context))
    .build();

Health Monitoring

Monitor MCP server health:

@Component
public class McpHealthChecker {

    @Scheduled(fixedRate = 30000) // 30 seconds
    public void checkServers() {
        mcpClients.forEach(client -> {
            try {
                client.listTools();
                markHealthy(client.key());
            } catch (Exception e) {
                markUnhealthy(client.key(), e.getMessage());
            }
        });
    }
}

Configuration

Application Properties

Configure MCP servers in application.yml:

mcp:
  servers:
    github:
      type: docker
      command: ["/usr/local/bin/docker", "run", "-e", "GITHUB_TOKEN", "-i", "mcp/github"]
      log-events: true
    database:
      type: stdio
      command: ["/usr/bin/npm", "exec", "@modelcontextprotocol/server-sqlite"]
      log-events: false

Spring Boot Configuration

Configure MCP with Spring Boot:

@Configuration
@EnableConfigurationProperties(McpProperties.class)
public class McpConfiguration {

    @Bean
    public MCPServer mcpServer(List<ToolProvider> providers) {
        return MCPServer.builder()
            .server(new StdioServer.Builder())
            .addToolProvider(providers)
            .enableLogging(true)
            .build();
    }
}

Examples

Refer to examples.md for comprehensive implementation examples including:

• Basic MCP server setup
• Multi-tool enterprise servers
• Resource and prompt providers
• Spring Boot integration
• Error handling patterns
• Security implementations

API Reference

Complete API documentation is available in api-reference.md covering:

• Core MCP classes and interfaces
• Transport configuration
• Client and server patterns
• Error handling strategies
• Configuration management
• Testing and validation

Best Practices

1. Resource Management: Always close MCP clients properly using try-with-resources
2. Error Handling: Implement graceful degradation when servers fail
3. Security: Use tool filtering and resource access controls
4. Performance: Enable caching and optimize tool execution
5. Monitoring: Implement health checks and observability
6. Testing: Create comprehensive test suites with mocks
7. Documentation: Document tools, resources, and prompts clearly
8. Configuration: Use structured configuration for maintainability

References

• LangChain4j Documentation
• Model Context Protocol Specification
• API Reference
• Examples