자바 MCP stdio 서버 구축하기

자바 MCP stdio 서버 구축하기 (Building a Java MCP stdio server)

LangChain4j는 MCP 서버에 연결하기 위한 MCP 클라이언트(langchain4j-mcp)를 제공해요. 자바 기반 MCP stdio 서버(MCP 클라이언트가 실행하는 로컬 하위 프로세스)를 만들고 싶다면 커뮤니티 모듈 langchain4j-community-mcp-server를 사용해요.

출처: 공식문서

이 가이드는 기존 @Tool-어노테이션 메서드를 stdio를 통해 MCP(JSON-RPC)로 노출하는 최소 설정을 보여줘요.

의존성 추가

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;
    }
}

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 클라이언트 구성

Claude Desktop

claude_desktop_config.json에 서버 항목을 추가해요:

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

절대 경로를 사용해요; Windows에서는 백슬래시를 이스케이프해요.

자바 MCP stdio 서버 구축하기