스프링 부트 MCP 서버 만들기 - 자바 메서드를 깃허브 코파일럿 도구로 노출하는 방법

핵심 메시지

• MCP(모델 컨텍스트 프로토콜)를 쓰면 코파일럿이 코드를 써 주는 데 그치지 않고 내 애플리케이션의 자바 메서드를 직접 호출할 수 있다.
• 스프링 AI의 Web MVC MCP 서버 스타터 의존성 하나면 애플리케이션이 MCP 서버 역할을 하는 데 필요한 것이 갖춰진다.
• 메서드에 MCP 도구 애너테이션으로 이름과 설명을, 파라미터 애너테이션으로 필요한 입력을 적어 두면 스캐너가 이를 찾아 도구로 등록한다.
• application.properties에서 프로토콜을 streamable로 지정해야 최신 HTTP 엔드포인트가 열리고, 지정하지 않으면 예전 SSE 방식으로 되돌아간다.
• 도구 메서드는 로직을 새로 짜지 않고 웹 화면이 쓰는 것과 같은 서비스에 위임하므로, 코파일럿이 만든 결과가 웹 페이지에도 그대로 보인다.

쉽게 이해하기

비주얼 스튜디오 코드 공식 채널이 공개한 이 실습 영상은 질문 하나로 시작한다. 깃허브 코파일럿이 자바 코드를 작성해 주는 데서 멈추지 않고, 내가 이미 만들어 둔 자바 메서드를 직접 호출하게 할 수 있을까 하는 물음이다. 답은 모델 컨텍스트 프로토콜, 즉 MCP다. 예제는 할 일 목록을 다루는 평범한 스프링 부트 애플리케이션으로, 이미 동작하는 기능을 도구로 노출하는 것이 목표다.

준비물은 자바 개발 키트와 자바용 확장 팩, 스프링 부트 확장 팩, 그리고 로그인된 깃허브 코파일럿이다. 핵심은 pom.xml에 들어 있는 스프링 AI의 Web MVC MCP 서버 스타터로, 이 의존성 하나가 애플리케이션이 MCP 서버로 동작하는 데 필요한 것을 공급한다. 도구가 될 메서드들은 스프링 컴포넌트 안에 모여 있어 애너테이션 스캐너가 찾아낼 수 있고, 목록 조회부터 삭제까지 다섯 개가 등록 대상이다.

각 메서드에는 도구 이름과 설명을 적는 애너테이션이 붙고, 제목이나 아이디처럼 반드시 필요한 입력은 파라미터 애너테이션으로 설명한다. 이 설명이 곧 코파일럿이 도구를 이해하는 근거가 된다. 메서드 본문은 애플리케이션 로직을 다시 구현하지 않고 웹 페이지가 쓰는 것과 같은 서비스로 넘긴다. 마지막으로 application.properties에서 MCP 서버 프로토콜을 streamable로 지정하는데, 이 한 줄이 없으면 스타터가 예전 서버 전송 이벤트 방식으로 되돌아가 엔드포인트 자체가 열리지 않는다.

설정을 마치고 스프링 부트 대시보드에서 애플리케이션을 실행하면, 몇 초 뒤 터미널에 등록된 도구가 다섯 개라는 메시지가 뜬다. 스프링이 애너테이션이 붙은 메서드를 모두 찾았다는 확인이다. 이제 편집기 쪽 차례로, 작업 공간의 MCP 설정 파일에 실행 중인 애플리케이션 주소를 가리키는 HTTP 서버를 정의하고 연결을 시작한다. 이때의 시작은 자바 프로세스를 띄우는 것이 아니라 클라이언트를 붙이는 동작이라는 점이 영상에서 따로 강조된다.

연결이 되면 코파일럿 채팅의 도구 목록에 스프링이 등록한 다섯 개 이름이 그대로 나타난다. 활성화한 뒤 '할 일을 하나 추가하고 전체 목록을 보여 달라'처럼 도구 두 개를 차례로 써야 하는 작업을 시키면, 호출 전에 도구 이름과 인자를 확인하는 창이 뜨고 승인하면 실행된다. 브라우저에서 애플리케이션 화면을 새로 고치면 방금 추가한 항목이 똑같이 보이는데, 도구와 웹 화면이 하나의 서비스와 하나의 저장소를 함께 쓰기 때문이다. 저장소가 메모리 기반이라 프로세스를 끄면 실습 중 만든 데이터도 함께 사라진다.

주요 인사이트

• MCP의 실질적 가치는 새 기능을 만드는 데 있지 않고, 이미 검증된 비즈니스 로직을 그대로 둔 채 호출 창구만 하나 더 여는 데 있다. 도구 메서드가 서비스에 위임하기만 하는 구조가 그 점을 보여 준다.
• 애너테이션에 적는 도구 이름과 설명은 주석이 아니라 인터페이스다. 모델은 그 문장을 읽고 언제 어떤 도구를 부를지 판단하므로, 설명이 부실하면 도구가 있어도 호출되지 않는다.
• 전송 방식 설정 한 줄을 빠뜨리면 엔드포인트가 열리지 않는다는 대목은 MCP 서버를 처음 붙일 때 가장 흔히 막히는 지점이 무엇인지 알려 준다.
• 편집기에서 서버 연결을 시작하는 동작과 애플리케이션 프로세스를 띄우는 동작은 별개다. 둘을 혼동하면 서버가 이미 떠 있는데도 연결이 안 된다고 착각하기 쉽다.
• 도구 실행 전에 이름과 인자를 확인시키는 승인 절차는 모델이 실제 데이터를 바꾸는 작업을 수행할 때 최소한의 안전장치가 어디에 놓이는지 보여 준다.

자주 묻는 질문

관련 AI 소식