LangChain4j - Spring AI MCP 구축기 (3)

김주엽·2025년 5월 16일

✨ 들어가며

Spring AI를 활용하면 MCP 서버를 손쉽게 구축할 수 있습니다.

이 글에서는 기본적인 MCP 서버를 생성하는 과정을 단계별로 안내합니다.

🛠️ 1. 의존성 추가

프로젝트의 build.gradle 파일에 다음과 같은 의존성을 추가합니다. Spring AI의 MCP 서버 기능을 사용하기 위한 필수적인 의존성 정의와 저장소 설정입니다.

repositories {
    mavenCentral()
    maven { url 'https://repo.spring.io/milestone' }
    maven { url 'https://repo.spring.io/snapshot' }
    maven {
        url = uri('https://central.sonatype.com/repository/maven-snapshots')
        mavenContent {
            snapshotsOnly()
        }
    }
}

dependencyManagement {
    imports {
        mavenBom 'org.springframework.ai:spring-ai-bom:1.0.0-SNAPSHOT'
    }
}

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-mcp-server-webmvc'
}

mavenCentral(): Maven 중앙 저장소를 추가합니다.
maven { url '<https://repo.spring.io/milestone>' },
maven { url '<https://repo.spring.io/snapshot>' }: Spring Milestone 및 Snapshot 저장소를 추가합니다.
- Spring AI는 아직 개발 중인 프로젝트이므로 최신 기능을 사용하기 위해 해당 저장소를 포함합니다.
maven { url = uri('<https://central.sonatype.com/repository/maven-snapshots/>') ... }: Sonatype의 Snapshot 저장소를 추가합니다.
dependencyManagement: Spring AI BOM (Bill of Materials)을 가져와 Spring AI 관련 의존성의 버전을 관리합니다.
- 이를 통해 각 Spring AI 라이브러리의 버전을 명시적으로 지정할 필요가 없습니다.
implementation 'org.springframework.ai:spring-ai-starter-mcp-server-webmvc': MCP 서버 및 WebMVC 기능을 포함하는 Spring AI Starter 의존성을 추가합니다.

🛡️ 2. application.yml 설정

MCP 서버의 기본 설정을 정의합니다. 서버 이름, 버전, 통신 방식, SSE 엔드포인트 등을 설정할 수 있습니다. src/main/resources/application.yml 파일에 다음 내용을 추가하세요.

spring:
  main:
    banner-mode: off
  ai:
    mcp:
      server:
        name: mcp-server-example
        version: 0.0.1
        type: SYNC
        sse-endpoint: /sse
        sse-message-endpoint: /mcp/messages

속성	기본값	설명
`spring.main.banner-mode`	`off`	애플리케이션 시작 시 배너 출력을 비활성화합니다.
`spring.ai.mcp.server.name`	`mcp-server`	서버의 고유한 이름 (식별 용도로 사용됩니다).
`spring.ai.mcp.server.version`	`1.0.0`	서버의 버전 정보입니다.
`spring.ai.mcp.server.type`	`SYNC`	서버의 통신 타입입니다. `SYNC` (동기) 또는 `ASYNC` (비동기)를 설정할 수 있습니다.
`spring.ai.mcp.server.sse-endpoint`	`/sse`	클라이언트가 서버로부터 이벤트를 수신하기 위한 Server-Sent Events (SSE) 엔드포인트 경로입니다.
`spring.ai.mcp.server.sse-message-endpoint`	`/mcp/messages`	클라이언트가 서버로 메시지를 전송할 수 있는 웹 전송을 위한 커스텀 SSE 메시지 엔드포인트 경로입니다.

🔧 3. Tool 정의

MCP 서버에서 제공할 기능을 Tool 형태로 정의합니다.

@Tool 어노테이션을 사용하여 메서드를 Tool로 등록할 수 있습니다.

@Service
@RequiredArgsConstructor
public class UserService {
    private final UserRepository userRepository;

    @Tool(name = "getAllUsers", description = """
	    모든 사용자 정보를 조회합니다. 다음과 같은 비슷한 상황에서 이 도구를 사용하세요.
		  예시:
		    - '모든 사용자 목록 보여줘'
		    - '시스템에 등록된 사용자가 몇 명인지 알려줘'
		    - '전체 사용자 정보를 조회해줘'.
	    페이지네이션이 필요한 경우 getPaginatedUsers 도구를 대신 사용하세요.
    """)
    public List<UserResponseDTO> findAllUsers() {
        return userRepository.findAll().stream()
                .map(UserResponseDTO::from)
                .toList();
    }
}`

@Service: 해당 클래스를 스프링 서비스로 등록합니다.
@RequiredArgsConstructor: Lombok 라이브러리의 어노테이션으로, final 필드에 대한 생성자를 자동으로 생성해줍니다.
@Tool(name = "...", description = "..."): 해당 메서드를 MCP에서 호출 가능한 Tool로 정의합니다.
- name: Tool의 이름으로, 클라이언트에서 이 이름을 사용하여 Tool을 호출합니다.
- description: Tool에 대한 상세 설명입니다.
  - AI 모델이 Tool을 선택하고 사용하는 방법을 이해하는 데 도움이 되도록 설명을 작성합니다.

👀 4. Configuration 등록

정의된 Tool들을 MCP 클라이언트가 사용할 수 있도록 Configuration을 작성해야 합니다.

ToolCallbackProvider 빈을 생성하여 이를 수행합니다.

@Configuration
@RequiredArgsConstructor
public class ToolCallbackProviderConfig {
    private final UserService userService;

    @Bean
    public ToolCallbackProvider toolCallbackProvider() {
        return MethodToolCallbackProvider.builder()
                .toolObjects(userService)
                .build();
    }
}