[Spring AI 2025 Renewal #8] Model Context Protocol (MCP)

안녕하세요 dev_writer입니다. 

 

이번 시간에는 Spring AI 공식 문서 중 MCP에 대해 번역한 내용을 전달해 드리겠습니다.

 

Model Context Protocol (MCP)

모델 컨텍스트 프로토콜(Model Context Protocol, MCP)은 AI 모델이 외부 도구 및 리소스와 구조화된 방식으로 상호작용할 수 있도록 해주는 표준화된 프로토콜입니다. 다양한 환경에서 유연성을 제공하기 위해 여러 전송 메커니즘을 지원합니다.

 

MCP Java SDK는 모델 컨텍스트 프로토콜의 Java 구현체로, 동기 및 비동기 통신 방식을 통해 AI 모델과 도구 간의 표준화된 상호작용을 가능하게 합니다.

 

Spring AI MCP는 MCP Java SDK에 Spring Boot 통합 기능을 확장한 것으로, 클라이언트 및 서버 스타터를 모두 제공합니다. Spring Initializer를 사용해 MCP 지원이 포함된 AI 애플리케이션을 신속하게 부트스트랩할 수 있습니다.

 

참고
MCP Java SDK 0.8.0의 주요 변경 사항 ⚠️ MCP Java SDK 0.8.0 버전에서는 세션 기반 아키텍처 등 여러 가지 주요 변경 사항이 도입되었습니다. Java SDK 0.7.0에서 업그레이드하는 경우, 자세한 내용은 마이그레이션 가이드를 참고하시기 바랍니다.

 

MCP Java SDK 아키텍처

팁
이 섹션은 MCP Java SDK 아키텍처에 대한 개요를 제공합니다. Spring AI MCP 통합에 대한 내용은 Spring AI MCP Boot Starters 문서를 참고하세요.

 

Java MCP 구현은 3 계층 아키텍처를 따릅니다:

출처: Spring AI 공식 문서

• 클라이언트/서버 계층 (Client/Server Layer): McpClient는 클라이언트 측 작업을 처리하고, McpServer는 서버 측 프로토콜 작업을 관리합니다. 두 구성 요소 모두 통신 관리를 위해 McpSession을 사용합니다.
• 세션 계층 (Session Layer - McpSession): DefaultMcpSession 구현체를 통해 통신 패턴과 상태를 관리합니다.
• 전송 계층 (Transport Layer - McpTransport): JSON-RPC 메시지의 직렬화 및 역직렬화를 처리하며, 다양한 전송 방식 구현을 지원합니다.

MCP 클라이언트

MCP 클라이언트(MCP Client)는 모델 컨텍스트 프로토콜(MCP) 아키텍처의 핵심 구성 요소로, MCP 서버와의 연결을 설정하고 관리하는 역할을 합니다. 이 구성 요소는 프로토콜의 클라이언트 측을 구현하며 다음과 같은 기능을 담당합니다:

출처: Spring AI 공식 문서

• 서버와의 프로토콜 버전 협상을 통해 호환성 보장
• 사용 가능한 기능을 확인하기 위한 기능 협상(Capability Negotiation)
• 메시지 전송 및 JSON-RPC 통신 처리
• 툴(도구) 검색 및 실행
• 리소스 접근 및 관리
• 프롬프트 시스템과의 상호작용 선택적 기능:
  • 루트(Roots) 관리
  • 샘플링(Sampling) 기능 지원

• 동기 및 비동기 처리 지원
• 지원 전송 방식:
  • 프로세스 기반 통신을 위한 Stdio 기반 전송 방식
  • Java HttpClient 기반 SSE 클라이언트 전송
  • WebFlux SSE 클라이언트 전송 – 리액티브 HTTP 스트리밍용

MCP 서버

MCP 서버(MCP Server)는 모델 컨텍스트 프로토콜(MCP) 아키텍처에서 기초적인 구성 요소로, 클라이언트에게 도구, 리소스, 기능을 제공합니다. 이 구성 요소는 프로토콜의 서버 측을 구현하며 다음과 같은 역할을 수행합니다:

출처 : Spring AI 공식 문서

• 서버 측 프로토콜 작업 처리
  • 툴(도구)의 노출 및 검색 지원
  • URI 기반 접근을 통한 리소스 관리
  • 프롬프트 템플릿 제공 및 처리
  • 클라이언트와의 기능 협상(Capability Negotiation)
  • 구조화된 로깅 및 알림(Notification) 지원
• 동시 클라이언트 연결 관리
• 동기 및 비동기 API 지원
• 지원 전송 방식:
  • Stdio 기반 전송 방식 – 프로세스 기반 통신용
  • Servlet 기반 SSE 서버 전송
  • WebFlux SSE 서버 전송 – 리액티브 HTTP 스트리밍용
  • WebMVC SSE 서버 전송 – 서블릿 기반 HTTP 스트리밍용

저수준 MCP 클라이언트/서버 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 및 HTTP 기반 SSE 지원을 제공하는 핵심 클라이언트 스타터
• spring-ai-starter-mcp-client-webflux
• WebFlux 기반 SSE 전송 구현

서버 스타터 (Server Starters)

•  spring-ai-starter-mcp-server STDIO 전송을 지원하는 핵심 서버 스타터
• spring-ai-starter-mcp-server-webmvc Spring MVC 기반 SSE 전송 구현
• spring-ai-starter-mcp-server-webflux WebFlux 기반 SSE 전송 구현

추가 자료

• MCP 클라이언트 Boot 스타터 문서
• MCP 서버 Boot 스타터 문서
• MCP 유틸리티 문서
• Model Context Protocol 명세서

---

MCP 클라이언트 Boot 스타터

Spring AI MCP (Model Context Protocol) 클라이언트 Boot 스타터는 Spring Boot 애플리케이션에서 MCP 클라이언트 기능을 자동으로 구성해 주는 모듈입니다. 동기 및 비동기 클라이언트 구현을 모두 지원하며, 다양한 전송 방식 옵션을 제공합니다.

 

MCP 클라이언트 Boot 스타터는 다음을 제공합니다: 

• 복수의 클라이언트 인스턴스 관리
• (활성화된 경우) 자동 클라이언트 초기화
• 이름 기반 전송 방식(multiple named transports) 지원
• Spring AI 툴 실행 프레임워크와 통합
• 애플리케이션 컨텍스트 종료 시 자원 자동 정리를 포함한 적절한 생명주기 관리
• 커스터마이저(Customizer)를 통한 클라이언트 생성 방식의 사용자 정의 가능

스타터

참고
스프링 AI 자동 구성, 스타터 모듈의 아티팩트 이름에 큰 변화가 있었습니다. 자세한 내용은 업그레이드 노트를 참조하세요.

표준 MCP 클라이언트

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

Webflux 클라이언트

WebFlux 스타터는 표준 스타터와 유사한 기능을 제공하지만, WebFlux 기반 SSE 전송 구현체를 사용합니다.

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

설정 속성 (Configuration Properties)

공통 속성 (Common Properties)

공통 속성은 다음과 같은 접두사로 시작합니다: spring.ai.mcp.client

속성	설명	기본값
enabled	MCP 클라이언트 활성화 여부	true
name	MCP 클라이언트 인스턴스의 이름 (호환성 확인 시 사용됨)	spring-ai-mcp-client
version	MCP 클라이언트 인스턴스의 버전	1.0.0
initialized	생성 시 클라이언트를 초기화할지 여부	true
request-timeout	MCP 클라이언트 요청의 타임아웃 시간	20s
type	클라이언트 유형 (SYNC 또는 ASYNC) – 혼용은 불가능	SYNC
root-change-notification	모든 클라이언트에 대해 루트 변경 알림 활성화 여부	true
toolcallback.enabled	Spring AI 툴 실행 프레임워크와의 MCP 툴 콜백 통합 활성화 여부	true

Stdio 전송 설정 속성 (Stdio Transport Properties)

Standard I/O 전송 방식에 대한 속성은 spring.ai.mcp.client.stdio 접두사를 사용합니다:

속성	설명	기본값
servers-configuration	MCP 서버 구성이 담긴 JSON 형식의 리소스	-
connections	이름이 지정된 stdio 연결 설정의 Map	-
connections.[name].command	MCP 서버를 실행할 명령어	-
connections.[name].args	명령어에 전달할 인자 목록	-
connections.[name].env	서버 프로세스 실행 시 사용할 환경 변수(Map 형태)	-

 

예시 구성:

spring:
  ai:
    mcp:
      client:
        stdio:
          root-change-notification: true
          connections:
            server1:
              command: /path/to/server
              args:
                - --port=8080
                - --mode=production
              env:
                API_KEY: your-api-key
                DEBUG: "true"

 

또한, Claude Desktop 형식의 외부 JSON 파일을 사용하여 stdio 연결을 구성할 수도 있습니다.

spring:
  ai:
    mcp:
      client:
        stdio:
          servers-configuration: classpath:mcp-servers.json

 

Claude Desktop 형식은 다음과 같은 형태입니다:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

 

현재 Claude Desktop 형식은 STDIO 연결 방식만 지원합니다.

SSE 전송 설정 속성 (SSE Transport Properties)

Server-Sent Events (SSE) 전송 방식에 대한 설정은 spring.ai.mcp.client.sse 접두사로 시작합니다.

속성	설명	기본값
connections	이름이 지정된 SSE 연결 설정들의 Map	-
connections.[name].url	MCP 서버와 SSE 통신을 위한 기본 URL 엔드포인트	-
connections.[name].sse-endpoint	연결에 사용할 SSE 엔드포인트 URL 접미사(suffix)	/sse

기능

동기/비동기 클라이언트 유형 (Sync/Async Client Types)

스타터는 두 가지 유형의 클라이언트를 지원합니다:

• 동기(Synchronous) 기본 클라이언트 유형으로, 블로킹 요청-응답 패턴에 적합합니다.
•  비동기(Asynchronous) 논블로킹 처리가 필요한 리액티브 애플리케이션에 적합하며, 다음과 같이 설정합니다: spring.ai.mcp.client.type=ASYNC

클라이언트 커스터마이징 (Client Customization)

Spring AI의 자동 구성은 콜백 인터페이스(Customizer)를 통해 MCP 클라이언트 사양을 유연하게 커스터마이징 할 수 있는 기능을 제공합니다.

 

자동 구성은 콜백 인터페이스를 통해 MCP 클라이언트 사양을 폭넓게 커스터마이징 할 수 있는 기능을 제공합니다.

이러한 커스터마이저를 사용하면 MCP 클라이언트의 요청 타임아웃, 이벤트 처리 방식, 메시지 처리 등 다양한 동작을 설정할 수 있습니다.

커스터마이징 타입

다음과 같은 커스터마이징 옵션을 사용할 수 있습니다: 

• 요청 구성(Request Configuration) – 사용자 지정 요청 타임아웃을 설정할 수 있습니다. 
• 커스텀 샘플링 핸들러(Custom Sampling Handlers) – 서버가 클라이언트를 통해 LLM으로부터 샘플링(완성 또는 생성)을 요청할 수 있는 표준화된 방식입니다. 이 흐름은 서버가 별도의 API 키 없이도 AI 기능을 활용할 수 있도록 하면서, 클라이언트가 모델 접근, 선택, 권한에 대한 제어권을 유지할 수 있게 해 줍니다.
• 파일 시스템(루트) 접근(File system (Roots) Access) – 클라이언트가 서버에 파일 시스템 루트를 노출할 수 있는 표준화된 방식입니다. 루트(Roots)는 서버가 파일 시스템 내에서 작업할 수 있는 범위를 정의하며, 서버는 지원 클라이언트로부터 루트 목록을 요청하고, 해당 목록이 변경되었을 때 알림을 받을 수 있습니다.
• 이벤트 핸들러(Event Handlers) – 특정 서버 이벤트가 발생했을 때 클라이언트 측에서 알림을 받을 수 있도록 하는 핸들러입니다:
  • 툴 변경 알림 – 사용 가능한 서버 툴 목록이 변경되었을 때
  • 리소스 변경 알림 – 사용 가능한 서버 리소스 목록이 변경되었을 때
  • 프롬프트 변경 알림 – 사용 가능한 서버 프롬프트 목록이 변경되었을 때
• 로깅 핸들러(Logging Handlers) – 서버가 구조화된 로그 메시지를 클라이언트로 전송할 수 있는 표준화된 방식입니다. 클라이언트는 최소 로그 수준을 설정하여 로깅의 상세 수준을 제어할 수 있습니다.

동기 클라이언트를 사용하는 경우에는 McpSyncClientCustomizer를, 비동기 클라이언트를 사용하는 경우에는 McpAsyncClientCustomizer를 구현하면 됩니다. 이는 애플리케이션의 필요에 따라 선택할 수 있습니다.

// 동기 방식
@Component
public class CustomMcpSyncClientCustomizer implements McpSyncClientCustomizer {
    @Override
    public void customize(String serverConfigurationName, McpClient.SyncSpec spec) {

        // 요청 타임아웃을 30초로 설정
        spec.requestTimeout(Duration.ofSeconds(30));

        // 이 클라이언트가 접근할 수 있는 파일 시스템 루트 경로 설정
        spec.roots(roots);

        // 메시지 생성 요청에 대한 샘플링 핸들러 설정
        spec.sampling((CreateMessageRequest messageRequest) -> {
            // 샘플링 처리 로직
            CreateMessageResult result = ...
            return result;
        });

        // 서버 툴 목록이 변경되었을 때 알림을 받을 소비자 설정
        spec.toolsChangeConsumer((List<McpSchema.Tool> tools) -> {
            // 툴 변경 처리
        });

        // 서버 리소스 목록이 변경되었을 때 알림을 받을 소비자 설정
        spec.resourcesChangeConsumer((List<McpSchema.Resource> resources) -> {
            // 리소스 변경 처리
        });

        // 서버 프롬프트 목록이 변경되었을 때 알림을 받을 소비자 설정
        spec.promptsChangeConsumer((List<McpSchema.Prompt> prompts) -> {
            // 프롬프트 변경 처리
        });

        // 서버에서 전달되는 로그 메시지를 처리할 소비자 설정
        spec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> {
            // 로그 메시지 처리
        });
    }
}

