LangChain4j MCP Server Implementation Patterns

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

Overview

The Model Context Protocol (MCP) is a standardized protocol for connecting AI applications to external data sources and tools. LangChain4j provides MCP server implementation patterns that enable AI systems to dynamically discover and execute tools, access resources, and use prompt templates through a standardized interface.

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

Instructions

Follow these steps to implement an MCP server with LangChain4j:

1. Create Tool Provider

Implement ToolProvider to define executable tools:

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";
    }
}

2. Configure MCP Server

Create and start the MCP server:

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

server.start();

3. Add Resource Provider

Implement resource providers for data access:

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);
    }
}

4. Integrate with Spring Boot

Configure MCP server in Spring Boot application:

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

5. Implement Security

Add tool filtering for access control:

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

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@0.6.2"))
    .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@0.6.2"]
      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

Example 1: Weather Tool Execution

Input:

// Client invokes the weather tool
Map<String, Object> args = Map.of("city", "Milan");
String result = mcpClient.executeTool("get_weather", mapper.writeValueAsString(args));

Output:

{
  "city": "Milan",
  "temperature": 22,
  "condition": "Partly Cloudy",
  "humidity": 65,
  "unit": "celsius"
}

Example 2: Resource Retrieval

Input:

// Client requests a resource by URI
String content = mcpClient.readResource("policies");

Output:

Company Remote Work Policy v2.0
Effective Date: January 1, 2025

1. Employees may work remotely up to 3 days per week...

Example 3: Multi-Server Tool Discovery

Input:

// List all tools from connected MCP servers
List<ToolSpecification> tools = mcpToolProvider.tools();
tools.forEach(t -> System.out.println(t.name() + ": " + t.description()));

Output:

get_weather: Get current weather for a city
search_documents: Search company knowledge base
send_notification: Send notification to user
admin_backup: Create system backup (admin only)

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

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

References

Constraints and Warnings

MCP servers should implement proper resource cleanup when stopped.
External MCP Server Security: Only connect to trusted, verified MCP servers; external servers (including those launched via npm exec or HTTP/SSE endpoints) can expose untrusted tools, resources, and prompts that may influence agent behavior through indirect prompt injection.
Pin MCP Server Versions: Always pin npm packages to specific versions (e.g., @modelcontextprotocol/server-everything@0.6.2) to prevent supply-chain attacks from unpinned dependencies.
Validate External Content: Content retrieved from MCP server resources (e.g., GitHub issues, database records) is untrusted user-generated data; validate and sanitize before acting on it.
Tool execution errors should be handled gracefully; never expose stack traces to clients.
Resource URIs should be validated to prevent directory traversal attacks.
Prompt templates should sanitize user inputs to prevent injection attacks.
Stdio transport requires proper process lifecycle management.
HTTP transport should implement authentication and rate limiting.
Multi-server configurations require careful handling of server failures.
Tool caching should have appropriate TTLs to prevent stale data.
Be cautious with tools that have external side effects; they may be called unexpectedly by AI models.

langchain4j-mcp-server-patterns

LangChain4j MCP Server Implementation Patterns

Overview

When to Use

Instructions

1. Create Tool Provider

2. Configure MCP Server

3. Add Resource Provider

4. Integrate with Spring Boot

5. Implement Security

Quick Start

Basic MCP Server

Spring Boot Integration

Core Concepts

MCP Architecture

Key Components

Implementation Patterns

Tool Provider Pattern

Resource Provider Pattern

Prompt Template Pattern

Transport Configuration

Stdio Transport

HTTP Transport

Client Integration

MCP Client Setup

Tool Provider Integration

Security & Best Practices

Tool Security

Resource Security

Error Handling

Advanced Patterns

Multi-Server Configuration

Dynamic Tool Discovery

Health Monitoring

Configuration

Application Properties

Spring Boot Configuration

Examples

Example 1: Weather Tool Execution

Example 2: Resource Retrieval

Example 3: Multi-Server Tool Discovery

API Reference

Best Practices

References

Constraints and Warnings

Is this your skill?