MCP 문서
SDK
Java SDK
개요

개요

Model Context Protocol용 Java SDK는 AI 모델과 도구 간 표준화된 통합을 가능하게 합니다.

기능

  • MCP Client 및 MCP Server 구현체 제공(지원 범위):
  • 다양한 전송(transport) 구현:
    • 기본 전송:
      • 프로세스 기반 통신을 위한 stdio 전송
      • HTTP SSE 클라이언트 스트리밍을 위한 Java HttpClient 기반 SSE 클라이언트 전송
      • HTTP SSE 서버 스트리밍을 위한 Servlet 기반 SSE 서버 전송
    • Spring 기반 전송:
      • 리액티브 HTTP 스트리밍을 위한 WebFlux SSE 클라이언트/서버 전송
      • 서블릿 기반 HTTP 스트리밍을 위한 WebMVC SSE 전송
  • 동기/비동기 프로그래밍 패러다임 모두 지원

아키텍처

SDK는 관심사의 분리를 명확히 한 레이어드 아키텍처를 따릅니다:

MCP Stack Architecture

  • 클라이언트/서버 레이어(McpClient/McpServer): 둘 다 McpSession을 사용해 동기/비동기 작업을 수행합니다. McpClient는 클라이언트 측 프로토콜 동작을, McpServer는 서버 측 프로토콜 동작을 담당합니다.
  • 세션 레이어(McpSession): DefaultMcpSession 구현을 통해 통신 패턴과 상태를 관리합니다.
  • 전송 레이어(McpTransport): 다음을 통해 JSON-RPC 메시지 직렬화/역직렬화를 처리합니다.
    • 코어 모듈의 StdioTransport(stdin/stdout)
    • 전용 전송 모듈의 HTTP SSE 전송(Java HttpClient, Spring WebFlux, Spring WebMVC)

MCP 클라이언트는 MCP 아키텍처의 핵심 구성 요소로, MCP 서버와의 연결을 수립하고 관리합니다. 즉, 프로토콜의 클라이언트 측을 구현합니다.

Java MCP Client Architecture

MCP 서버는 MCP 아키텍처의 기반 구성 요소로, 클라이언트에 도구/리소스/기능을 제공합니다. 즉, 프로토콜의 서버 측을 구현합니다.

Java MCP Server Architecture

핵심 상호작용:

  • 클라이언트/서버 초기화: 전송 설정, 프로토콜 호환성 확인, capability 협상, 구현 세부정보 교환
  • 메시지 흐름: 검증을 포함한 JSON-RPC 메시지 처리, 타입 안전 응답 처리, 오류 처리
  • 리소스 관리: 리소스 탐색, URI 템플릿 기반 접근, 구독 시스템, 콘텐츠 조회

의존성

프로젝트에 다음 Maven 의존성을 추가하세요:

코어 MCP 기능:

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

HTTP SSE 전송 구현을 사용하려면 아래 의존성 중 하나를 추가하세요:

<!-- Spring WebFlux-based SSE client and server transport -->
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webflux</artifactId>
</dependency>

<!-- Spring WebMVC-based SSE server transport -->
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webmvc</artifactId>
</dependency>

코어 MCP 기능:

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

HTTP SSE 전송 구현을 사용하려면 아래 의존성 중 하나를 추가하세요:

// Spring WebFlux-based SSE client and server transport
dependencies {
  implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webflux")
}

// Spring WebMVC-based SSE server transport
dependencies {
  implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webmvc")
}

Bill of Materials(BOM)

BOM(Bill of Materials)은 특정 릴리스에서 사용되는 모든 의존성의 권장 버전을 선언합니다. 애플리케이션의 빌드 스크립트에서 BOM을 사용하면, 개별 의존성 버전을 직접 지정하고 유지보수할 필요가 줄어듭니다. 대신 사용 중인 BOM 버전이 실제로 사용되는 의존성 버전을 결정합니다. 또한 별도로 오버라이드하지 않는 한, 기본적으로 지원되고 테스트된 버전 조합을 사용하도록 보장합니다.

프로젝트에 BOM을 추가하세요:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.modelcontextprotocol.sdk</groupId>
            <artifactId>mcp-bom</artifactId>
            <version>0.7.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
dependencies {
  implementation platform("io.modelcontextprotocol.sdk:mcp-bom:0.7.0")
  //...
}

Gradle 사용자는 Gradle(5.0+)의 Maven BOM 기반 의존성 제약 선언 기능을 활용해 Spring AI MCP BOM도 사용할 수 있습니다. 이는 Gradle 빌드 스크립트의 dependencies 섹션에 ‘platform’ 의존성을 추가하는 방식으로 구현됩니다. 위 예시처럼 설정한 뒤에는, 사용하고 싶은 spring-ai 모듈(예: spring-ai-openai)의 스타터 의존성을 버전 없이 선언할 수 있습니다.

BOM 버전은 원하는 버전으로 교체해서 사용하세요.

사용 가능한 의존성

BOM에서 관리하는 의존성은 다음과 같습니다:

  • 코어 의존성
    • io.modelcontextprotocol.sdk:mcp - Model Context Protocol 구현을 위한 코어 라이브러리(기본 기능 및 API 제공)
  • 전송(transport) 의존성
    • io.modelcontextprotocol.sdk:mcp-spring-webflux - 리액티브 애플리케이션을 위한 WebFlux 기반 SSE(Server-Sent Events) 전송 구현
    • io.modelcontextprotocol.sdk:mcp-spring-webmvc - 서블릿 기반 애플리케이션을 위한 WebMVC 기반 SSE 전송 구현
  • 테스트 의존성
    • io.modelcontextprotocol.sdk:mcp-test - MCP 기반 애플리케이션을 위한 테스트 유틸리티 및 지원
MCP 서버