MCP 서버 Boot Starter

MCP 서버 Boot Starter (MCP Server Boot Starter)

Model Context Protocol (MCP) 서버는 표준화된 프로토콜 인터페이스를 통해 AI 애플리케이션에 특정 기능을 노출하는 프로그램이에요. Spring AI MCP Server Boot Starters는 Spring Boot 애플리케이션에서 MCP 서버를 설정하기 위한 자동 구성을 제공해요. 여러 프로토콜과 전송을 지원하므로 원하는 배포 방식에 맞춰 서버를 세울 수 있어요.

출처: 문서

본문

MCP 서버 Boot Starter (MCP Server Boot Starter)

Model Context Protocol (MCP) 서버는 표준화된 프로토콜 인터페이스를 통해 AI 애플리케이션에 특정 기능을 노출하는 프로그램이에요. 각 서버는 특정 도메인에 초점을 맞춘 기능을 제공해요.

Spring AI MCP Server Boot Starters는 Spring Boot 애플리케이션에서 MCP 서버를 설정하기 위한 자동 구성을 제공해요. MCP 서버 기능을 Spring Boot의 자동 구성 시스템과 원활하게 통합할 수 있게 해 줘요.

MCP Server Boot Starters는 다음을 제공해요:

• 도구, 리소스, 프롬프트를 포함한 MCP 서버 컴포넌트의 자동 구성
• STDIO, SSE, Streamable-HTTP, stateless 서버를 포함한 다양한 MCP 프로토콜 버전 지원
• 동기·비동기 운영 모드 모두 지원
• 여러 전송 계층 옵션
• 유연한 도구, 리소스, 프롬프트 명세
• 변경 알림 기능
• 자동 빈 스캔·등록을 통한 어노테이션 기반 서버 개발

참고: HTTP 기반 서버 전송(SSE, Streamable-HTTP, Stateless)은 기본적으로 인증되지 않은 JSON-RPC 엔드포인트를 노출해요. starters는 자체적으로 어떤 인증이나 권한 부여도 적용하지 않으므로, 엔드포인트에 도달할 수 있는 모든 클라이언트가 등록된 모든 도구·리소스·프롬프트를 나열하고 호출할 수 있어요. MCP 서버를 localhost 밖으로 노출하기 전에 반드시 그 앞에 보안 경계를 배치해야 해요. 자세한 내용은 Securing the MCP Server를 참고하세요.

이는 프로세스 내에서 실행되고 네트워크로 접근할 수 없는 STDIO 전송에는 적용되지 않아요.

MCP 서버 Boot Starters

MCP 서버는 여러 프로토콜과 전송 메커니즘을 지원해요. 전용 starter와 올바른 spring.ai.mcp.server.protocol 프로퍼티를 사용해 서버를 구성하세요:

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 _(2.0.0부터 deprecated, STREAMABLE 사용)	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 WebMVC	spring-ai-starter-mcp-server-webmvc	spring.ai.mcp.server.protocol=STATELESS

WebFlux (리액티브)

서버 타입 (Server Type)	의존성 (Dependency)	프로퍼티 (Property)
SSE WebFlux _(2.0.0부터 deprecated, STREAMABLE 사용)	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 WebFlux	spring-ai-starter-mcp-server-webflux	spring.ai.mcp.server.protocol=STATELESS

서버 기능 (Server Capabilities)

서버와 전송 타입에 따라 MCP 서버는 다양한 기능을 지원할 수 있어요, 예를 들어:

• 도구 (Tools) - 언어 모델이 호출할 수 있는 도구를 서버가 노출할 수 있게 해 줘요.
• 리소스 (Resources) - 서버가 클라이언트에 리소스를 노출하는 표준화된 방법을 제공해요.
• 프롬프트 (Prompts) - 서버가 클라이언트에 프롬프트 템플릿을 노출하는 표준화된 방법을 제공해요.
• 유틸리티/완성 (Utility/Completions) - 서버가 프롬프트와 리소스 URI에 대한 인자 자동 완성 제안을 제공하는 표준화된 방법.
• 유틸리티/로깅 (Utility/Logging) - 서버가 구조화된 로그 메시지를 클라이언트에 보내는 표준화된 방법.
• 유틸리티/진행 (Utility/Progress) - 알림 메시지를 통한 장기 실행 작업의 선택적 진행 추적.
• 유틸리티/핑 (Utility/Ping) - 서버가 상태를 보고하는 선택적 헬스 체크 메커니즘.

