gh-giuseppe-trisciuoglio-developer-kit/skills/langchain4j/langchain4j-mcp-server-patterns/references/api-reference.md

LangChain4j MCP Server API Reference

This document provides comprehensive API documentation for implementing MCP servers with LangChain4j.

Core MCP Classes

McpClient Interface

Primary interface for communicating with MCP servers.

Key Methods:

// Tool Management
List<ToolSpecification> listTools();
String executeTool(ToolExecutionRequest request);

// Resource Management
List<McpResource> listResources();
String getResource(String uri);
List<McpResourceTemplate> listResourceTemplates();

// Prompt Management
List<Prompt> listPrompts();
String getPrompt(String name);

// Lifecycle Management
void close();

DefaultMcpClient.Builder

Builder for creating MCP clients with configuration options.

Configuration Methods:

McpClient client = new DefaultMcpClient.Builder()
    .key("unique-client-id")                    // Unique identifier
    .transport(transport)                        // Transport mechanism
    .cacheToolList(true)                         // Enable tool caching
    .logMessageHandler(handler)                 // Custom logging
    .build();

McpToolProvider.Builder

Builder for creating tool providers that bridge MCP servers to LangChain4j AI services.

Configuration Methods:

McpToolProvider provider = McpToolProvider.builder()
    .mcpClients(client1, client2)               // Add MCP clients
    .failIfOneServerFails(false)                // Configure failure handling
    .filterToolNames("tool1", "tool2")           // Filter by names
    .filter((client, tool) -> logic)             // Custom filtering
    .build();

Transport Configuration

StdioMcpTransport.Builder

For local process communication with npm packages or Docker containers.

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

HttpMcpTransport.Builder

For HTTP-based communication with remote MCP servers.

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

StreamableHttpMcpTransport.Builder

For streamable HTTP transport with enhanced performance.

McpTransport transport = new StreamableHttpMcpTransport.Builder()
    .url("http://localhost:3001/mcp")
    .logRequests(true)
    .logResponses(true)
    .build();

AI Service Integration

AiServices.builder()

Create AI services integrated with MCP tool providers.

Integration Methods:

AIAssistant assistant = AiServices.builder(AIAssistant.class)
    .chatModel(chatModel)
    .toolProvider(toolProvider)
    .chatMemoryProvider(memoryProvider)
    .build();

Error Handling and Management

Exception Handling

Handle MCP-specific exceptions gracefully:

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

Retry and Resilience

Implement retry logic for unreliable MCP servers:

RetryTemplate retryTemplate = RetryTemplate.builder()
    .maxAttempts(3)
    .exponentialBackoff(1000, 2, 10000)
    .build();

String result = retryTemplate.execute(context ->
    mcpClient.executeTool(request));

Configuration Properties

Application Configuration

mcp:
  fail-if-one-server-fails: false
  cache-tools: true
  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

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

    @Bean
    public List<McpClient> mcpClients(McpProperties properties) {
        return properties.getServers().entrySet().stream()
            .map(entry -> createMcpClient(entry.getKey(), entry.getValue()))
            .collect(Collectors.toList());
    }

    @Bean
    public McpToolProvider mcpToolProvider(List<McpClient> mcpClients, McpProperties properties) {
        return McpToolProvider.builder()
            .mcpClients(mcpClients)
            .failIfOneServerFails(properties.isFailIfOneServerFails())
            .build();
    }
}

Tool Specification and Execution

Tool Specification

Define tools with proper schema:

ToolSpecification toolSpec = ToolSpecification.builder()
    .name("database_query")
    .description("Execute SQL queries against the database")
    .inputSchema(Map.of(
        "type", "object",
        "properties", Map.of(
            "sql", Map.of(
                "type", "string",
                "description", "SQL query to execute"
            )
        )
    ))
    .build();

Tool Execution

Execute tools with structured requests:

ToolExecutionRequest request = ToolExecutionRequest.builder()
    .name("database_query")
    .arguments("{\"sql\": \"SELECT * FROM users LIMIT 10\"}")
    .build();

String result = mcpClient.executeTool(request);

Resource Handling

Resource Access

Access and utilize MCP resources:

// List available resources
List<McpResource> resources = mcpClient.listResources();