// 비동기 방식
import org.springframework.stereotype.Component;
import java.time.Duration;

@Component
public class CustomMcpAsyncClientCustomizer implements McpAsyncClientCustomizer {
    @Override
    public void customize(String serverConfigurationName, McpClient.AsyncSpec spec) {
        // 비동기 MCP 클라이언트의 요청 타임아웃을 30초로 설정
        spec.requestTimeout(Duration.ofSeconds(30));
    }
}

 

serverConfigurationName 파라미터는 커스터마이저가 적용되는 서버 구성의 이름이며, 해당 구성에 대해 MCP 클라이언트가 생성됩니다. MCP 클라이언트의 자동 구성은 애플리케이션 컨텍스트에서 발견된 모든 커스터마이저를 자동으로 감지하고 적용합니다.

 

전송 계층 지원

자동 구성은 여러 가지 전송 방식을 지원합니다: 

• 표준 입출력(Standard I/O, Stdio) (spring-ai-starter-mcp-client를 통해 활성화됨) 
• SSE over HTTP (spring-ai-starter-mcp-client를 통해 활성화됨) 
• SSE over WebFlux (spring-ai-starter-mcp-client-webflux를 통해 활성화됨)

Spring AI와의 통합

스타터는 Spring AI의 툴 실행 프레임워크와 통합되는 툴 콜백을 구성할 수 있으며, 이를 통해 MCP 툴을 AI 상호작용의 일부로 사용할 수 있습니다. 이 통합은 기본적으로 활성화되어 있으며, spring.ai.mcp.client.toolcallback.enabled=false 속성을 설정하여 비활성화할 수 있습니다.

