Model Context Protocol

Model Context Protocol (MCP)

AI 모델이 데이터베이스, API, 파일 시스템 같은 외부 도구와 서비스를 표준화된 방식으로 쓰게 해 주는 프로토콜이 바로 Model Context Protocol(MCP)이에요. 여기서는 Spring AI가 이 MCP를 어떻게 지원하는지, 클라이언트와 서버 양쪽을 어떻게 붙일 수 있는지 정리할게요.

출처: 공식문서

TIP: MCP가 처음이신가요? 빠른 소개와 실습 예제는 Getting Started with MCP 가이드로 시작하세요.

MCP는 AI 모델이 외부 도구와 리소스에 구조화된 방식으로 상호작용하게 해 주는 표준화된 프로토콜입니다. 쉽게 말하면 AI 모델과 현실 세계 사이의 다리예요. 일관된 인터페이스를 통해 데이터베이스, API, 파일 시스템, 다른 외부 서비스에 접근하게 해 줍니다. 여러 환경에서 유연하게 쓰일 수 있도록 다양한 전송(transport) 메커니즘도 지원해요.

MCP Java SDK는 Model Context Protocol의 Java 구현으로, 동기·비동기 통신 패턴을 통해 AI 모델과 도구의 표준화된 상호작용을 지원합니다.

Spring AI는 전용 Boot Starter와 MCP Java Annotations를 통해 MCP를 폭넓게 지원해서, 외부 시스템에 매끄럽게 연결되는 정교한 AI 애플리케이션을 더 쉽게 만들 수 있게 해 줘요. 즉 Spring 개발자는 MCP 에코시스템의 양쪽에 모두 참여할 수 있습니다. MCP 서버를 소비하는 AI 애플리케이션을 만들 수도 있고, Spring 기반 서비스를 더 넓은 AI 커뮤니티에 노출하는 MCP 서버를 만들 수도 있어요. Spring Initializr에서 MCP 지원으로 AI 애플리케이션을 시작해 보세요.

MCP Java SDK 아키텍처

TIP: 이 절은 MCP Java SDK 아키텍처 개요입니다. Spring AI MCP 통합은 아래 Spring AI MCP Boot Starters 문서를 참고하세요.

Java MCP 구현은 관심사를 분리해 유지보수성과 유연성을 높이는 3계층 아키텍처를 따릅니다.

클라이언트/서버 계층 (상단)

상단 계층이 메인 애플리케이션 로직과 프로토콜 연산을 처리합니다.

• McpClient — 클라이언트 측 연산과 서버 연결을 관리
• McpServer — 서버 측 프로토콜 연산과 클라이언트 요청을 처리
• 두 컴포넌트 모두 아래의 세션 계층을 사용해 통신을 관리

세션 계층 (중간)

중간 계층이 통신 패턴과 연결 상태를 관리합니다.

• McpSession — 핵심 세션 관리 인터페이스
• McpClientSession — 클라이언트 전용 세션 구현
• McpServerSession — 서버 전용 세션 구현

전송 계층 (하단)

하단 계층이 실제 메시지 전송과 직렬화를 처리합니다.

• McpTransport — JSON-RPC 메시지 직렬화/역직렬화 관리
• 여러 전송 구현 지원 (STDIO, HTTP/SSE, Streamable-HTTP 등)
• 모든 상위 수준 통신의 기반 제공

MCP Client는 MCP 아키텍처의 핵심 컴포넌트로, MCP 서버와의 연결을 수립하고 관리합니다. 프로토콜의 클라이언트 측을 구현하며 다음을 처리해요.

• 서버와의 호환을 위한 프로토콜 버전 협상
• 사용 가능한 기능을 결정하는 기능 협상
• 메시지 전송과 JSON-RPC 통신
• 도구 발견과 실행
• 리소스 접근과 관리
• 프롬프트 시스템 상호작용
• 선택 기능:
  • Roots 관리
  • 샘플링 지원
• 동기·비동기 연산
• 전송 옵션:
  • 프로세스 기반 통신을 위한 Stdio 전송
  • Java HttpClient 기반 SSE 클라이언트 전송
  • 리액티브 HTTP 스트리밍을 위한 WebFlux SSE 클라이언트 전송