모든 기능은 기본적으로 활성화돼 있어요. 기능을 비활성화하면 서버가 해당 기능을 등록하고 클라이언트에 노출하는 것을 막게 돼요.

서버 프로토콜 (Server Protocols)

MCP는 여러 프로토콜 타입을 제공해요:

• STDIO - 프로세스 내(예: 서버가 호스트 애플리케이션 안에서 실행) 프로토콜. 통신은 표준 입력과 표준 출력을 통해 이루어져요. STDIO를 활성화하려면 spring.ai.mcp.server.stdio=true로 설정하세요.
• SSE - 실시간 업데이트를 위한 Server-sent events 프로토콜. 서버는 여러 클라이언트 연결을 처리할 수 있는 독립 프로세스로 동작해요.
• Streamable-HTTP - Streamable HTTP 전송은 MCP 서버가 HTTP POST와 GET 요청을 사용해 여러 클라이언트 연결을 처리할 수 있는 독립 프로세스로 동작하게 해 주고, 여러 서버 메시지에 대한 선택적 Server-Sent Events (SSE) 스트리밍을 지원해요. SSE 전송을 대체해요. STREAMABLE 프로토콜을 활성화하려면 spring.ai.mcp.server.protocol=STREAMABLE로 설정하세요.
• Stateless - 상태 없는 MCP 서버는 요청 간에 세션 상태를 유지하지 않는 단순화된 배포를 위해 설계됐어요. 마이크로서비스 아키텍처와 클라우드 네이티브 배포에 이상적이에요. STATELESS 프로토콜을 활성화하려면 spring.ai.mcp.server.protocol=STATELESS로 설정하세요.

MCP 서버 보안 (Securing the MCP Server)

MCP 서버 전송은 의도적으로 인증과 무관(authentication-agnostic)해요: 자동 설정은 엔드포인트를 연결해 주지만 인증이나 권한 부여를 강제하지는 않아요.

다른 Spring 웹 엔드포인트와 마찬가지로 HTTP 기반 MCP 서버(SSE, Streamable-HTTP, Stateless)를 보호하는 것은 그 앞에 추가하는 전용 보안 계층의 책임이에요 — 전송이 제공하지 않아요. 보안 라이브러리의 예로는 Spring Security와 MCP Security가 있어요.

참고: 기본 구성에서는 MCP 엔드포인트(POST /mcp 기본값)가 모든 요청을 수락하므로, 네트워크로 접근 가능한 모든 클라이언트가 자격 증명 없이 등록된 도구·리소스·프롬프트를 열거하고 호출할 수 있어요. 도구·리소스·프롬프트의 등록을 곧 노출을 결정하는 것으로 취급하고, localhost 밖에 배포하기 전에 엔드포인트를 보호하세요.

동기/비동기 서버 API 옵션 (Sync/Async Server API Options)

MCP Server API는 명령형(즉 동기)과 반응형(예: 비동기) 프로그래밍 모델을 모두 지원해요.

• 동기 서버 (Synchronous Server) - McpSyncServer로 구현된 기본 서버 타입. 애플리케이션의 간단한 요청-응답 패턴을 위해 설계됐어요. 활성화하려면 구성에서 spring.ai.mcp.server.type=SYNC로 설정하세요. 활성화되면 동기 도구 명세 구성을 자동으로 처리해요. 참고: SYNC 서버는 동기 MCP 어노테이션 메서드만 등록해요. 비동기 메서드는 무시돼요.
• 비동기 서버 (Asynchronous Server) - 비동기 서버 구현은 McpAsyncServer를 사용하며 블로킹되지 않는 연산에 최적화됐어요. 활성화하려면 애플리케이션을 spring.ai.mcp.server.type=ASYNC로 구성하세요. 이 서버 타입은 내장 Project Reactor 지원과 함께 비동기 도구 명세를 자동으로 설정해요. 참고: ASYNC 서버는 비동기 MCP 어노테이션 메서드만 등록해요. 동기 메서드는 무시돼요.

MCP 서버 어노테이션 (MCP Server Annotations)

MCP Server Boot Starters는 어노테이션 기반 서버 개발에 대한 포괄적인 지원을 제공해서, 수동 구성 대신 선언적 Java 어노테이션으로 MCP 서버를 만들 수 있게 해 줘요.

핵심 어노테이션 (Key Annotations)