// Get specific resource content
String content = mcpClient.getResource("resource://schema/database");

// Work with resource templates
List<McpResourceTemplate> templates = mcpClient.listResourceTemplates();

Resource as Tools

Convert MCP resources to tools automatically:

DefaultMcpResourcesAsToolsPresenter presenter =
    new DefaultMcpResourcesAsToolsPresenter();
mcpToolProvider.provideTools(presenter);

// Adds 'list_resources' and 'get_resource' tools automatically

Security and Filtering

Tool Filtering

Implement security-conscious tool filtering:

McpToolProvider secureProvider = McpToolProvider.builder()
    .mcpClients(mcpClient)
    .filter((client, tool) -> {
        // Check user permissions
        if (tool.name().startsWith("admin_") && !currentUser.hasRole("ADMIN")) {
            return false;
        }
        return true;
    })
    .build();

Resource Security

Apply security controls to resource access:

public boolean canAccessResource(String uri, User user) {
    if (uri.contains("sensitive/") && !user.hasRole("ADMIN")) {
        return false;
    }
    return true;
}

Performance Optimization

Caching Strategy

Implement intelligent caching:

// Enable tool caching for performance
McpClient client = new DefaultMcpClient.Builder()
    .transport(transport)
    .cacheToolList(true)
    .build();

// Periodic cache refresh
@Scheduled(fixedRate = 300000) // 5 minutes
public void refreshToolCache() {
    mcpClients.forEach(client -> {
        try {
            client.invalidateCache();
            client.listTools(); // Preload cache
        } catch (Exception e) {
            log.warn("Cache refresh failed: {}", e.getMessage());
        }
    });
}

Connection Pooling

Optimize connection management:

@Bean
public Executor mcpExecutor() {
    return Executors.newFixedThreadPool(10); // Dedicated thread pool
}

Testing and Validation

Mock Configuration

Setup for testing:

@TestConfiguration
public class MockMcpConfiguration {

    @Bean
    @Primary
    public McpClient mockMcpClient() {
        McpClient mock = Mockito.mock(McpClient.class);

        when(mock.listTools()).thenReturn(List.of(
            ToolSpecification.builder()
                .name("test_tool")
                .description("Test tool")
                .build()
        ));

        when(mock.executeTool(any(ToolExecutionRequest.class)))
            .thenReturn("Mock result");

        return mock;
    }
}

Integration Testing

Test MCP integrations:

@SpringBootTest
class McpIntegrationTest {

    @Autowired
    private AIAssistant assistant;

    @Test
    void shouldExecuteToolsSuccessfully() {
        String response = assistant.chat("Execute test tool");

        assertThat(response).contains("Mock result");
    }
}

Monitoring and Observability

Health Checks

Monitor MCP server health:

@Component
public class McpHealthChecker {

    @EventListener
    @Async
    public void checkHealth() {
        mcpClients.forEach(client -> {
            try {
                client.listTools(); // Simple health check
                healthRegistry.markHealthy(client.key());
            } catch (Exception e) {
                healthRegistry.markUnhealthy(client.key(), e.getMessage());
            }
        });
    }
}

Metrics Collection

Collect execution metrics:

@Bean
public Counter toolExecutionCounter(MeterRegistry meterRegistry) {
    return meterRegistry.counter("mcp.tool.execution", "type", "total");
}

@Bean
public Timer toolExecutionTimer(MeterRegistry meterRegistry) {
    return meterRegistry.timer("mcp.tool.execution.time");
}

Migration and Versioning

Version Compatibility

Handle version compatibility:

public class VersionedMcpClient {

    public boolean isCompatible(String serverVersion) {
        return semanticVersionChecker.isCompatible(
            REQUIRED_MCP_VERSION, serverVersion);
    }

    public McpClient createClient(ServerConfig config) {
        if (!isCompatible(config.getVersion())) {
            throw new IncompatibleVersionException(
                "Server version " + config.getVersion() +
                " is not compatible with required " + REQUIRED_MCP_VERSION);
        }

        return new DefaultMcpClient.Builder()
            .transport(createTransport(config))
            .build();
    }
}

This API reference provides the complete foundation for implementing MCP servers and clients with LangChain4j, covering all major aspects from basic setup to advanced enterprise patterns.