예제 애플리케이션

• Brave Web Search Chatbot - Model Context Protocol을 사용하여 웹 검색 서버와 상호작용하는 챗봇 예제
• Default MCP Client Starter - spring-ai-starter-mcp-client 기본 MCP 클라이언트 Boot 스타터 사용 예제
• WebFlux MCP Client Starter - spring-ai-starter-mcp-client-webflux WebFlux 기반 MCP 클라이언트 Boot 스타터 사용 예제

추가 자료

• Spring AI 문서
• Model Context Protocol 명세서
• Spring Boot 자동 구성 문서

---

MCP 서버 Boot 스타터

표준 스타터는 STDIO(프로세스 내) 및/또는 SSE(원격) 전송 방식을 통해 하나 이상의 MCP 서버에 동시에 연결할 수 있습니다. SSE 연결은 HttpClient 기반 전송 구현체를 사용합니다. 각 MCP 서버에 대한 연결마다 새로운 MCP 클라이언트 인스턴스가 생성됩니다. 

 

사용자는 동기(SYNC) 또는 비동기(ASYNC) MCP 클라이언트 중 하나만 선택할 수 있으며, 동기와 비동기를 혼용할 수는 없습니다. 운영 환경에서는 spring-ai-starter-mcp-client-webflux를 사용한 WebFlux 기반 SSE 연결을 권장합니다.

 