• @McpTool - 자동 JSON 스키마 생성으로 메서드를 MCP 도구로 표시
• @McpResource - URI 템플릿을 통해 리소스 접근 제공
• @McpPrompt - AI 상호작용용 프롬프트 메시지 생성
• @McpComplete - 프롬프트용 자동 완성 기능 제공

특수 파라미터 (Special Parameters)

어노테이션 시스템은 추가 컨텍스트를 제공하는 특수 파라미터 타입을 지원해요:

• McpMeta - MCP 요청에서 메타데이터 접근
• @McpProgressToken - 장기 실행 작업용 진행 토큰 수신
• McpSyncServerExchange/McpAsyncServerExchange - 고급 작업을 위한 전체 서버 컨텍스트
• McpTransportContext - 상태 없는 작업용 가벼운 컨텍스트
• CallToolRequest - 유연한 도구를 위한 동적 스키마 지원

간단한 예제 (Simple Example)

@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;
    }

    @McpResource(uri = "config://{key}", name = "Configuration")
    public String getConfig(String key) {
        return configData.get(key);
    }
}

McpTransportContext에 데이터 추가 (Adding data to McpTransportContext)

기본적으로 McpTransportContext는 비어 있어요 (McpTransportContext.EMPTY). 이는 MCP 서버를 전송에 무관하게 유지하기 위한 설계예요.

도구에 전송 특정 메타데이터(예: HTTP 헤더, 원격 호스트 등)가 필요하다면 전송 provider에 TransportContextExtractor를 구성하세요.

WebMVC의 경우:

@Bean
public WebMvcStreamableServerTransportProvider transport() {
    return WebMvcStreamableServerTransportProvider.builder()
        .contextExtractor(serverRequest -> {
            String authorization = serverRequest.headers().firstHeader("Authorization");
            return McpTransportContext.create(Map.of("authorization", authorization));
        })
        .build();
}

WebFlux(리액티브)의 경우:

@Bean
public WebFluxStreamableServerTransportProvider transport() {
    return WebFluxStreamableServerTransportProvider.builder()
        .contextExtractor(serverRequest -> {
            String authorization = serverRequest.headers().firstHeader("Authorization");
            return McpTransportContext.create(Map.of("authorization", authorization));
        })
        .build();
}

구성 후 도구에서 McpSyncRequestContext(또는 McpAsyncRequestContext)로 컨텍스트에 접근하세요.

@McpTool
public String accessProtectedResource(McpSyncRequestContext requestContext) {
    McpTransportContext context = requestContext.transportContext();
    String authorization = (String) context.get("authorization");

    return "Successfully accessed protected resource.";
}

자동 설정 (Auto-Configuration)

Spring Boot 자동 설정을 사용하면 어노테이션된 빈이 자동으로 감지되고 등록돼요:

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

자동 설정은 다음을 수행해요:

1. MCP 어노테이션이 있는 빈을 스캔.
2. 적절한 명세를 생성.
3. MCP 서버에 등록.
4. 구성에 따라 동기·비동기 구현을 모두 처리.

구성 프로퍼티 (Configuration Properties)

서버 어노테이션 스캐너를 구성해요:

spring:
  ai:
    mcp:
      server:
        type: SYNC  # or ASYNC
        annotation-scanner:
          enabled: true

추가 자료 (Additional Resources)

• Server Annotations Reference - 서버 어노테이션에 대한 완전한 가이드
• Special Parameters - 고급 파라미터 주입
• Examples - 포괄적인 예제와 사용 사례

예제 애플리케이션 (Example Applications)

• Weather Server (SSE WebFlux) - WebFlux 전송과 함께하는 Spring AI MCP Server Boot Starter
• Weather Server (STDIO) - STDIO 전송과 함께하는 Spring AI MCP Server Boot Starter
• Weather Server Manual Configuration - 자동 설정을 사용하지 않고 Java SDK로 서버를 수동 구성하는 Spring AI MCP Server Boot Starter
• Streamable-HTTP WebFlux/WebMVC Example - TODO
• Stateless WebFlux/WebMVC Example - TODO

추가 자료 (Additional Resources)

• MCP Server Annotations - 어노테이션을 사용한 선언적 서버 개발
• Special Parameters - 고급 파라미터 주입과 컨텍스트 접근
• MCP Annotations Examples - 포괄적인 예제와 사용 사례
• Spring AI Documentation
• Model Context Protocol Specification
• Spring Boot Auto-configuration

더 알아보기 (Learn more)