java-sdk 딥다이브
— AI와 자바 도구 사이, 통신의 약속을 코드로 만들기

1프로젝트 한줄 요약

java-sdk는 Java 애플리케이션이 MCP 서버와 클라이언트가 되도록 만드는 라이브러리입니다. 서버는 “내가 제공하는 도구는 이것이고, 입력은 이런 JSON이다”라고 공개합니다. 클라이언트는 목록을 확인하고 도구를 호출한 뒤 결과를 받습니다. 이 저장소가 해결하는 문제는 모델의 지능이 아니라, 모델 주변 프로그램과 도구 사이의 일관된 통신입니다.

예를 들어 사내 재고 조회 함수를 lookup_stock이라는 MCP 도구로 등록할 수 있습니다. AI를 포함한 호스트 애플리케이션은 그 도구를 발견하고 {"sku":"BOOK-001"} 같은 인자를 보냅니다. Java 서버가 데이터베이스를 조회하는 코드는 개발자가 작성하고, SDK는 메시지의 해석·전송·응답 연결을 맡습니다. 모델 제공자의 추론 API 키나 모델 가중치가 SDK 자체에 필요한 것은 아닙니다.

1-1. 처음에는 세 가지 기능만 구분하자

이 이름들은 mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java의 메서드 상수와 레코드에 대응합니다. 서버에서 클라이언트에 모델 생성을 요청하는 sampling, 사용자 추가 입력을 요청하는 elicitation도 있지만, 첫 학습에서는 도구 한 개의 목록 조회와 호출을 끝까지 추적하는 편이 좋습니다.

// 도구 호출의 메시지 모양: SDK가 이 봉투를 만들고 읽는다.
{
  "jsonrpc": "2.0",
  "id": "study-1",
  "method": "tools/call",
  "params": {
    "name": "lookup_stock",
    "arguments": { "sku": "BOOK-001" }
  }
}

2왜 주목받는가

2026-10-23 GitHub Trending Java Weekly #5에 오른 저장소입니다. 스타 3,736과 포크 1,112는 관심의 규모를 보여주지만, 특정 기능이 순위를 만들었다는 인과관계까지 설명하지는 않습니다. 아래 세 가지는 공식 설명·릴리스·소스 구조에서 읽을 수 있는 주목할 기술적 배경입니다.

2-1. 기존 Java 기능을 MCP로 공개하는 경로

공식 저장소 설명은 Spring AI와의 협력 유지보수를 명시합니다. Java로 작성한 업무 함수를 유지하면서 MCP 계약을 덧붙일 수 있다는 점이 실용적입니다. 모든 기능을 별도 언어로 옮기기보다, 이미 있는 서비스와 라이브러리를 재사용할 수 있습니다. 이는 도입 경로에 대한 해석이며, 이 저장소만으로 회사 시스템 연결이 자동 완성된다는 뜻은 아닙니다.

2-2. 통신의 세부까지 다루는 구현

공개 배포판의 변경 내역은 v2.1.0 릴리스 노트에서 볼 수 있습니다. 커밋 54e8b61에는 도구 목록 필터링, JDK HTTP 전송의 Publisher 기반 응답 처리, 조합 가능한 요청 커스터마이저가 구현되어 있습니다. STDIO 출력 쓰기의 동기화, Streamable HTTP 세션 정리와 keep-alive도 살펴볼 수 있습니다. 초보자에게는 기능 목록보다 동시 실행·연결 종료·오류 응답 같은 세부가 SDK 품질을 좌우한다는 사례입니다.

이 SDK의 장점은 도구를 등록하는 편의 API와, 통신 구현을 교체할 수 있는 경계를 함께 제공한다는 점입니다. 편리한 McpServer.sync(...)로 시작하더라도, 아래에는 독립된 전송·JSON 인터페이스가 있습니다.

2-3. 비교할 때는 “어느 층을 맡는가”부터

2-4. 별 개수와 프로토콜 완성도는 따로 읽는다

conformance-tests/VALIDATION_RESULTS.md는 2026-10-02 검증 결과와 알려진 실패를 함께 기록합니다. 이런 문서는 표준 SDK를 평가할 때 중요한 단서입니다. “공식”이라는 이름만으로 모든 규격·전송·실패 복구가 완전하다고 가정하지 않고, 어떤 조건을 검증했는지 확인하는 습관을 배울 수 있습니다.