MCP 서버 부트 스타터는 다음 기능을 제공합니다: 

• MCP 서버 구성 요소의 자동 설정 
• 동기 및 비동기 운영 모드 모두에 대한 지원 
• 다양한 전송 계층 옵션 지원 
• 유연한 툴, 리소스, 프롬프트 명세 구성 
• 변경 사항에 대한 알림 기능

스타터

참고
스프링 AI 자동 구성, 스타터 모듈의 아티팩트 이름에 큰 변화가 있었습니다. 자세한 내용은 업그레이드 노트를 참고하시기 바랍니다.

 

전송 방식 요구사항에 따라 아래 스타터 중 하나를 선택하세요:

표준 MCP 서버

STDIO 서버 전송 방식을 사용하는 전체 MCP 서버 기능을 지원합니다.

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
</dependency>

• 커맨드라인 및 데스크톱 도구에 적합
• 추가적인 웹 관련 의존성이 필요하지 않음

이 스타터는 McpServerAutoConfiguration 자동 구성을 활성화하며, 이는 다음 역할을 수행합니다: 

• 기본 서버 구성 요소 설정
• 툴, 리소스, 프롬프트 명세 처리
• 서버 기능 및 변경 알림 관리
• 동기 및 비동기 서버 구현 모두 제공

WebMVC 서버 전송

