Java SDK 퀵스타트

Java SDK 퀵스타트

MCP Java SDK로 첫 발을 떼는 가장 빠른 길은 의존성을 몇 개 추가하고, 빌드 도구가 알아서 정리하도록 하는 거예요. 여기서는 Maven과 Gradle 기준으로 필요한 것들을 차근차근 짚어볼게요.

출처: Quickstart - MCP Java SDK

의존성 추가하기

프로젝트에 다음 의존성을 추가하면 돼요. 두 개의 mcp 모듈은 mcp-core에 Jackson 3.x JSON 직렬화를 묶어서 제공해요.

Maven:

<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>
</dependency>

이 모듈에는 기본 STDIO, SSE, Streamable HTTP 트랜스포트 구현이 들어 있어서 외부 웹 프레임워크 없이도 동작해요.

JSON 구현 없이 코어 모듈만 필요한 경우(직렬화를 직접 가져오고 싶을 때)에는 이렇게 해요:

<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-core</artifactId>
</dependency>

Jackson 3.x 대신 2.x를 쓰려면:

<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-core</artifactId>
</dependency>
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-json-jackson2</artifactId>
</dependency>

Spring Framework를 쓰고 있다면 Spring 전용 트랜스포트 구현은 이제 Spring AI 2.0+의 일부(group org.springframework.ai)로 제공돼요:

<!-- Optional: Spring WebFlux 기반 SSE 및 Streamable HTTP 클라이언트/서버 트랜스포트 (Spring AI 2.0+) -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>mcp-spring-webflux</artifactId>
</dependency>

<!-- Optional: Spring WebMVC 기반 SSE 및 Streamable HTTP 서버 트랜스포트 (Spring AI 2.0+) -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>mcp-spring-webmvc</artifactId>
</dependency>

Gradle:

dependencies {
    implementation "io.modelcontextprotocol.sdk:mcp"
}

코어만 필요한 경우:

dependencies {
    implementation "io.modelcontextprotocol.sdk:mcp-core"
}

Jackson 2.x를 쓰려면:

dependencies {
    implementation "io.modelcontextprotocol.sdk:mcp-core"
    implementation "io.modelcontextprotocol.sdk:mcp-json-jackson2"
}

Spring을 쓴다면:

// Optional: Spring WebFlux 기반 SSE 및 Streamable HTTP 클라이언트/서버 트랜스포트 (Spring AI 2.0+)
dependencies {
    implementation "org.springframework.ai:mcp-spring-webflux"
}

// Optional: Spring WebMVC 기반 SSE 및 Streamable HTTP 서버 트랜스포트 (Spring AI 2.0+)
dependencies {
    implementation "org.springframework.ai:mcp-spring-webmvc"
}

참고 — spring-ai-bom이나 Spring AI 스타터 의존성(spring-ai-starter-mcp-server-webflux, spring-ai-starter-mcp-server-webmvc, spring-ai-starter-mcp-client-webflux)을 쓰면 명시적인 버전을 적지 않아도 BOM이 자동 관리해요.

BOM (Bill of Materials)

BOM은 특정 릴리스가 사용하는 모든 의존성의 권장 버전을 선언해 두는 목록이에요. 애플리케이션 빌드 스크립트에서 BOM을 쓰면 의존성 버전을 직접 지정하고 관리할 필요가 없어져요. BOM의 버전이 실제 사용되는 의존성 버전을 결정하고, 별도로 오버라이드하지 않는 한 테스트된 지원 버전을 자동으로 쓰게 돼요.

Maven:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.modelcontextprotocol.sdk</groupId>
            <artifactId>mcp-bom</artifactId>
            <version>2.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Gradle:

dependencies {
    implementation platform("io.modelcontextprotocol.sdk:mcp-bom:2.0.0")
    //...
}

Gradle 5.0+를 쓰는 경우 Maven BOM을 이용해 의존성 제약을 선언하는 네이티브 지원도 사용할 수 있어요. 위의 예시처럼 platform 의존성 핸들러를 추가한 뒤, 버전 없는 선언들을 이어서 나열하면 됩니다.

버전 번호는 Maven Central의 최신 버전으로 바꿔 주세요.

사용 가능한 의존성

BOM이 관리하는 의존성 종류는 이렇게 나뉘어요:

  • 코어 의존성
    • io.modelcontextprotocol.sdk:mcp-core — 기본 기능, API, 기본 트랜스포트(STDIO, SSE, Streamable HTTP)를 제공하는 코어 MCP 라이브러리. JSON 바인딩은 플러그 가능하도록 추상화되어 있어요.
    • io.modelcontextprotocol.sdk:mcp — mcp-core에 mcp-json-jackson3을 묶어 바로 쓸 수 있게 한 편의 번들.
  • JSON 직렬화
    • io.modelcontextprotocol.sdk:mcp-json-jackson3 — Jackson 3.x JSON 직렬화 구현(mcp 번들에 포함).
    • io.modelcontextprotocol.sdk:mcp-json-jackson2 — Jackson 2.x 호환이 필요한 프로젝트용 Jackson 2.x JSON 직렬화 구현.
  • 선택적 Spring 트랜스포트 의존성 (Spring AI 2.0+ 일부, group org.springframework.ai)
    • org.springframework.ai:mcp-spring-webflux — 리액티브 애플리케이션용 WebFlux 기반 SSE 및 Streamable HTTP 트랜스포트.
    • org.springframework.ai:mcp-spring-webmvc — 서블릿 기반 애플리케이션용 WebMVC 기반 SSE 및 Streamable HTTP 트랜스포트.
  • 테스트 의존성
    • io.modelcontextprotocol.sdk:mcp-test — MCP 기반 애플리케이션을 위한 테스트 유틸리티와 지원.

더 알아보기 (Learn more)