langchain4j-mcp-server-patterns

# LangChain4j MCP Server Implementation Patterns ## Overview Use this skill to design and implement Model Context Protocol (MCP) integrations with LangChain4j. The main concerns are: - defining a clean tool, resource, and prompt surface - choosing the right transport and bootstrap model - filtering unsafe capabilities before exposing them to agents or applications Keep `SKILL.md` focused on the implementation flow. Use the bundled references for expanded examples and API-level detail. ## When to Use Use this skill when: - building a Java MCP server that exposes tools, resources, or prompts - integrating LangChain4j with one or more external MCP servers - wiring MCP support into a Spring Boot application - filtering available tools by tenant, user role, or runtime context - adding observability, resilience, and safe failure handling around MCP interactions - reviewing an MCP integration for prompt-injection and side-effect risks Typical trigger phrases include `langchain4j mcp`, `java mcp server`, `mcp tool provider`, `spring boot mcp`, and `connect langchain4j to mcp`. ## Instructions ### 1. Design the MCP surface before writing code Decide what the server should expose: - tools for actions with clear inputs and side effects - resources for read-only or structured data access - prompts only when a reusable template adds real value Keep names stable, descriptions concrete, and schemas small enough for a client or model to understand quickly. ### 2. Implement providers with narrow responsibilities Use separate classes for each concern: - tool provider for executable functions - resource provider for discoverable and readable data - prompt provider for reusable prompt templates Validate arguments before execution and return clear error messages for invalid input or unavailable dependencies. ### 3. Choose the transport intentionally Use: - stdio for local integrations, CLI tools, and sidecar processes - HTTP or SSE for remote or shared services Pin external server versions and document how the process is started, authenticated, and monitored. ### 4. Bridge MCP into LangChain4j carefully When consuming MCP servers from LangChain4j: - initialize clients during application startup - cache tool lists only when stale metadata is acceptable - filter tools by trust level, environment, or user permissions - fail closed for dangerous tools rather than exposing everything by default ### 5. Add resilience and security controls At minimum: - bound execution time for external calls - log server and tool identity for each failure - sanitize content returned by external resources before using it downstream - isolate privileged tools behind allowlists, qualifiers, or role checks ### 6. Validate the full workflow Before shipping: - verify tool discovery and invocation with a real MCP client - test disconnected or slow server behavior - confirm that tool filtering matches the intended authorization model - check that prompts and resources do not leak secrets or unsafe instructions ## Examples ### Example 1: Minimal tool provider and stdio server bootstrap ```java class WeatherToolProvider implements ToolProvider { @Override public List<ToolSpecification> listTools() { return List.of( ToolSpecification.builder() .name("get_weather") .description("Return the current weather for a city") .inputSchema(Map.of( "type", "object", "properties", Map.of( "city", Map.of("type", "string") ), "required", List.of("city") )) .build() ); } @Override public String executeTool(String name, String arguments) { return weatherService.lookup(arguments); } } MCPServer server = MCPServer.builder() .server(new StdioServer.Builder()) .addToolProvider(new WeatherToolProvider()) .build(); server.start(); ``` Use this pattern for local tool execution or a sidecar process started by another application. ### Example 2: Expose MCP tools to a LangChain4j AI service with filtering ```java McpToolProvider toolProvider = McpToolProvider.builder() .mcpClients(mcpClients) .failIfOneServerFails(false) .filter((client, tool) -> !tool.name().startsWith("admin_")) .build(); Assistant assistant = AiServices.builder(Assistant.class) .chatModel(chatModel) .toolProvider(toolProvider) .build(); ``` Use this pattern when you want LangChain4j to consume external MCP servers while still enforcing trust boundaries. ## Best Practices - Keep each tool focused, deterministic, and well-described. - Prefer explicit schemas over free-form string arguments. - Separate read-only resources from tools with side effects. - Filter or disable privileged tools by default. - Pin external MCP server packages or container versions. - Capture metrics for connection failures, invocation latency, and tool error rates. - Store longer protocol details and framework-specific wiring in `references/` instead of expanding `SKILL.md` indefinitely. ## Constraints and Warnings - External MCP servers are untrusted integration boundaries and may expose malicious or misleading content. - Do not forward raw resource content directly into autonomous tool execution without validation. - Some LangChain4j and MCP APIs evolve quickly; adapt class names and builders to the versions already used in the project. - Long-running or stateful tools need explicit timeout, cancellation, and cleanup behavior. - Stdio-based servers require process lifecycle management and robust logging. ## References - `references/examples.md` - `references/api-reference.md` ## Related Skills - `prompt-engineering` - `spring-ai` - `clean-architecture`