Spring MVC 기반의 SSE(Server-Sent Events) 서버 전송 방식을 사용하며, 선택적으로 STDIO 전송도 지원하는 전체 MCP 서버 기능을 제공합니다.

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

 

이 스타터는 McpWebMvcServerAutoConfiguration 및 McpServerAutoConfiguration 자동 구성을 활성화하여 다음 기능을 제공합니다:

• Spring MVC를 기반으로 한 HTTP 전송 지원 (WebMvcSseServerTransportProvider)
• 자동으로 구성되는 SSE 엔드포인트
• 선택적 STDIO 전송 지원 (spring.ai.mcp.server.stdio=true로 설정 시 활성화)
• spring-boot-starter-web 및 mcp-spring-webmvc 의존성 포함

WebFlux 서버 전송

Spring WebFlux 기반의 SSE(Server-Sent Events) 서버 전송 방식을 사용하며, 선택적으로 STDIO 전송도 지원하는 전체 MCP 서버 기능을 제공합니다.

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

 

이 스타터는 McpWebFluxServerAutoConfiguration 및 McpServerAutoConfiguration 자동 구성을 활성화하여 다음 기능을 제공합니다: 

• Spring WebFlux를 활용한 리액티브 전송 지원 (WebFluxSseServerTransportProvider) 
• 자동으로 구성되는 리액티브 SSE 엔드포인트 
• 선택적 STDIO 전송 지원 (spring.ai.mcp.server.stdio=true로 설정 시 활성화) 
• spring-boot-starter-webflux 및 mcp-spring-webflux 의존성 포함

설정 속성 (Configuration Properties)

모든 속성은 spring.ai.mcp.server 접두사가 붙습니다:

속성	설명	기본값
enabled	MCP 서버를 활성화/비활성화합니다.	true
stdio	stdio 전송 방식을 활성화/비활성화합니다.	false
name	서버 식별을 위한 서버 이름입니다.	mcp-server
version	서버 버전입니다.	1.0.0
instructions	클라이언트가 이 서버와 상호작용하는 방법에 대한 선택적 안내입니다.	null
type	서버 유형입니다 (SYNC 또는 ASYNC).	SYNC
capabilities.resource	리소스 기능을 활성화/비활성화합니다.	true
capabilities.tool	툴 기능을 활성화/비활성화합니다.	true
capabilities.prompt	프롬프트 기능을 활성화/비활성화합니다.	true
capabilities.completion	completion 기능을 활성화/비활성화합니다.	true
resource-change-notification	리소스 변경 알림을 활성화합니다.	true
prompt-change-notification	프롬프트 변경 알림을 활성화합니다.	true
tool-change-notification	툴 변경 알림을 활성화합니다.	true
tool-response-mime-type	(선택 사항) 툴 이름별 응답 MIME 타입을 지정합니다.예: spring.ai.mcp.server.tool-response-mime-type.generateImage=image/png는 generateImage() 툴 이름에 image/png MIME 타입을 연결합니다.	-
sse-message-endpoint	클라이언트가 메시지를 전송하는 데 사용할 웹 전송용 SSE 메시지 엔드포인트 경로입니다.	/mcp/message
sse-endpoint	웹 전송용 SSE 엔드포인트 경로입니다.	/sse
base-url	선택적 URL 접두사입니다. 예: base-url=/api/v1로 설정하면 클라이언트는 /api/v1/sse 및 /api/v1/mcp/message에 접근합니다.	-
request-timeout	서버 응답을 기다리는 시간입니다. 이 시간 이후에는 툴 호출, 리소스 접근, 프롬프트 작업을 포함한 모든 요청이 타임아웃됩니다.	20초

동기/비동기 서버 유형 

• 동기 서버(Synchronous Server) – 기본 서버 유형으로, McpSyncServer를 사용하여 구현됩니다. 애플리케이션에서 단순한 요청-응답 패턴에 적합하도록 설계되어 있습니다. 이 서버 유형을 활성화하려면 설정에서 spring.ai.mcp.server.type=SYNC로 지정하십시오. 활성화되면 동기 툴 명세 구성을 자동으로 처리합니다. 
• 비동기 서버(Asynchronous Server) – 비동기 서버 구현은 McpAsyncServer를 사용하며, 논블로킹 작업에 최적화되어 있습니다. 이 서버 유형을 활성화하려면 애플리케이션 설정에서 spring.ai.mcp.server.type=ASYNC로 지정하십시오. 해당 서버 유형은 Project Reactor 지원을 포함한 비동기 툴 명세 구성을 자동으로 설정합니다.

서버 기능 (Server Capabilities) 

MCP 서버는 네 가지 주요 기능 유형을 지원하며, 각각 개별적으로 활성화하거나 비활성화할 수 있습니다: 