MCP Server는 MCP 아키텍처의 기반 컴포넌트로, 클라이언트에 도구·리소스·능력을 제공합니다. 프로토콜의 서버 측을 구현하며 다음을 담당해요.

• 서버 측 프로토콜 연산 구현
  • 도구 노출과 발견
  • URI 기반 접근으로 리소스 관리
  • 프롬프트 템플릿 제공과 처리
  • 클라이언트와의 기능 협상
  • 구조화된 로깅과 알림
• 동시 클라이언트 연결 관리
• 동기·비동기 API 지원
• 전송 구현: Stdio, Streamable-HTTP, Stateless Streamable-HTTP, SSE

저수준 MCP Client/Server API를 쓰는 자세한 구현 가이드는 MCP Java SDK 문서를 참고하세요. Spring Boot로 간단히 설정하려면 아래 MCP Boot Starters를 사용하면 돼요.

Spring AI MCP 통합

Spring AI는 다음 Spring Boot 스타터로 MCP 통합을 제공합니다.

Client Starters

• spring-ai-starter-mcp-client — STDIO, Servlet 기반 Streamable-HTTP, Stateless Streamable-HTTP, SSE 지원을 제공하는 핵심 스타터
• spring-ai-starter-mcp-client-webflux — WebFlux 기반 Streamable-HTTP, Stateless Streamable-HTTP, SSE 전송 구현

Server Starters

STDIO

Server Type	Dependency	Property
Standard Input/Output (STDIO)	spring-ai-starter-mcp-server	spring.ai.mcp.server.stdio=true

WebMVC

Server Type	Dependency	Property
SSE WebMVC	spring-ai-starter-mcp-server-webmvc	spring.ai.mcp.server.protocol=SSE 또는 비어 있음
Streamable-HTTP WebMVC	spring-ai-starter-mcp-server-webmvc	spring.ai.mcp.server.protocol=STREAMABLE
Stateless Streamable-HTTP WebMVC	spring-ai-starter-mcp-server-webmvc	spring.ai.mcp.server.protocol=STATELESS

WebFlux (Reactive)

Server Type	Dependency	Property
SSE WebFlux	spring-ai-starter-mcp-server-webflux	spring.ai.mcp.server.protocol=SSE 또는 비어 있음
Streamable-HTTP WebFlux	spring-ai-starter-mcp-server-webflux	spring.ai.mcp.server.protocol=STREAMABLE
Stateless Streamable-HTTP WebFlux	spring-ai-starter-mcp-server-webflux	spring.ai.mcp.server.protocol=STATELESS

Spring AI MCP Annotations

프로그래매틱 MCP 클라이언트·서버 구성 외에도, Spring AI는 MCP Annotations 모듈을 통해 MCP 서버와 클라이언트의 애노테이션 기반 메서드 처리를 제공합니다. 이 방식은 Java 애노테이션으로 깔끔한 선언형 프로그래밍 모델을 써서 MCP 연산의 생성과 등록을 단순화해요.

MCP Annotations 모듈을 쓰면 다음이 가능합니다.

• 간단한 애노테이션으로 MCP 도구·리소스·프롬프트 생성
• 클라이언트 측 알림과 요청을 선언적으로 처리
• 보일러플레이트 코드를 줄이고 유지보수성 향상
• 도구 파라미터의 JSON 스키마 자동 생성
• 특수 파라미터와 컨텍스트 정보 접근

주요 기능:

• Server Annotations: @McpTool, @McpResource, @McpPrompt, @McpComplete
• Client Annotations: @McpLogging, @McpSampling, @McpElicitation, @McpProgress
• Special Parameters: McpSyncServerExchange, McpAsyncServerExchange, McpTransportContext, McpMeta
• 자동 발견: 구성 가능한 패키지 포함/제외로 애노테이션 스캔
• Spring Boot 통합: MCP Boot Starters와 매끄럽게 연동

Spring AI 2.0으로 업그레이드

