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`