MCP 어노테이션

MCP 어노테이션 (MCP Annotations)

Spring AI MCP Annotations 모듈은 Java에서 Model Context Protocol (MCP) 서버와 클라이언트를 위한 어노테이션 기반 메서드 처리를 제공해요. Java 어노테이션을 활용한 선언적(declarative) 방식으로 MCP 서버 메서드와 클라이언트 핸들러를 깔끔하게 만들고 등록할 수 있어요. 이 글에서는 아키텍처와 주요 어노테이션, 빠른 예제까지 살펴볼게요.

출처: 문서

본문

MCP 어노테이션 (MCP Annotations)

Spring AI MCP Annotations 모듈은 Java에서 Model Context Protocol (MCP) 서버와 클라이언트를 위한 어노테이션 기반 메서드 처리를 제공해요. Java 어노테이션을 사용한 깔끔하고 선언적인 접근 방식으로 MCP 서버 메서드와 클라이언트 핸들러의 생성·등록을 단순화해요.

 MCP Annotations는 개발자가 선언적 어노테이션을 사용해 MCP 작업 핸들러를 생성·등록할 수 있게 해 줘요.
이 방식은 보일러플레이트 코드를 줄이고 유지보수성을 높여 MCP 서버·클라이언트 기능 구현을 단순화해요.

이 라이브러리는 MCP Java SDK 위에 구축되어, MCP 서버와 클라이언트를 구현하기 위한 더 높은 수준의 어노테이션 기반 프로그래밍 모델을 제공해요.

아키텍처 (Architecture)

MCP Annotations 모듈은 다음으로 구성돼요:

서버 어노테이션 (Server Annotations)

MCP 서버의 경우 다음 어노테이션이 제공돼요:

  • @McpTool - 자동 JSON 스키마 생성으로 MCP 도구를 구현해요.
  • @McpResource - URI 템플릿을 통해 리소스에 접근을 제공해요.
  • @McpPrompt - 프롬프트 메시지를 생성해요.
  • @McpComplete - 자동 완성 기능을 제공해요.

클라이언트 어노테이션 (Client Annotations)

MCP 클라이언트의 경우 다음 어노테이션이 제공돼요:

  • @McpLogging - 로깅 메시지 알림을 처리해요.
  • @McpSampling - 샘플링 요청을 처리해요.
  • @McpElicitation - 추가 정보 수집을 위한 elicit 요청을 처리해요.
  • @McpProgress - 장기 실행 작업 중 진행 알림을 처리해요.
  • @McpToolListChanged - 도구 목록 변경 알림을 처리해요.
  • @McpResourceListChanged - 리소스 목록 변경 알림을 처리해요.
  • @McpPromptListChanged - 프롬프트 목록 변경 알림을 처리해요.

특수 파라미터와 어노테이션 (Special Parameters and Annotations)

  • McpSyncRequestContext - 동기 작업용 특수 파라미터 타입. 원래 요청, 서버 exchange(상태 유지 작업), 전송 컨텍스트(상태 없는 작업), 로깅·진행·샘플링·elicitation·roots 접근을 위한 편리한 메서드를 포함한 MCP 요청 컨텍스트 접근용 통합 인터페이스를 제공해요. 이 파라미터는 자동 주입되며 JSON 스키마 생성에서 제외돼요. Complete, Prompt, Resource, Tool 메서드에서 지원돼요.
  • McpAsyncRequestContext - 비동기 작업용 특수 파라미터 타입. McpSyncRequestContext와 동일한 통합 인터페이스를 제공하지만 반응형(Mono 기반) 반환 타입을 가져요. 이 파라미터는 자동 주입되며 JSON 스키마 생성에서 제외돼요. Complete, Prompt, Resource, Tool 메서드에서 지원돼요.
  • McpTransportContext - 상태 없는 작업용 특수 파라미터 타입. 전체 서버 exchange 기능 없이 전송 수준 컨텍스트에 대한 가벼운 접근을 제공해요. 이 파라미터는 자동 주입되며 JSON 스키마 생성에서 제외돼요.
  • @McpProgressToken - 요청에서 진행 토큰을 받을 메서드 파라미터를 표시해요. 이 파라미터는 자동 주입되며 생성된 JSON 스키마에서 제외돼요. 참고: McpSyncRequestContext나 McpAsyncRequestContext를 사용할 때는 이 어노테이션 대신 ctx.request().progressToken()으로 진행 토큰에 접근할 수 있어요.
  • McpMeta - MCP 요청, 알림, 결과의 메타데이터에 접근을 제공하는 특수 파라미터 타입. 이 파라미터는 자동 주입되며 파라미터 개수 제한과 JSON 스키마 생성에서 제외돼요. 참고: McpSyncRequestContext나 McpAsyncRequestContext를 사용할 때는 ctx.requestMeta()로 메타데이터를 얻을 수 있어요.
  • MetaProvider - 도구, 프롬프트, 리소스 선언을 위한 _meta 필드 데이터를 공급하기 위해 구현하는 인터페이스. @McpTool, @McpPrompt, @McpResource의 metaProvider 속성으로 참조돼요.

시작하기 (Getting Started)

의존성 (Dependencies)

프로젝트에 MCP annotations 의존성을 추가하세요:

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

MCP 어노테이션은 MCP Boot Starters 중 하나를 사용하면 자동으로 포함돼요:

  • spring-ai-starter-mcp-client
  • spring-ai-starter-mcp-client-webflux
  • spring-ai-starter-mcp-server
  • spring-ai-starter-mcp-server-webflux
  • spring-ai-starter-mcp-server-webmvc

구성 (Configuration)

MCP Boot Starters를 사용하면 어노테이션 스캔이 기본적으로 활성화돼요. 다음 프로퍼티로 스캔 동작을 구성할 수 있어요:

클라이언트 어노테이션 스캐너 (Client Annotation Scanner)

spring:
  ai:
    mcp:
      client:
        annotation-scanner:
          enabled: true  # Enable/disable annotation scanning

서버 어노테이션 스캐너 (Server Annotation Scanner)

spring:
  ai:
    mcp:
      server:
        annotation-scanner:
          enabled: true  # Enable/disable annotation scanning

빠른 예제 (Quick Example)

MCP 어노테이션을 사용해 계산기 도구를 만드는 간단한 예제예요:

@Component
public class CalculatorTools {

    @McpTool(name = "add", description = "Add two numbers together")
    public int add(
            @McpToolParam(description = "First number", required = true) int a,
            @McpToolParam(description = "Second number", required = true) int b) {
        return a + b;
    }

    @McpTool(name = "multiply", description = "Multiply two numbers")
    public double multiply(
            @McpToolParam(description = "First number", required = true) double x,
            @McpToolParam(description = "Second number", required = true) double y) {
        return x * y;
    }
}

그리고 로깅을 위한 간단한 클라이언트 핸들러예요:

@Component
public class LoggingHandler {

    @McpLogging(clients = "my-server")
    public void handleLoggingMessage(LoggingMessageNotification notification) {
        System.out.println("Received log: " + notification.level() +
                          " - " + notification.data());
    }
}

Spring Boot 자동 설정을 사용하면 이렇게 어노테이션된 빈들이 자동으로 감지되어 MCP 서버나 클라이언트에 등록돼요.

문서 (Documentation)

추가 자료 (Additional Resources)

더 알아보기 (Learn more)