git:20260228.3187e79 to git:20260323.2528036

- description: Provides Model Context Protocol (MCP) server implementation patterns with LangChain4j. Use when building MCP servers to extend AI capabilities with custom tools, resources, and prompt templates.

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

-

- 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:

-

- ```java

- 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:

-

- ```java

- MCPServer server = MCPServer.builder()

- .server(new StdioServer.Builder())

- .addToolProvider(new WeatherToolProvider())

- .build();

-

- server.start();

- ```

-

- ### 3. Add Resource Provider

-

- Implement resource providers for data access:

-

- ```java

- 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:

- ```java

- @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:

- ```java

- 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:

- ```java

- MCPServer server = MCPServer.builder()

- .server(new StdioServer.Builder())

- .addToolProvider(new SimpleWeatherToolProvider())

- .build();

- server.start();

- ```

- ### Spring Boot Integration

- Configure MCP server in Spring Boot:

- ```java

- @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:

- 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:

-

- ```java

- class CompanyResourceProvider

- implements ResourceListProvider, ResourceReadHandler {

-

- @Override

- public List<McpResource> listResources() {

- 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:

-

- ```java

- class PromptTemplateProvider

- implements PromptListProvider, PromptGetHandler {

-

- @Override

- public List<Prompt> listPrompts() {

- return List.of(

- Prompt.builder()

- .name("code-review")

- .description("Review code for quality")

- public String getPrompt(String name, Map<String, String> args) {

- return applyTemplate(name, args);

- ```

- ## Transport Configuration

-

- ### Stdio Transport

-

- Local process communication:

-

- ```java

- McpTransport transport = new StdioMcpTransport.Builder()

- .command(List.of("npm", "exec", "@modelcontextprotocol/server-everything@0.6.2"))

- .logEvents(true)

- .build();

- ```

-

- ### HTTP Transport

-

- Remote server communication:

-

- ```java

- McpTransport transport = new HttpMcpTransport.Builder()

- .sseUrl("http://localhost:3001/sse")

- .logRequests(true)

- .logResponses(true)

- .build();

- ```

-

- ## Client Integration

-

- ### MCP Client Setup

-

- Connect to MCP servers:

-

- ```java

- McpClient client = new DefaultMcpClient.Builder()

- .key("my-client")

- .transport(transport)

- .cacheToolList(true)

- // List available tools

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

- ### Tool Provider Integration

- Bridge MCP servers to LangChain4j AI services:

- McpToolProvider provider = McpToolProvider.builder()

- .mcpClients(mcpClient)

- .filter((client, tool) -> filterByPermissions(tool))

- // Integrate with AI service

- AIAssistant assistant = AiServices.builder(AIAssistant.class)

- .toolProvider(provider)

- .build();

- ```

-

- ## Security & Best Practices

-

- ### Tool Security

-

- Implement secure tool filtering:

-

- ```java

- 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:

-

- ```java

- public boolean canAccessResource(String uri, User user) {

- return resourceService.hasAccess(uri, user);

- }

- ```

-

- ### Error Handling

-

- Implement robust error handling:

-

- ```java

- 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:

-

- ```java

- @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:

-

- ```java

- McpToolProvider contextualProvider = McpToolProvider.builder()

- .mcpClients(clients)

- .filter((client, tool) -> isToolAllowed(user, tool, context))

- ### Health Monitoring

-

- Monitor MCP server health:

-

- ```java

- @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:

-

- ```yaml

- 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:

-

- ```java

- @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:**

- ```java

- // Client invokes the weather tool

- Map<String, Object> args = Map.of("city", "Milan");

- String result = mcpClient.executeTool("get_weather", mapper.writeValueAsString(args));

- ```

-

- **Output:**

- ```json

- {

- "city": "Milan",

- "temperature": 22,

- "condition": "Partly Cloudy",

- "humidity": 65,

- "unit": "celsius"

- }

- ```

-

- ### Example 2: Resource Retrieval

-

- **Input:**

- ```java

- // 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:**

- ```java

- // 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](./references/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](./references/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

- - [LangChain4j Documentation](https://langchain4j.com/docs/)

- - [Model Context Protocol Specification](https://modelcontextprotocol.org/)

- - [API Reference](./references/api-reference.md)

- - [Examples](./references/examples.md)

- ## 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.