부록: 스프링 AI 플레이그라운드¶
앞 글에서는 이 책의 MCP 서버를 클로드 코드, 코덱스 같은 외부 AI 에이전트에 연결했습니다. 이번에 서버를 연결할 곳은 스프링 AI 플레이그라운드입니다. 플레이그라운드는 이 책과 별개로 개발되는 오픈소스 프로젝트입니다. 스프링 AI 커뮤니티의 인큐베이팅 프로젝트이고 아파치 2.0 라이선스로 공개되어 있으며, 이 책의 저자가 리드 메인테이너를 맡아 개발을 이끌고 있습니다.
이 글에서는 플레이그라운드가 어떤 기능으로 이루어져 있는지 먼저 봅니다. 그다음 예제 저장소 코드로 실행한 6장 지식 MCP 서버를 플레이그라운드에 연결하고, MCP 인스펙터로 툴을 검사한 뒤 에이전트 채팅에서 그 툴이 쓰이는 모습까지 확인합니다.
스프링 AI 플레이그라운드란¶
처음에는 스프링 AI의 여러 기능을 UI에서 바로 실험해 보려는 커뮤니티 프로젝트로 출발했습니다. 스프링 AI에 에이전트와 MCP 지원이 본격적으로 들어온 뒤로는 MCP 툴을 만들고 검증하고 안전하게 실행하는 일에 무게를 둔 툴 중심의 에이전트 실험 환경으로 자랐습니다. 애플리케이션 자체를 스프링 AI로 만들었고, 화면은 바딘(Vaadin)으로 구성했으며, 운영체제별 데스크톱 애플리케이션으로 배포합니다.
RAG, MCP, 에이전트 루프처럼 책에서 장을 나눠 다룬 스프링 AI 기능이 플레이그라운드에서는 각자의 화면으로 구현되어 있습니다. 이 화면들은 서로 연결되어 있어서 한 곳에서 확인한 결과를 다른 곳에서 곧바로 쓸 수 있습니다. 기능은 다음 다섯 축으로 나뉩니다.
- 툴 스튜디오: 자바스크립트로 작성하는 저코드 툴을 샘플 입력으로 시험하고, 통과한 툴만 공개하는 no-pass-no-run 방식으로 관리합니다.
- MCP 서버와 인스펙터: 연결한 MCP 서버의 툴, 리소스, 프롬프트, 알림과 클라이언트 쪽 기본 요소를 탭별로 살펴보고 직접 실행합니다. 인스펙터는 서버 기본 요소와 클라이언트 기본 요소를 나눠 검증합니다.
- 벡터 데이터베이스와 RAG: 문서를 읽고, 나누고, 색인하고, 검색하는 흐름을 화면에서 관리합니다. 3장에서 다룬 RAG 과정을 눈으로 다시 따라가 볼 수 있습니다.
- 에이전트 채팅: 툴 호출, RAG, 프롬프트, 모델 설정을 한데 묶어 시험하는 단일 에이전트 채팅입니다. 검증을 마친 MCP 연결과 벡터 검색을 채팅에서 바로 씁니다.
- 관측 가능성: 채팅 턴, 툴 호출, MCP 교환, 벡터 질의를 실행 중에 모두 수집해 추적합니다.
설치¶
설치 파일은 운영체제마다 따로 제공됩니다. 다운로드 페이지에 들어가 자신의 운영체제 버튼을 고르면 가장 최근 릴리스를 내려받을 수 있습니다. 앱 안에는 설정 편집기와 모델 제공자별 시작 템플릿이 있고, API 키는 운영체제의 보안 저장소에 보관하며, 올라마 모델을 관리하는 화면도 들어 있습니다. 모델 연결에 필요한 설정과 API 키 같은 비밀 값을 앱을 벗어나지 않고 다룰 수 있다는 뜻입니다.
지식 MCP 서버 연결 설정¶
플레이그라운드에서는 외부 MCP 서버를 연결한 뒤 인스펙터로 툴을 검사하고, 에이전트 채팅에서 그 툴을 호출해 시험합니다. 연결 대상은 부록 C에서 외부 에이전트에 붙였던 서버와 같습니다. 먼저 예제 저장소에서 6장 지식 서버를 실행합니다. 지식 서버는 기동하면서 문서를 색인하므로 올라마와 bge-m3 임베딩 모델이 준비되어 있어야 합니다.
서버가 올라오면 플레이그라운드의 MCP 서버 화면에서 지식 서버의 주소 http://localhost:8086/mcp를 등록합니다. 아래 그림은 서버 이름을 부록 C와 같은 book-knowledge로 정하고, 전송 방식으로 Streamable HTTP를 골라 URL http://localhost:8086과 엔드포인트 /mcp를 나눠 입력한 화면입니다. URL의 포트 8086과 엔드포인트 /mcp는 지식 서버의 application-knowledge.yml에 있는 server.port와 spring.ai.mcp.server.streamable-http.mcp-endpoint 값에 맞춘 것입니다.
MCP 인스펙터로 툴 확인¶
서버에 연결되면 인스펙터 화면에 이 서버가 내놓은 툴과 리소스, 프롬프트 목록이 나타납니다. 탭에는 Roots, Sampling, Elicitation 같은 클라이언트 기본 요소도 따로 있어서 서버 쪽 기능과 나눠 검증할 수 있습니다. 지식 서버의 툴 목록에는 rag_answer_question 하나가 보입니다. 서버 안에서 문서를 검색하고 검색한 문서만 근거로 답을 만드는 툴로, 6장에서 에이전트를 툴로 제공하는 방식의 예로 만든 것입니다.
툴 카드에는 툴 설명과 입력 스키마가 나오고, 입력값을 넣어 그 자리에서 실행해 볼 수 있습니다. 카드에 보이는 제목(RAG 근거 기반 답변)과 question, topK, category 파라미터 설명은 지식 서버의 KnowledgeMcpTools 클래스가 @McpTool, @McpToolParam 애너테이션에 적어 둔 문구 그대로입니다. 그림은 question 파라미터에 비밀번호 변경 주기를 묻는 질문을 넣고 실행해 요청과 응답 JSON을 확인하는 모습입니다. 모델이 이 툴을 부르게 하기 전에 입력과 결과가 약속한 계약에 맞는지 사람이 먼저 확인하는 단계로, 실무에서도 건너뛰지 않는 편이 좋습니다.
에이전트 채팅에서 답변 확인¶
인스펙터에서 확인한 툴은 에이전트 채팅에서 호출할 수 있습니다. 지식 서버를 연결해 둔 상태로 사내 보안 정책을 물으면, 모델이 rag_answer_question을 호출하고 그 결과로 답하는 흐름이 채팅 화면에 드러납니다.
그림에서는 올라마 qwen3.5:4b 모델에게 보안 정책 문서 속 비밀번호 변경 주기를 물었습니다. 채팅 기록 안에 모델이 보낸 툴 호출 인자, 서버가 돌려준 툴 결과, 최종 답변이 차례로 펼쳐져 있어 어느 시점에 어떤 툴이 불렸는지 따라갈 수 있습니다.
플레이그라운드와 서버는 MCP 표준으로 통신하므로, 부록 C에서 클로드 코드나 코덱스를 붙인 것과 원리는 같습니다. 차이는 화면에 있습니다. 서버 연결부터 툴 검사, 승인, 채팅 시험까지 한곳에서 눈으로 확인하며 진행할 수 있습니다. 공부할 때뿐 아니라 만든 툴을 외부에 내놓기 직전에 최종 점검하는 용도로도 쓸 수 있습니다.
책과 플레이그라운드의 역할¶
책과 플레이그라운드는 맡은 몫이 다릅니다. 모델 추상화, RAG, 툴 호출, MCP, 관측을 왜 그렇게 설계하는지, 그리고 직접 어떻게 구현하는지는 책과 예제 저장소 코드가 다룹니다. 플레이그라운드는 그렇게 만든 기능을 가져와 한 화면에서 시험하고, 운영하는 감각으로 다뤄 보는 쪽에 가깝습니다. 책에서 코드로 쌓은 개념이 실제 제품 안에서 어떻게 맞물리는지 보고 싶다면, 이 글에서 한 것처럼 책의 MCP 서버를 플레이그라운드에 직접 연결해 보는 것으로 시작할 수 있습니다. 책과 플레이그라운드를 함께 보면 책에서 읽은 내용을 화면으로 확인하고 설정을 바꿔 가며 되풀이해 실험할 수 있어, MCP 기반 에이전트를 익히는 데 도움이 됩니다.
4-티어 아키텍처에서의 위치¶
책의 MCP 서버 쪽에서 보면 플레이그라운드는 부록 C의 외부 에이전트처럼 MCP로 접속하는 또 하나의 앞단입니다. 사용자의 입력을 받고, 툴 실행 과정과 응답을 보여 주고, 승인 같은 사람의 개입을 처리한다는 점에서 4-티어의 T1 채널이 맡는 일과 겹칩니다. 능력을 MCP 서버로 떼어 표준 인터페이스 뒤에 둔 덕분에, 앞단이 책의 CLI든 외부 에이전트든 플레이그라운드든 T3 자리의 서버는 그대로 다시 쓸 수 있습니다. 책의 장을 따라온 글은 여기까지입니다. 4-티어 요약부터 다시 훑어보려면 처음으로 돌아가면 됩니다.
책에서 더 다루는 내용¶
책 부록 D
- 플레이그라운드가 UI 실험용 커뮤니티 프로젝트에서 툴 중심 에이전트 실험 환경으로 넓어진 배경
- 다섯 축의 기능이 서로 이어지는 방식과 책의 3장, 5장, 6장 주제와 맞닿는 지점
- 부록 C의 외부 AI 에이전트 연결과 플레이그라운드 연결을 나란히 놓고 본 비교
참고 자료¶
- spring-ai-community/spring-ai-playground: 스프링 AI 플레이그라운드 프로젝트 저장소