• 툴(도구) – spring.ai.mcp.server.capabilities.tool=true|false로 툴 기능을 활성화/비활성화합니다.
• 리소스 – spring.ai.mcp.server.capabilities.resource=true|false로 리소스 기능을 활성화/비활성화합니다.
• 프롬프트 – spring.ai.mcp.server.capabilities.prompt=true|false로 프롬프트 기능을 활성화/비활성화합니다.
• 완성(Completions) – spring.ai.mcp.server.capabilities.completion=true|false로 완성 기능을 활성화/비활성화합니다.

 

모든 기능은 기본적으로 활성화되어 있습니다. 기능을 비활성화하면 해당 기능이 서버에 등록되지 않으며, 클라이언트에 노출되지 않습니다.

전송 옵션 (Transport Options)

MCP 서버는 세 가지 전송 방식을 지원하며, 각 방식은 전용 스타터와 함께 사용됩니다:

• 표준 입출력 (STDIO) – spring-ai-starter-mcp-server
• Spring MVC (Server-Sent Events) – spring-ai-starter-mcp-server-webmvc
• Spring WebFlux (Reactive SSE) – spring-ai-starter-mcp-server-webflux

기능 및 제공 항목 (Features and Capabilities) 

MCP 서버 부트 스타터는 서버가 클라이언트에 툴, 리소스, 프롬프트를 제공할 수 있도록 합니다. 서버 유형(SYNC 또는 ASYNC)에 따라, Spring 빈으로 등록된 사용자 정의 기능 핸들러를 자동으로 동기/비동기 명세로 변환합니다.

툴 (Tools)

서버가 언어 모델에 의해 호출될 수 있는 툴을 노출할 수 있도록 합니다. MCP 서버 부트 스타터는 다음을 제공합니다: 

• 툴 변경 알림 지원 
• 서버 유형(SYNC 또는 ASYNC)에 따라 Spring AI 툴을 동기/비동기 명세로 자동 변환 
• Spring 빈을 통한 자동 툴 명세화

@Bean
public ToolCallbackProvider myTools(...) {
    List<ToolCallback> tools = ...
    return ToolCallbackProvider.from(tools);
}

 

또는 저수준 API를 사용할 수도 있습니다:

@Bean
public List<McpServerFeatures.SyncToolSpecification> myTools(...) {
    List<McpServerFeatures.SyncToolSpecification> tools = ...
    return tools;
}

 

자동 구성은 다음으로부터 모든 ToolCallback을 자동으로 감지하고 등록합니다:

• 개별 ToolCallback 빈
• ToolCallback 빈 목록
• ToolCallbackProvider 빈

툴은 이름 기준으로 중복 제거되며, 각 툴 이름의 첫 번째 항목이 사용됩니다.

 

툴 컨텍스트 지원 (Tool Context Support)

툴 호출 시 컨텍스트 정보를 전달할 수 있도록 ToolContext가 지원됩니다. 이 컨텍스트에는 exchange 키 아래에 McpSyncServerExchange 인스턴스가 포함되어 있으며, McpToolUtils.getMcpExchange(toolContext)를 통해 접근할 수 있습니다.

exchange.loggingNotification(…​) 및 exchange.createMessage(…​)를 사용하는 예제를 참고하세요.

리소스 관리

서버가 클라이언트에 리소스를 노출할 수 있도록 표준화된 방식을 제공합니다.

• 정적 및 동적 리소스 명세
• 선택적 변경 알림
• 리소스 템플릿 지원
• 동기/비동기 리소스 명세 간 자동 변환
• Spring 빈을 통한 자동 리소스 명세화

@Bean
public List<McpServerFeatures.SyncResourceSpecification> myResources(...) {
    var systemInfoResource = new McpSchema.Resource(...);
    var resourceSpecification = new McpServerFeatures.SyncResourceSpecification(systemInfoResource, (exchange, request) -> {
        try {
            var systemInfo = Map.of(...);
            String jsonContent = new ObjectMapper().writeValueAsString(systemInfo);
            return new McpSchema.ReadResourceResult(
                    List.of(new McpSchema.TextResourceContents(request.uri(), "application/json", jsonContent)));
        }
        catch (Exception e) {
            throw new RuntimeException("Failed to generate system info", e);
        }
    });

    return List.of(resourceSpecification);
}

프롬프트 관리

서버가 클라이언트에 프롬프트 템플릿을 노출할 수 있도록 표준화된 방식을 제공합니다.

• 변경 알림 지원
• 템플릿 버전 관리
• 동기/비동기 프롬프트 명세 간 자동 변환
• Spring 빈을 통한 자동 프롬프트 명세화