3기술 스택 전체 지도

루트 pom.xml은 io.modelcontextprotocol.sdk:mcp-parent:2.2.0-SNAPSHOT을 선언합니다. 반면 최신 공개 릴리스는 2026-10-16의 v2.1.0입니다. 배포판을 사용하는 방법과 개발 브랜치의 구현을 읽는 방법은 버전 기준을 분리해야 합니다. 아래 의존성 버전을 v2.1.0의 구성으로 그대로 옮기면 안 됩니다.

3-1. 백엔드·통신·데이터 표현

3-2. 프론트엔드와 외부 Spring 통합

제품용 프론트엔드 앱은 없습니다. 추적 파일에 package.json, React·Vue 코드, 프론트엔드 빌드 설정이 보이지 않습니다. 문서 사이트는 mkdocs.yml의 Material 테마와 Markdown으로 구성됩니다. .github/workflows/docs.yml은 Python 3.x에서 mkdocs-material과 mike를 설치하지만, 두 패키지의 버전은 고정하지 않습니다. 문서 도구가 런타임 Java 의존성인 것은 아닙니다.

Spring은 core의 필수 웹 프레임워크가 아닙니다. conformance-tests/client-spring-http-client/pom.xml은 Spring Boot 4.1.2, Spring AI 2.0.2, MCP 보안 통합 0.1.14를 선언합니다. 이 값은 Spring 인증 검증 애플리케이션의 구성입니다. README는 WebClient·WebFlux·WebMVC 통합을 Spring AI 2.0+의 영역으로 안내합니다.

3-3. 인프라·빌드·검증

추적 파일에는 Dockerfile이나 Kubernetes 배포 명세가 없습니다. Docker는 README가 안내하는 전체 테스트 준비물이지, SDK를 사용하는 모든 Java 프로세스의 필수 런타임은 아닙니다. 데이터베이스나 벡터 저장소도 SDK의 필수 구성요소가 아닙니다.

3-4. 의존성 한 줄 뒤에는 무엇이 따라올까

<!-- Maven 의존성 예: 공개 배포판 2.1.0 사용 -->
<dependency>
  <groupId>io.modelcontextprotocol.sdk</groupId>
  <artifactId>mcp</artifactId>
  <version>2.1.0</version>
</dependency>

mcp/pom.xml은 mcp-core와 mcp-json-jackson3를 묶습니다. 커밋 기준 packaging은 jar이며 mcp/src/main/java/module-info.java도 있습니다. 업무 기능을 잔뜩 넣은 앱이라기보다, 기본 선택을 전달하는 편의 모듈입니다. 버전을 일괄 관리하려면 mcp-bom을 사용합니다.

4아키텍처 심화 분석

4-1. 전체 시스템 구조

아래는 io.modelcontextprotocol.client와 io.modelcontextprotocol.server의 기존 API 경로입니다. 모델과 도구 선택을 담당하는 호스트는 SDK 바깥에 있고, Java SDK의 클라이언트는 그 호스트 안에서 통신을 맡을 수 있습니다. 표준 입출력과 HTTP는 같은 기능 호출을 서로 다른 통로로 전달합니다.

핵심 구현은 mcp-core/src/main/java/io/modelcontextprotocol/ 아래에 있습니다. 다이어그램의 클래스는 그 아래 client/, spec/, server/에서 찾을 수 있습니다. 전송별 세션 구현은 다르므로, 모든 경로가 정확히 같은 서버 세션 클래스를 거친다고 읽으면 안 됩니다.

4-2. 패턴 ① Facade — 쉬운 동기 API를 비동기 코어 위에

mcp-core/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java의 callTool()은 별도의 통신 엔진을 만들지 않습니다. McpAsyncClient인 delegate에 호출을 넘기고, 반환된 Mono에서 결과를 기다립니다.

// McpSyncClient.callTool()의 실제 위임 구조
public McpSchema.CallToolResult callTool(
        McpSchema.CallToolRequest callToolRequest) {
    return withProvidedContext(
        this.delegate.callTool(callToolRequest)
    ).block();
}

