---
name: langchain4j-mcp-server
description: "Use when designing, creating, scaffolding, or reviewing Java/Kotlin MCP servers based on LangChain4j. Select the community stdio server for local tools-only hosts, CDI-MCP for Java HTTP Streamable servers, or Quarkus MCP Server when Quarkus is required. Do not use for consuming MCP servers from LangChain4j (use langchain4j-mcp-client) or general code generation/review (use langchain4j-scaffold/langchain4j-review)."
allowed-tools: Read, Grep, Glob, Write, Edit, Bash(find * -name "*.java" -o -name "*.kt" -o -name "pom.xml" -o -name "build.gradle*")
---

# LangChain4j MCP Server

Build or review a JVM MCP server as a separately deployable integration boundary. Inspect the host runtime, transport, and required MCP primitives before selecting an implementation.

> **Version baseline**: LangChain4j core `1.18.1`; MCP client `1.18.1-beta28`; community MCP server `1.18.0-beta28`; CDI-MCP `1.3.4`

## Choose the server path

| Requirement | Use | Do not use |
|---|---|---|
| Local Claude Desktop, Cursor, or IDE subprocess; tools only | `langchain4j-community-mcp-server` stdio fat JAR | Spring Boot web endpoint |
| Remote Streamable HTTP; tools, prompts, or resources; Jakarta EE, Helidon, WildFly, Liberty, or Quarkus | CDI-MCP `1.3.4` | LangChain4j `@Tool` / `@P` annotations |
| Quarkus-native MCP service and Quarkus extension features | Quarkus MCP Server | `quarkus-langchain4j-mcp`, which is a client integration |
| Python platform, rich MCP middleware/auth/composition | FastMCP | A second Java implementation of the same tool catalog |
| Spring Boot application needs remote MCP | Keep Spring Boot as an MCP **client**; deploy a separate CDI-MCP/Quarkus service or FastMCP sidecar | Hand-rolled `@RestController` JSON-RPC |

`langchain4j-mcp` is a client library; it does not create a server. The published community server is **tools-only over stdio**. Do not declare the non-published coordinate `langchain4j-community-mcp-server:1.18.1-beta28`; use its released `1.18.0-beta28` version.

## Implementation workflow

1. Inspect build files, current runtime, existing `@Tool` methods, host configuration, authentication boundary, and deployment target.
2. Decide whether the host needs only tools or also prompts/resources, then select the table row above.
3. Keep the MCP surface narrow: version tool names/schemas deliberately, validate all model-controlled arguments, return safe operational errors, and keep credentials server-side.
4. For community stdio:
   - use `dev.langchain4j.community.mcp.server.*`;
   - expose ordinary LangChain4j `@Tool` / `@P` methods;
   - send **all** logs to `System.err`; stdout is JSON-RPC only;
   - package a standalone executable JAR with an explicit main class and configure hosts with absolute paths.
5. For CDI-MCP:
   - use `org.mcp_java.annotations.*` from the released `1.3.4` stack, not LangChain4j `@Tool` / `@P`;
   - expose the extension-provided JAX-RS `/mcp` endpoint rather than writing a controller;
   - apply TLS, bearer/OAuth validation, authorization, request limits, network policy, and audit logging at the HTTP boundary.
6. For Quarkus MCP Server, follow the extension's server documentation; keep `quarkus-langchain4j-mcp` on the consuming/client side.

## Review checklist

- **Surface:** unique action-oriented tool names; precise descriptions and typed, validated inputs; no credentials in schemas, outputs, or logs.
- **Stdio lifecycle:** no `System.out.println`, no console appender targeting stdout, no web-server bootstrap, and the process remains alive until stdin closes.
- **HTTP lifecycle:** endpoint is `/mcp`, session headers are preserved by clients/proxies, notifications/long-running work are tested, and only supported primitives are advertised.
- **Authorization:** authentication is not authorization; enforce per-tool and per-tenant checks in the server/domain layer, including for read tools.
- **Operations:** health/readiness endpoints must not leak data; tool calls carry request/trace IDs; timeouts, cancellation, rate limits, and safe error envelopes are explicit.
- **Tests:** initialize and list capabilities, invoke a successful tool, test invalid arguments/authorization/downstream failure, and prove stdout remains protocol-clean for stdio.

## Routing

- `langchain4j-mcp-client` — consuming MCP servers with `McpToolProvider`.
- `langchain4j-scaffold` — general AI-service/client/workflow generation; use this skill to choose the server implementation first.

For released dependencies, templates, host configuration, and test patterns, read [reference.md](reference.md).