@Bean
public List<McpServerFeatures.SyncPromptSpecification> myPrompts() {
    var prompt = new McpSchema.Prompt("greeting", "A friendly greeting prompt",
        List.of(new McpSchema.PromptArgument("name", "The name to greet", true)));

    var promptSpecification = new McpServerFeatures.SyncPromptSpecification(prompt, (exchange, getPromptRequest) -> {
        String nameArgument = (String) getPromptRequest.arguments().get("name");
        if (nameArgument == null) { nameArgument = "friend"; }
        var userMessage = new PromptMessage(Role.USER, new TextContent("Hello " + nameArgument + "! How can I assist you today?"));
        return new GetPromptResult("A personalized greeting message", List.of(userMessage));
    });

    return List.of(promptSpecification);
}

완성(Completion) 관리

서버가 클라이언트에 텍스트 생성(completion) 기능을 노출할 수 있도록 표준화된 방식을 제공합니다.

• 동기 및 비동기 completion 명세 지원
• Spring 빈을 통한 자동 등록

@Bean
public List<McpServerFeatures.SyncCompletionSpecification> myCompletions() {
    // "code-completion"이라는 이름의 동기형 completion 기능 정의
    var completion = new McpServerFeatures.SyncCompletionSpecification(
        "code-completion", // 기능 이름
        "Provides code completion suggestions", // 기능 설명
        (exchange, request) -> {
            // 텍스트 자동완성(completion) 결과 반환 구현
            return new McpSchema.CompletionResult(List.of(
                new McpSchema.Completion("suggestion1", "First suggestion"),
                new McpSchema.Completion("suggestion2", "Second suggestion")
            ));
        }
    );

    return List.of(completion); // 이 기능을 빈으로 등록
}

루트 변경 소비자 (Root Change Consumers)

루트가 변경되면, listChanged를 지원하는 클라이언트는 루트 변경 알림(Root Change notification)을 전송합니다.

• 루트 변경 감지를 위한 모니터링 지원
• 리액티브 애플리케이션을 위한 비동기 소비자(async consumer)로의 자동 변환
• Spring 빈을 통한 선택적 등록 가능

@Bean
public BiConsumer<McpSyncServerExchange, List<McpSchema.Root>> rootsChangeHandler() {
    return (exchange, roots) -> {
        logger.info("Registering root resources: {}", roots);
    };
}

사용 예

표준 STDIO 서버 구성 (Standard STDIO Server Configuration)

# spring-ai-starter-mcp-server 사용
spring:
  ai:
    mcp:
      server:
        name: stdio-mcp-server
        version: 1.0.0
        type: SYNC

WebMVC 서버 구성

# spring-ai-starter-mcp-server-webmvc 사용
spring:
  ai:
    mcp:
      server:
        name: webmvc-mcp-server
        version: 1.0.0
        type: SYNC
        instructions: "This server provides weather information tools and resources"
        sse-message-endpoint: /mcp/messages
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true

WebFlux 서버 구성

# spring-ai-starter-mcp-server-webflux 사용
spring:
  ai:
    mcp:
      server:
        name: webflux-mcp-server
        version: 1.0.0
        type: ASYNC  # Recommended for reactive applications
        instructions: "This reactive server provides weather information tools and resources"
        sse-message-endpoint: /mcp/messages
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true

MCP 서버가 포함된 Spring Boot 애플리케이션 생성

@Service
public class WeatherService {

    @Tool(description = "Get weather information by city name")
    public String getWeather(String cityName) {
        // 구현
    }
}

@SpringBootApplication
public class McpServerApplication {

    private static final Logger logger = LoggerFactory.getLogger(McpServerApplication.class);

    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }

	@Bean
	public ToolCallbackProvider weatherTools(WeatherService weatherService) {
		return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
	}
}

 

자동 구성은 ToolCallback들을 MCP 툴로 자동 등록합니다. 여러 개의 빈이 ToolCallback을 생성할 수 있으며, 자동 구성은 이들을 병합하여 처리합니다.

예제 애플리케이션

• 날씨 서버 (WebFlux) – WebFlux 전송 방식을 사용하는 Spring AI MCP 서버 부트 스타터
• 날씨 서버 (STDIO) – STDIO 전송 방식을 사용하는 Spring AI MCP 서버 부트 스타터
• 날씨 서버 수동 구성 – 자동 구성을 사용하지 않고 Java SDK를 통해 서버를 수동으로 설정하는 Spring AI MCP 서버 부트 스타터

추가 자료

• Spring AI 문서
• Model Context Protocol 명세서
• Spring Boot 자동 구성 문서

---

MCP 유틸리티

