Spring MCP Server

Tags:

개요

MCP Server는 AI 모델이 외부 리소스(도구, 데이터, API 등)에 접근할 수 있도록 연결해주는 표준화된 인터페이스를 제공하는 역할을 한다.

MCP 서버에 대한 개념은 아래의 문서를 참고 바란다.
AI 용어 | MCP Server

이 문서에선 Spring를 활용하여 MCP Server를 만들고, Claude에서 MCP Server에 연결하는 방법에 대해서 설명한다.
MCP architect

물론, Claude 외에 다른 AI 도구를 활용할 수도 있고, MCP Server도 Spring이 아니어도 된다. MCP는 말 그대로 모델 컨텐츠 규약을 대로 따르기에 가능한 것이다.

MCP Server에서 연결되는 Resoures는 DB, API 등 다양하게 활용될 수 있다. 여기 문서는 Resoures는 연결까지는 다루지 않았다.

Spring을 활용한 MCP Server 구현

먼저 간단한 Spring와 Kotlin를 활용한 MCP Server를 생성해 보겠다.

프로젝트 생성

먼저, Spirng ininitializr에서 신규 프로젝트를 생성한다.

Spirng ininitializr

화면 아래 부근에 “GENERATE” 버튼을 누르면, 프로젝트 파일을 다운을 수 있다.

또는, 아래와 같이 curl 명령어를 사용하여 Spring Boot 초기 프로젝트를 생성할 수도 있다.

curl https://start.spring.io/starter.tgz \
-d bootVersion=3.5.7 \
-d dependencies=spring-ai-mcp-server \
-d baseDir=spring-ai-mcp-server \
-d groupId=com.devkuma \
-d artifactId=spring-ai-mcp-server \
-d packageName=com.devkuma.ai.mcp.server \
-d applicationName=McpServerApplication \
-d packaging=jar \
-d language=kotlin \
-d javaVersion=21 \
-d description="Demo project for Spring AI MCP Server" \
-d type=gradle-project-kotlin | tar -xzvf -

생성된 프로젝트 확인

빌드 스크립트

/build.gradle.kts

dependencies {
	...
	implementation("org.springframework.ai:spring-ai-starter-mcp-server")
	...
}

의존성 라이브러리에 스프링 캐시 라이브러리(spring-ai-starter-mcp-server)가 포함된 것을 볼 수 있다.

Service 객체 생성

MCP Client에서 호출을 하게 되는 서비스 객체를 생성한다.

package com.devkuma.ai.mcp.server

import org.springframework.ai.tool.annotation.Tool
import org.springframework.ai.tool.annotation.ToolParam
import org.springframework.stereotype.Service

@Service
class WeatherService {

    @Tool(name = "get_weather", description = "Return the weather of a given city.")
    fun getWeather(@ToolParam(description = "The city for which to get the weather") city: String): String {
        // 실제 날씨 정보를 가져오는 로직을 추가한다.
        // 여기서는 간단히 "Good"을 반환한다.
        return "The weather in $city is good."
    }
}

여기서는 도시(city)를 전달 받고, 날씨의 상태를 고정으로 “good"이라고 응답하게 만들었다.
여기서는 고정으로 넣었지만, 실제로는 다른 리소스(DB, API 등)에서 정보를 가져와서 응답하게 하면 된다.

MCP 설정 객체 생성

생성된 Service를 Spring 설정으로 AI Tool로 추가한다.

package com.devkuma.ai.mcp.server

import org.springframework.ai.tool.ToolCallbackProvider
import org.springframework.ai.tool.method.MethodToolCallbackProvider
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration
class McpConfig {

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

어플리케이션 설정 파일

src/main/resources/application.yml를 아래와 같이 작성한다.

spring:
  main:
    web-application-type: none
    # NOTE: You must disable the banner and the console logging to allow the STDIO transport to work !!!
    banner-mode: off
  ai:
    mcp:
      server:
        name: my-weather-server
        version: 0.0.1

logging:
  pattern:
    console:
  file:
    name: ./model-context-protocol/spring-ai-starter-mcp-server/mcp-weather-stdio-server.log

여기서 주의점은 banner-mode로 진정해야 한다.

빌드 및 실행 파일 생성

이제 완료되었다면 빌드를 해야 하는데, IDEA로 gradle 빌드로 boorJar를 실행한다.

또는, 아래와 같이 터미널에서 커멘드로 아래와 같이 실행한다.

% ./gradlew clean bootJar

그러면, jar 파일이 아래 경로에 생성된다.
build/libs/spring-ai-mcp-server-0.0.1-SNAPSHOT.jar

Claude에서 MCP Server에 연결

빌드까지 완료가 되었다면 클로드 데스크탑에 MCP Server에 연결해 보고, 적용이 잘되어 있는지 확인해보도록 하겠다.

연결 설정

MCP Server 연결 설정은 json 파일에 등록해야 한다.

MacOS인 경우에는 ~/Library/Application Support/Claude/claude_desktop_config.json에 설정을 하면된다.
(파일이 없다면 새로 생성을 하고, 기존에 있다면 추가한다.)

{
  "mcpServers": {
    "spring-ai-mcp-weather": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dlogging.pattern.console=",
        "-jar",
        "{{앞에서 만든 프로젝트의 경로}}/spring-ai-mcp-server/build/libs/spring-ai-mcp-server-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

생성한 어플리케이션은 java 명령어로 실행이 되고, 실행된 서버는 stdio를 통해서 클로드 데스크탑과 연결이 된다.

연결 설정 확인

메뉴에서 “Claude > 설정 > 개발자"을 확인해 보면, 로컬 MCP 서버가 추가되어 있는 것을 확인 할 수 있다. Spring AI MCP Server Claude

채팅 창에서는 설정 버튼을 누르면 “spring-ai-mcp-wearther"가 활성화 되어 있는 것을 볼 수 있다. Spring AI MCP Server Claude

실행 확인

이제 연결이 잘 된 것을 확인했으니, 입력을 해보도로 하겠다.

아래 창에서는 “서울의 날씨는 어때?“라고 입력을 하였다. Spring AI MCP Server Claude

그러면, 아래와 같이 “Claude가 spring-ai-mcp-weather에서 Get weather을(를) 사용하려고 합니다.“라는 메세지와 함께, 허용 여부를 묻는다. Spring AI MCP Server Claude

허용 버튼을 누르면, 응답으로 “서울 날씨는 좋습니다.“라는 응답하는 것을 볼 수 있다.
“Get weather"를 누르면 요청과 응답에 대해서도 확인할 수 있다. Spring AI MCP Server Claude

참고

위에 예제 코드는 GitHub에서 확인해 볼 수 있다.