Spring AI 2.0부터 Spring 관련 MCP 전송 구현(mcp-spring-webflux, mcp-spring-webmvc)이 더 이상 MCP Java SDK에 포함되지 않습니다. 이들은 Spring AI 프로젝트 자체로 이동했어요. 이는 이 전송 아티팩트나 클래스를 직접 참조하는 애플리케이션에서 의존성과 import를 갱신해야 하는 breaking change입니다.

Maven 의존성 Group ID 변경

mcp-spring-webflux와 mcp-spring-webmvc 아티팩트가 io.modelcontextprotocol.sdk 그룹에서 org.springframework.ai 그룹으로 이동했습니다.

이전 (MCP Java SDK < 1.0.x 그리고 Spring AI < 2.0.x):

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

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

이후 (MCP Java SDK >= 1.0.x 그리고 Spring AI >= 2.0.x):

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>mcp-spring-webflux</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>mcp-spring-webmvc</artifactId>
</dependency>

NOTE: spring-ai-bom이나 Spring AI 스타터 의존성(spring-ai-starter-mcp-server-webflux, spring-ai-starter-mcp-server-webmvc, spring-ai-starter-mcp-client-webflux)을 쓸 때는 명시적 버전이 필요 없습니다 — BOM이 자동으로 관리해요.

Java 패키지 이전(Relocation)

모든 전송 클래스가 org.springframework.ai 패키지로 이전됐습니다.

서버 전송 클래스:

Class	Old package (MCP SDK)	New package (Spring AI)
WebFluxSseServerTransportProvider	io.modelcontextprotocol.server.transport	org.springframework.ai.mcp.server.webflux.transport
WebFluxStreamableServerTransportProvider	io.modelcontextprotocol.server.transport	org.springframework.ai.mcp.server.webflux.transport
WebFluxStatelessServerTransport	io.modelcontextprotocol.server.transport	org.springframework.ai.mcp.server.webflux.transport
WebMvcSseServerTransportProvider	io.modelcontextprotocol.server.transport	org.springframework.ai.mcp.server.webmvc.transport
WebMvcStreamableServerTransportProvider	io.modelcontextprotocol.server.transport	org.springframework.ai.mcp.server.webmvc.transport
WebMvcStatelessServerTransport	io.modelcontextprotocol.server.transport	org.springframework.ai.mcp.server.webmvc.transport

클라이언트 전송 클래스:

Class	Old package (MCP SDK)	New package (Spring AI)
WebFluxSseClientTransport	io.modelcontextprotocol.client.transport	org.springframework.ai.mcp.client.webflux.transport
WebClientStreamableHttpTransport	io.modelcontextprotocol.client.transport	org.springframework.ai.mcp.client.webflux.transport

import 갱신 예시:

// Before
import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;

// After
import org.springframework.ai.mcp.server.webflux.transport.WebFluxSseServerTransportProvider;
import org.springframework.ai.mcp.server.webmvc.transport.WebMvcSseServerTransportProvider;
import org.springframework.ai.mcp.client.webflux.transport.WebFluxSseClientTransport;
import org.springframework.ai.mcp.client.webflux.transport.WebClientStreamableHttpTransport;

MCP SDK 버전 요구 사항

Spring AI 2.0은 MCP Java SDK 1.0.0(RC1 이상)을 요구합니다. SDK 버전이 0.18.x에서 1.0.x 릴리스 라인으로 올라갔어요. BOM이나 명시적 버전을 그에 맞게 갱신하세요.

Spring Boot 자동 구성 사용자

Spring AI 스타터를 통해 오로지 Spring Boot 자동 구성에만 의존한다면 Java 코드는 전혀 바꿀 필요가 없습니다. 자동 구성은 이미 내부적으로 새 패키지를 참조하도록 갱신됐어요. 위에서 설명한 대로 pom.xml/build.gradle 의존성 좌표만 갱신하면 됩니다.

참고 자료

• MCP Annotations Documentation
• MCP Client Boot Starters Documentation
• MCP Server Boot Starters Documentation
• MCP Utilities Documentation
• Model Context Protocol Specification

더 알아보기

• Getting Started with MCP — MCP 입문 가이드
• Tools — 함수 호출/도구
• Effective Agents — 에이전트 구축 모범 사례