서버 방향에도 같은 경계가 있습니다. mcp-core/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java의 AsyncToolSpecification.fromSync()는 동기 핸들러를 Mono.fromCallable()로 감싸며, 일반 경로에서는 Schedulers.boundedElastic()에 실행을 맡깁니다. immediate 옵션이 참인 경로는 스케줄러 전환을 생략합니다. “동기 API를 지원한다”는 말 뒤에 실행 스레드 선택까지 있다는 점이 학습 포인트입니다.

4-3. 패턴 ② Strategy와 Adapter — 업무와 전송·JSON 구현을 분리

mcp-core/src/main/java/io/modelcontextprotocol/spec/McpTransport.java는 sendMessage(), closeGracefully(), unmarshalFrom() 같은 계약을 정의합니다. StdioClientTransport.connect()는 ProcessBuilder로 서버 프로세스를 시작하고, HTTP 구현은 JDK HttpClient를 사용합니다. 호출자는 “도구를 실행한다”는 의도를 유지하면서 전송 전략을 바꿀 수 있습니다.

JSON 쪽에서는 mcp-core/src/main/java/io/modelcontextprotocol/json/McpJsonMapper.java가 readValue(), convertValue(), writeValueAsString() 등을 정의합니다. mcp-json-jackson3/src/main/java/io/modelcontextprotocol/json/jackson3/JacksonMcpJsonMapper.java는 Jackson의 JsonMapper 호출을 이 인터페이스에 맞추는 Adapter입니다.

기본 구현은 McpJsonDefaults.getMapper()에서 가져옵니다. 내부의 McpServiceLoader.getDefault()는 일반 Java 환경에서 ServiceLoader.load(...).findFirst()로 공급자를 찾고 결과를 저장합니다. Jackson 3 공급자 이름은 mcp-json-jackson3/src/main/resources/META-INF/services/io.modelcontextprotocol.json.McpJsonMapperSupplier에 적혀 있습니다.

4-4. 패턴 ③ 요청 상관관계와 초기화 게이트 — 동시에 보내도 응답을 찾기

mcp-core/src/main/java/io/modelcontextprotocol/spec/McpClientSession.java의 generateRequestId()는 세션 접두어와 AtomicLong 카운터를 합쳐 ID를 만듭니다. sendRequest()는 그 ID를 키로 pendingResponses에 응답 대기자를 저장합니다. handle()에 응답이 들어오면 같은 ID의 대기자를 꺼내 완료합니다.

자료구조는 ConcurrentHashMap<Object, MonoSink<McpSchema.JSONRPCResponse>>입니다. 이 구조에서 “동시성”은 단순히 스레드를 많이 만드는 문제가 아니라, 어느 응답이 누구의 결과인지 안전하게 연결하는 문제라는 사실이 드러납니다. sendRequest()의 timeout(requestTimeout)은 응답을 무한정 기다리지 않게 합니다.

메시지를 보내기 전에는 LifecycleInitializer.withInitialization()가 관문 역할을 합니다. AtomicReference.compareAndExchange()로 첫 초기화 작업을 정하고, 동시에 들어온 호출은 기존 초기화 결과를 기다립니다. doInitialize()는 initialize 요청, 버전 검사, notifications/initialized 통지를 수행합니다.

McpAsyncClient.callTool()은 이 관문 안에서 서버의 tools capability를 확인한 뒤 요청을 보냅니다. 명시적으로 initialize()를 호출해 흐름을 배울 수도 있지만, 소스에는 일반 작업 시 초기화를 보장하는 경로도 있습니다. 기존 API의 이 초기화 절차를 뒤에서 설명할 modern 서버에 그대로 적용해서는 안 됩니다.

4-5. 패턴 ④ Observer — 목록 변경을 기다리는 쪽에 알리기