MCP 유틸리티(MCP Utilities)는 Spring AI 애플리케이션에 Model Context Protocol(MCP)을 통합하기 위한 기반 지원 기능을 제공합니다. 이 유틸리티는 Spring AI의 툴 시스템과 MCP 서버 간의 원활한 통신을 가능하게 하며, 동기 및 비동기 작업을 모두 지원합니다. 일반적으로 프로그래밍 방식의 MCP 클라이언트/서버 구성 및 상호작용에 사용되며, 보다 간편한 설정을 원할 경우 Boot 스타터 사용을 권장합니다.

ToolCallback 유틸리티

Tool Callback 어댑터

MCP 툴을 Spring AI의 툴 인터페이스에 어댑팅(연결)하여, 동기(synchronous) 및 비동기(asynchronous) 실행을 모두 지원합니다.

// 동기 방식
McpSyncClient mcpClient = // MCP 클라이언트 인스턴스 획득
Tool mcpTool = // MCP 툴 정의 획득
ToolCallback callback = new SyncMcpToolCallback(mcpClient, mcpTool);

// Spring AI 인터페이스를 통해 MCP 툴 사용
ToolDefinition definition = callback.getToolDefinition();
String result = callback.call("{\"param\": \"value\"}");

// 비동기 방식
McpAsyncClient mcpClient = // MCP 클라이언트 인스턴스 획득
Tool mcpTool = // MCP 툴 정의 획득
ToolCallback callback = new AsyncMcpToolCallback(mcpClient, mcpTool);

// Spring AI 인터페이스를 통해 MCP 툴 사용
ToolDefinition definition = callback.getToolDefinition();
String result = callback.call("{\"param\": \"value\"}");

Tool Callback 제공자

MCP 클라이언트를 통해 MCP 툴을 탐색(discover)하고 Spring AI에서 사용할 수 있도록 제공합니다.

// 동기 방식
McpSyncClient mcpClient = // MCP 클라이언트 인스턴스 획득
ToolCallbackProvider provider = new SyncMcpToolCallbackProvider(mcpClient);

// 사용 가능한 모든 MCP 툴 획득
ToolCallback[] tools = provider.getToolCallbacks();

// 비동기 방식
McpAsyncClient mcpClient = // MCP 클라이언트 인스턴스 획득
ToolCallbackProvider provider = new AsyncMcpToolCallbackProvider(mcpClient);

// 사용 가능한 모든 MCP 툴 획득
ToolCallback[] tools = provider.getToolCallbacks();

 

여러 클라이언트를 위한 경우:

List<McpAsyncClient> clients = // 클라이언트 목록 획득
Flux<ToolCallback> callbacks = AsyncMcpToolCallbackProvider.asyncToolCallbacks(clients);

McpToolUtils

ToolCallbacks를 ToolSpecifications로 변환

Spring AI 툴 콜백을 MCP 툴 명세로 변환하기:

// 동기 방식
List<ToolCallback> toolCallbacks = // 툴 콜백 목록 획득
List<SyncToolSpecifications> syncToolSpecs = McpToolUtils.toSyncToolSpecifications(toolCallbacks);

// 비동기 방식
List<ToolCallback> toolCallbacks = // 툴 콜백 목록 획득
List<AsyncToolSpecification> asyncToolSpecifications = McpToolUtils.toAsyncToolSpecifications(toolCallbacks);

 

그런 다음 McpServer.SyncSpecification을 사용하여 툴 명세를 등록할 수 있습니다: (비동기는 McpServer.AsyncSpecification)

// 동기 방식
McpServer.SyncSpecification syncSpec = ...
syncSpec.tools(syncToolSpecs);

// 비동기 방식
McpServer.AsyncSpecification asyncSpec = ...
asyncSpec.tools(asyncToolSpecifications);

MCP 클라이언트에서 ToolCallback 가져오기

// 동기 방식
List<McpSyncClient> syncClients = // 동기 클라이언트 목록 획득
List<ToolCallback> syncCallbacks = McpToolUtils.getToolCallbacksFromSyncClients(syncClients);

// 비동기 방식
List<McpAsyncClient> asyncClients = // 비동기 클라이언트 목록 획득
List<ToolCallback> asyncCallbacks = McpToolUtils.getToolCallbacksFromAsyncClients(asyncClients);

네이티브 이미지 지원 (Native Image Support)

McpHints 클래스는 MCP 스키마 클래스들을 위한 GraalVM 네이티브 이미지 힌트를 제공합니다. 이 클래스는 네이티브 이미지를 빌드할 때 MCP 스키마 클래스에 필요한 모든 리플렉션 힌트를 자동으로 등록합니다.

Reference

• Spring AI : Model Context Protocl (MCP)
• Spring AI : MCP Client Boot Starters
• Spring AI : MCP Server Boot Starters
• Spring AI : MCP Utilities