构建一个 Java MCP 服务器

LangChain4j 提供了一个用于连接 MCP 服务器的 MCP 客户端（langchain4j-mcp）。 如果你想构建一个基于 Java 的 MCP stdio 服务器（由 MCP 客户端启动的本地子进程）， 请使用社区模块：langchain4j-community-mcp-server。

本指南演示如何经 stdio 通过 MCP（JSON-RPC）暴露已有的 @Tool 注解方法的最小配置。 如果你的服务器应作为一个可通过网络访问的独立服务运行，参见 Streamable HTTP 服务器。

添加依赖

添加 BOM（推荐）：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-bom</artifactId>
            <version>${latest version here}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-community-bom</artifactId>
            <version>${latest version here}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

然后添加社区 MCP 服务器依赖：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-community-mcp-server</artifactId>
</dependency>

实现工具

使用 @Tool 暴露你的功能：

import dev.langchain4j.agent.tool.P;
import dev.langchain4j.agent.tool.Tool;

class Calculator {

    @Tool
    long add(@P("a") long a, @P("b") long b) {
        return a + b;
    }
}

MCP 工具参数名取自 Java 方法的参数名。 请用 -parameters javac 选项编译你的项目，否则 MCP 客户端会看到诸如 arg0、arg1 的通用名称：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <parameters>true</parameters>
            </configuration>
        </plugin>
    </plugins>
</build>

启动 stdio 服务器

import dev.langchain4j.community.mcp.server.McpServer;
import dev.langchain4j.community.mcp.server.transport.StdioMcpServerTransport;
import dev.langchain4j.mcp.protocol.McpImplementation;
import java.util.List;

public class McpServerMain {

    public static void main(String[] args) throws Exception {
        McpImplementation serverInfo = new McpImplementation();
        serverInfo.setName("my-java-mcp-server");
        serverInfo.setVersion("1.0.0");

        McpServer server = new McpServer(List.of(new Calculator()), serverInfo);
        new StdioMcpServerTransport(System.in, System.out, server);

        // Keep the process alive while stdio is open
        Thread.currentThread().join();
    }
}

::: caution StdioMcpServerTransport 会把 JSON-RPC 协议写入 System.out。 请确保你的日志配置为写入 System.err（否则你会破坏协议流，导致客户端断开）。 :::

打包为可运行 JAR

MCP 客户端（如 Claude Desktop）通常期望启动一个本地服务器进程。 将你的服务器打包为可运行（fat）JAR 是一种常见做法，但任何可运行的进程都行。

配置一个 MCP 客户端

.mcp.json

许多 MCP 客户端从 .mcp.json 文件读取服务器定义：

{
  "mcpServers": {
    "my-java-tool": {
      "type": "stdio",
      "command": "java",
      "args": ["-jar", "/absolute/path/to/my-java-mcp-server.jar"]
    }
  }
}

Claude Desktop

在 claude_desktop_config.json 中添加一个服务器条目：

{
  "mcpServers": {
    "my-java-tool": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/my-java-mcp-server.jar"]
    }
  }
}

请使用绝对路径；在 Windows 上要转义反斜杠。

Streamable HTTP 服务器

stdio 传输每个进程只服务单个本地客户端。 若你的 MCP 服务器应作为一个可被多个（本地或远程）客户端共享的独立服务运行， 请使用 Streamable HTTP 传输。 langchain4j-community-mcp-server 不提供它，但以下 Java 库提供（按字母顺序列出）：

库	描述
Helidon MCP	面向 Helidon 应用的 MCP 服务器支持
MCP Java SDK	Model Context Protocol 的官方 Java SDK，不依赖任何框架
Micronaut MCP	面向 Micronaut 应用的 MCP 服务器支持
Quarkus MCP Server	面向 Quarkus 应用的 MCP 服务器支持
Tachyon	面向 Java 与 Kotlin 的 MCP 服务器库

这些是独立项目，不由 LangChain4j 团队维护。 关于搭建、安全（认证、TLS）与部署，请参阅各自的文档。

服务器运行后，将 MCP 客户端指向它的端点 URL，例如在 .mcp.json 中：

{
  "mcpServers": {
    "my-java-tool": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Claude Desktop 只启动本地进程， 因此用 mcp-remote 将其连接到一个 Streamable HTTP 服务器：

{
  "mcpServers": {
    "my-java-tool": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8080/mcp"]
    }
  }
}