분석 대상 커밋의 제목은 “Notify resources list_changed when removing a resource template (#1266)”입니다. 현재 McpAsyncServer.removeResourceTemplate()를 읽으면 실제 템플릿이 제거되고 resources.listChanged가 참일 때 notifyResourcesListChanged()로 이어집니다. 아래는 조건을 드러내기 위해 축약한 흐름입니다.

// removeResourceTemplate(): 조건 흐름을 보이기 위한 축약
return Mono.defer(() -> {
    var removed = this.resourceTemplates.remove(uriTemplate);
    if (removed != null
            && Boolean.TRUE.equals(
                this.serverCapabilities.resources().listChanged())) {
        return notifyResourcesListChanged();
    }
    return Mono.empty();
});

통지 메서드는 전송 Provider의 notifyClients()에 notifications/resources/list_changed를 전달합니다. 템플릿이 없거나 resources.listChanged가 true가 아니면 알리지 않습니다. resources capability 자체가 없으면 삭제 요청은 IllegalStateException으로 실패합니다. 자원 내용 변경 알림인 notifications/resources/updated와도 구분해야 합니다.

서버의 자료구조를 바꾸는 일과, 클라이언트가 가진 목록을 갱신하게 만드는 일은 별개의 책임입니다. 이 짧은 메서드 하나로 캐시·관찰자·기능 협상이 만나는 지점을 공부할 수 있습니다.

4-6. 같은 저장소의 다른 경로: modern 서버

mcp-core/src/main/java/io/modelcontextprotocol/modern/McpSchema.java는 LATEST_PROTOCOL_VERSION = "2026-07-28"을 선언합니다. mcp-core/src/main/java/io/modelcontextprotocol/modern/server/McpServer.java는 요청마다 _meta의 버전과 capabilities를 검사하고, dispatch()에서 해당 McpFeature로 보냅니다. ToolsFeature.handle()는 repository의 list(), find(), call()을 사용합니다.

이 경로는 stateless 수명주기와 server/discover를 다룹니다. 기존 패키지의 McpServer와 클래스 이름이 같아도 계약이 다르므로 import를 확인해야 합니다. ROADMAP.md는 이 규격 지원을 3.x 계획으로 설명하지만, 현재 POM은 2.2.0-SNAPSHOT입니다. 코드가 존재한다는 사실과 안정된 배포 API로 약속되었다는 사실을 구분하는 사례입니다.

5디렉토리 구조 해부

5-1. 왜 JSON 구현을 core에서 떼었을까

mcp-json-jackson3가 core에 의존해야 SDK 인터페이스를 구현할 수 있습니다. 그런데 core 테스트가 다시 Jackson 3 모듈에 의존하면 모듈 간 순환이 생깁니다. README는 JSON 구현이 필요한 통합 테스트를 mcp-test로 옮긴 이유를 이 의존 관계로 설명합니다. 테스트 폴더 배치는 실행 속도뿐 아니라 모듈 의존 방향의 결과이기도 합니다.

표의 소스 파일은 모두 mcp-core/src/main/java/io/modelcontextprotocol/ 아래입니다. 처음부터 6,000줄이 넘는 스키마 파일을 정독하기보다, 호출 지점에서 필요한 레코드로 이동하는 편이 이해하기 쉽습니다.

5-2. 코드 규모는 무엇을 포함하는가

집계 기준은 커밋의 추적 파일이며, 빈 줄과 주석, 마지막 개행이 없는 줄까지 포함한 물리적 줄 수입니다. 생성된 target/ 출력이나 Git 내부 파일은 포함하지 않습니다. 따라서 74,017줄을 전부 업무 로직이라고 해석하거나, 테스트 줄 수를 기능 커버리지 비율로 바꿔 말할 수는 없습니다.

6학습 포인트 (기술별)

6-1. Java 레코드와 Builder: 올바른 객체를 만드는 경계

McpSchema.CallToolRequest는 name, arguments, meta를 가진 레코드입니다. builder(String name)은 빈 이름을 막지만, JSON을 읽는 fromJson()은 누락된 이름을 빈 문자열로 보정하고 경고합니다. “직접 생성할 때의 검증”과 “외부 메시지를 받아들일 때의 호환성 처리”가 같은 규칙은 아닙니다.

// 기존 spec 패키지의 요청 객체를 만드는 학습용 예
var request = McpSchema.CallToolRequest.builder("hello")
    .arguments(Map.of("name", "민수"))
    .build();

// arguments()는 Map<String, Object>를 돌려준다.
Object name = request.arguments().get("name");

작은 실습: builder(""), 직접 생성, 이름이 빠진 JSON 역직렬화를 각각 비교해 보세요. 어느 층에서 예외가 나고, 어느 층에서 보정되는지 표로 정리하면 MIGRATION-2.0.md가 설명하는 required-first Builder와 wire 호환성의 의미가 보입니다.

6-2. JSON Schema: 설명과 실행 조건을 같은 계약으로

Tool.inputSchema의 타입은 좁은 전용 레코드가 아닌 Map<String, Object>입니다. JSON Schema 키워드를 보존하기 위한 선택입니다. 다음 예시는 이름 문자열 하나를 받는 도구를 구성하는 메서드 안의 코드이며, 웹 서버 실행 전체를 포함하지 않습니다.

import java.util.List;
import java.util.Map;
import io.modelcontextprotocol.json.McpJsonDefaults;
import io.modelcontextprotocol.server.McpServer;
import io.modelcontextprotocol.server.McpServerFeatures;
import io.modelcontextprotocol.server.transport.StdioServerTransportProvider;
import io.modelcontextprotocol.spec.McpSchema;

// 아래 구문은 애플리케이션의 서버 구성 메서드 안에 둔다.
Map<String, Object> inputSchema = Map.of(
    "type", "object",
    "properties", Map.of(
        "name", Map.of("type", "string", "minLength", 1)),
    "required", List.of("name"),
    "additionalProperties", false
);

var hello = McpServerFeatures.SyncToolSpecification.builder()
    .tool(McpSchema.Tool.builder("hello", inputSchema)
        .description("이름을 받아 한국어 인사말을 반환합니다.")
        .build())
    .callHandler((exchange, request) -> {
        String name = (String) request.arguments().get("name");
        return McpSchema.CallToolResult.builder()
            .content(List.of(McpSchema.TextContent
                .builder("안녕하세요, " + name + "님!").build()))
            .isError(false)
            .build();
    })
    .build();

var transport = new StdioServerTransportProvider(
    McpJsonDefaults.getMapper());
var server = McpServer.sync(transport)
    .serverInfo("study-server", "1.0.0")
    .capabilities(McpSchema.ServerCapabilities.builder()
        .tools(false).build())
    .tools(hello)
    .build();

tools(false)의 false는 도구 기능을 끈다는 뜻이 아닙니다. tools capability를 만들되 목록 변경 알림을 선언하지 않는 값입니다. 서버 구성의 validateToolInputs 기본값은 true이며, ToolInputValidator.validate()가 핸들러 실행 전에 인자를 검사합니다. 검증이 비활성화되었거나 입력 스키마가 비어 있거나 검증기가 없으면 검사를 건너뜁니다. 서버의 종료는 애플리케이션 수명주기에 server.closeGracefully()를 연결해 처리해야 합니다.

작은 실습: 빈 이름, 숫자 이름, 추가 필드, 이름 누락을 각각 보내 보세요. 현재 검증 경로는 잘못된 입력을 CallToolResult의 isError=true로 돌려줍니다. 존재하지 않는 도구 이름의 JSON-RPC 오류와 구분하면 프로토콜 오류와 업무 결과 오류를 함께 배울 수 있습니다.

6-3. Reactor: 호출 표현과 실제 작업 시작 시점

Mono를 반환받았다는 사실만으로 그 작업이 끝난 것은 아닙니다. Mono.defer()는 구독 시점에 작업을 구성합니다. McpAsyncServer.removeResourceTemplate()가 그 안에서 Map을 수정하는 이유를 살펴보세요. 다만 이 SDK 내부에는 생성 시 연결을 구독하는 코드도 있으므로, “모든 동작이 항상 지연된다”고 일반화하면 안 됩니다.

// 비동기 호출을 연결하는 예: 완료·오류도 흐름의 일부다.
asyncClient.callTool(request)
    .map(result -> result.isError())
    .subscribe(
        isError -> logger.info("도구 오류 여부: {}", isError),
        error -> logger.error("통신 실패", error)
    );

작은 실습: mock 전송으로 응답을 늦추고 타임아웃을 짧게 설정해 결과를 관찰하세요. McpClient.SyncSpec와 AsyncSpec의 요청·초기화 제한 시간은 각각 기본 20초입니다. 타임아웃은 대기 정책이며, 이미 수행된 외부 작업을 되돌리는 트랜잭션은 아닙니다.

6-4. 페이지네이션: 첫 페이지와 전체 목록을 구분

McpAsyncClient.listTools()는 expand()로 nextCursor를 따라가고 reduceWith()로 도구를 모읍니다. 반면 listTools(String cursor)는 지정한 페이지를 조회합니다. 목록이 크면 전체를 한 번에 모으는 편의성과 메모리 사용 사이의 선택이 생깁니다.

작은 실습: 두 페이지를 반환하는 mock 서버를 만들고 두 메서드의 요청 횟수를 비교하세요. 잘못된 서버가 같은 커서를 반복할 때를 별도 실패 사례로 설계해 보는 것도 좋습니다.

6-5. HTTP와 STDIO: 메시지 내용 바깥의 조건

HttpServletStreamableServerTransportProvider.doPost()는 요청 크기, 헤더, Content-Type 등을 먼저 확인합니다. Accept에 application/json과 text/event-stream이 필요한 경로도 있습니다. JSON 문법이 맞더라도 전송 계층에서 거절될 수 있습니다.

STDIO에서는 System.out이 프로토콜 메시지 통로입니다. 학습 중 진단 문자열을 임의로 출력하면 상대가 JSON으로 읽지 못할 수 있습니다. 로그를 stderr 쪽으로 보내도록 구성하고, UTF-8 메시지가 여러 바이트 조각으로 나뉘는 경우도 살펴보세요.

6-6. 테스트 설계: 성공보다 경계를 자세히

mcp-core/src/test/java/io/modelcontextprotocol/util/ToolInputValidatorTests.java는 검증기 부재·비활성화·잘못된 입력·null 인자를 나눕니다. mcp-core/src/test/java/io/modelcontextprotocol/client/transport/Utf8LineDecoderBoundTests.java는 바이트 수가 아닌 디코딩된 문자 수에 따른 줄 길이 경계를, mcp-test/src/test/java/io/modelcontextprotocol/server/DerivedCapabilitiesRuntimeChangesTests.java는 자동으로 파생된 capabilities의 목록 변경 알림 값이 null인 상태에서 런타임 변경을 다룹니다.

통신 라이브러리에서 배울 핵심은 성공 예제보다, 입력·상태·시간·종료 경계를 나누어 검증하는 방법입니다. 작은 실습: 테스트 하나를 읽고 “이 테스트가 없으면 어떤 사용자 문제가 생기는가”를 한 문장으로 적어 보세요.

7하드웨어 / 시스템 요구사항

SDK 자체는 GPU 계산을 하지 않습니다. 모델을 별도로 실행하거나 이미지·오디오를 처리하는 도구를 붙이면 그 기능의 요구사항이 더해집니다. 실행 부담은 MCP 라이브러리보다 연결한 도구와 모델, 동시 요청 수에 더 크게 좌우됩니다.

학습용 권장 출발점: 2~4코어 CPU, RAM 8GB 이상, 남은 디스크 수 GB를 잡을 수 있습니다. IDE와 Docker를 함께 사용하면 RAM 16GB가 더 여유롭습니다. 이는 공식 보장 사양이나 실측 결과가 아닌 일반 개발 환경을 위한 추정입니다. 큰 모델 가중치 저장 공간은 이 SDK의 크기와 별도로 계산해야 합니다.

7-1. HTTP 서버의 실제 실행 환경

Servlet 전송 객체를 만들었다고 포트가 열리지는 않습니다. conformance-tests/server-servlet/src/main/java/io/modelcontextprotocol/conformance/server/ConformanceServlet.java의 main()은 전송 Provider를 만든 뒤 Tomcat에 Servlet을 등록하고 서버를 시작합니다. 그 검증 앱은 8080 포트와 /mcp 경로를 사용합니다. 이 값은 SDK 전체에 강제되는 포트가 아닙니다.

7-2. 연결을 오래 유지할 때 필요한 관찰 지표

기존 Streamable HTTP 서버 Builder의 기본값은 mcpEndpoint="/mcp", keepAliveInterval=30분, sessionSweepInterval=30분입니다. 열린 스트림이 있는 세션의 keep-alive와, 열린 스트림도 최근 요청도 없는 세션의 정리는 다른 목적입니다. 지연 시간뿐 아니라 열린 연결 수, 메모리, 타임아웃, 종료 후 남는 프로세스를 관찰해야 합니다.

8직접 해볼 수 있는 실습 과제

실습용 앱은 SDK 소스와 별도 프로젝트로 구성하고, 공개 배포판을 쓸 때는 의존성을 2.1.0으로 고정하세요. 아래 소스 탐색과 회귀 조건은 커밋 54e8b61 기준입니다. modern API까지 실험하려면 그 코드가 포함된 버전과 별도의 프로토콜 계약을 먼저 확인해야 합니다.

// HTTP 실습 앱 안의 클라이언트 구성: 기존 client/spec API
var transport = HttpClientStreamableHttpTransport
    .builder("http://localhost:8080")
    .endpoint("/mcp")
    .build();

try (var client = McpClient.sync(transport).build()) {
    client.initialize();
    var tools = client.listTools();
    var result = client.callTool(
        McpSchema.CallToolRequest.builder("hello")
            .arguments(Map.of("name", "민수"))
            .build());
    // tools와 result를 실습 앱의 로그·검증 코드에서 확인한다.
}

실습의 완료 기준은 실행 화면 한 장보다, 정상·실패·종료 조건을 다른 사람이 재현할 수 있게 설명하는 것입니다. 전체 빌드나 적합성 검증은 Docker·npx 등 준비 조건을 갖춘 뒤 공식 개발 문서의 절차로 진행하세요.

9관련 기술 심화 학습 로드맵

주당 3~5시간 정도를 가정한 학습 제안입니다. Java 경험이 있다면 1주차를 줄이고 테스트·네트워크에 시간을 더 쓸 수 있습니다. 각 주차마다 설명 문서 하나보다 작은 산출물 하나를 남기는 방식입니다.

9-1. 3주차에 꼭 답해 볼 질문

• Mono를 만드는 시점과 그 안의 작업이 수행되는 시점은 어떻게 다른가?
• block()은 어느 스레드를 기다리게 하며, 그 스레드는 다른 요청을 처리해야 하는가?
• 성공 값이 없는 완료와 오류는 어떻게 다른가? Mono<Void>는 무엇을 표현하는가?
• 제한 시간이 지나도 원격 쓰기 작업이 완료될 수 있다면, 재시도 정책은 어떻게 정해야 하는가?

9-2. 6주 뒤에는 한 기능의 전문가가 되기

다음 단계에서는 resources 구독, 출력 스키마 검증, 요청 커스터마이저, modern의 repository 중 하나만 고르세요. 인터페이스, 기본 구현, 정상 테스트, 실패 테스트, 버전 변경 안내를 한 묶음으로 읽으면 공개 API가 유지해야 할 약속을 이해할 수 있습니다.

프로젝트 전체를 한 번 훑는 것보다, 입력부터 테스트까지 한 경로를 끝까지 설명할 수 있는 것이 더 확실한 학습입니다. 마지막에는 도구 하나의 사용법을 넘어, 그 도구를 안전하게 호출하게 하는 계약까지 자신의 말로 설명해 보세요.

10핵심 키워드 사전

11참고 링크

11-1. 공식 저장소와 규격·기술 문서

• 공식 저장소: modelcontextprotocol/java-sdk
• v2.1.0 릴리스 노트 — 2026-10-16 공개 배포의 변화
• Java SDK 공식 시작 안내 · 클라이언트 · 서버
• mcp-core 2.1.0 Javadoc — 배포 버전을 고정한 API 문서
• MCP 2025-11-25 규격 · MCP 2026-07-28 규격
• JSON-RPC 2.0 규격 · JSON Schema 2020-12
• Project Reactor 공식 설명서 — Mono·Flux·스케줄러·오류 처리
• Java 17 ServiceLoader API · JDK HttpClient API
• Spring AI MCP 통합 문서 — README가 안내하는 외부 통합 경로
• MCP 적합성 검증 도구 · Maven 의존성 관리 안내

11-2. 핵심 소스 다시 읽기 — 모두 커밋 고정

• pom.xml · mcp-core/pom.xml — 버전과 의존 범위
• McpSyncClient.java · McpAsyncClient.java — 동기 위임과 도구 호출
• LifecycleInitializer.java · McpClientSession.java — 초기화와 요청 ID
• McpAsyncServer.java · ToolInputValidator.java — 핸들러 호출과 템플릿 삭제 알림
• McpJsonDefaults.java · McpServiceLoader.java — JSON 공급자 탐색
• HttpServletStreamableServerTransportProvider.java — HTTP 입력 조건과 기본 설정
• modern/server/McpServer.java · ToolsFeature.java — 새 규격의 요청 분배
• VALIDATION_RESULTS.md · conformance.yml — 검증 기록과 CI 조건
• MIGRATION-2.0.md · ROADMAP.md · DEPENDENCY_POLICY.md

11-3. 현재 상태 (2026-10-23 확인)