giuseppe-trisciuoglio/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

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

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