Spring AI 2.0 MCP 서버 만들기: Spring Boot 4 실전 가이드와 보안 체크리스트

AI 에이전트가 파일, 데이터베이스, 사내 API 같은 외부 도구를 안전하고 일관된 방식으로 호출하려면 연결 규격이 필요합니다. MCP(Model Context Protocol)는 이 연결 방식을 표준화하고, Spring AI 2.0은 Spring Boot 애플리케이션에서 MCP 서버와 클라이언트를 빠르게 구성할 수 있도록 스타터와 애너테이션 기반 모델을 제공합니다.

이 글에서는 Spring Boot 4와 Spring AI 2.0을 기준으로 가장 단순한 MCP 서버를 만들고, 실제 운영 전에 반드시 확인해야 할 보안 항목까지 정리합니다.

1. MCP를 한 문장으로 이해하기

MCP는 AI 애플리케이션이 외부의 도구(Tool), 자료(Resource), 프롬프트(Prompt)를 발견하고 호출하는 방식을 표준화한 프로토콜입니다. 서비스마다 별도의 플러그인 규격을 만드는 대신, MCP 클라이언트와 서버라는 공통 인터페이스로 연결할 수 있다는 점이 핵심입니다.

• Tool: 검색, 주문 조회, 파일 변환처럼 실행 가능한 기능
• Resource: 문서, 설정, 데이터처럼 읽을 수 있는 정보
• Prompt: 반복해서 사용하는 프롬프트 템플릿

2. Spring AI 2.0에서 달라진 점

Spring AI 2.0은 MCP Java SDK 2.0 계열과 최신 MCP 사양을 바탕으로 통합 구조를 정리했습니다. 특히 @McpTool, @McpResource, @McpPrompt 애너테이션이 Spring AI에 포함되어 보일러플레이트 코드가 크게 줄었습니다.

전송 방식은 로컬 프로세스 연동에 적합한 STDIO, 원격 서버에 적합한 Streamable HTTP, 상태를 최소화한 Stateless 방식 등을 선택할 수 있습니다. 새 프로젝트라면 기존 SSE보다 Streamable HTTP를 우선 검토하는 편이 좋습니다.

3. 프로젝트 의존성 추가

Spring Initializr에서 Spring Boot 프로젝트를 만든 뒤 MCP 서버 스타터를 추가합니다. 버전은 작성 시점의 최신 안정 버전을 확인해 적용하세요.

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

Gradle을 사용한다면 다음과 같이 추가할 수 있습니다.

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

4. 가장 작은 MCP Tool 만들기

아래 예제는 도시 이름을 받아 간단한 날씨 안내 문자열을 반환합니다. 실제 서비스에서는 외부 날씨 API나 사내 데이터베이스 호출로 교체하면 됩니다.

import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.stereotype.Service;

@Service
public class WeatherTool {

    @McpTool(
        name = "get_weather",
        description = "도시 이름으로 현재 날씨 정보를 조회합니다"
    )
    public String getWeather(String city) {
        return city + "의 현재 날씨는 맑음입니다.";
    }
}

도구 이름과 설명은 모델이 어떤 상황에서 이 기능을 호출할지 판단하는 단서입니다. 설명을 모호하게 쓰기보다 입력값, 반환값, 사용 조건을 구체적으로 적는 것이 좋습니다.

5. Streamable HTTP 설정

원격에서 접근 가능한 MCP 서버를 구성하려면 다음처럼 전송 프로토콜을 지정할 수 있습니다.

spring:
  ai:
    mcp:
      server:
        name: knowledge-mcp-server
        version: 1.0.0
        protocol: STREAMABLE

서버를 실행하면 MCP 클라이언트가 초기화 과정을 거쳐 제공 기능을 탐색하고 Tool을 호출할 수 있습니다. 운영 환경에서는 타임아웃, 동시 호출 수, 관측성 설정도 함께 점검해야 합니다.

6. 운영 배포 전 반드시 확인할 보안

가장 중요한 부분입니다. Spring AI의 MCP 전송 계층은 인증을 자동으로 강제하지 않습니다. 외부에서 접근 가능한 엔드포인트를 그대로 노출하면 등록된 Tool과 Resource가 인증 없이 조회되거나 실행될 수 있습니다.

1. 인증·인가 적용: Spring Security, OAuth 2.0 또는 API Key 계층을 추가합니다.
2. 최소 권한: 파일·DB·외부 API 권한을 Tool이 실제로 필요한 범위로 제한합니다.
3. 입력값 검증: 경로 조작, 명령 삽입, 과도한 요청을 차단합니다.
4. 승인 단계: 삭제·결제·게시처럼 되돌리기 어려운 작업은 사람의 확인을 거치게 합니다.
5. 감사 로그: 누가 어떤 Tool을 어떤 입력으로 호출했는지 기록하되 비밀값은 남기지 않습니다.

7. 자주 발생하는 문제

Tool이 발견되지 않는 경우

애너테이션이 붙은 클래스가 Spring Bean으로 등록됐는지, 컴포넌트 스캔 범위에 포함됐는지 먼저 확인하세요.

연결은 되지만 호출이 실패하는 경우

클라이언트와 서버의 전송 방식이 같은지, 엔드포인트 주소와 프로토콜 버전이 맞는지 확인합니다. 기존 예제의 SSE 설정을 그대로 사용했다면 최신 Streamable HTTP 구성과 혼용되지 않았는지도 살펴보세요.

운영에서만 타임아웃이 발생하는 경우

Tool 내부의 외부 API 호출 시간과 MCP 요청 타임아웃을 함께 점검해야 합니다. 오래 걸리는 작업은 비동기 처리, 진행 상태 보고 또는 작업 큐를 고려하는 편이 안전합니다.

마무리

Spring AI 2.0의 MCP 통합은 Java·Spring 개발자가 기존 서비스 기능을 AI 에이전트에 연결하는 진입 장벽을 크게 낮췄습니다. 다만 Tool을 만드는 것보다 중요한 것은 어떤 기능을 어느 권한으로 공개할지 설계하는 일입니다. 로컬에서 작은 읽기 전용 Tool부터 검증한 뒤 인증, 권한, 감사 로그를 갖춰 단계적으로 확장하는 것을 권합니다.

참고 자료

• Spring AI 2.0.0 GA 공식 발표
• Spring AI MCP 공식 레퍼런스
• MCP Server Boot Starter 공식 문서