kakao PlayMcp 이용기

Kakao PlayMCP 서비스 사용기

이번에 Kakao PlayMCP라는 서비스에 직접 만든 Remote Server와 Tool을 어떻게 구성했고, PlayMCP 서비스 등록 및 테스트까지 진행했던 과정을 설명합니다.

Kakao PlayMCP 서비스란?

카카오에서 베타 오픈한 PlayMCP는 개발자들이 만든 MCP 서버(Tool)를 등록하고, 다른 사용자들이나 AI가 이를 발견하고 테스트하며 사용할 수 있는 공간입니다.

카카오 계정이 있는 사람이라면 누구든 자신이 만든 MCP 서버를 등록하고 실제 대화에서 어떻게 작동하는지 테스트할 수 있는 플랫폼을 제공합니다.

또한 다른 사람이 올린 도구도 자유롭게 사용이 가능합니다.

나의 MCP 서버를 웹에 공개하고 등록하기만 하면, 실제 AI 채팅 환경에서 사용자의 다양한 대화 시나리오에 따라 내 툴이 정확하게 호출되는지 실시간으로 확인할 수 있습니다. 뿐만 아니라, 툴의 호출 수나 사용자 수 같은 통계 데이터를 제공받고 다른 개발자들에게 내 툴을 쉽게 공유하고 알리는 것까지 가능합니다.

PlayMCP 주요 기능

카카오 PlayMCP에서는 아래의 기능을 제공하며 자세한 내용은 더 아래에서 다루겠습니다.

1. MCP Server 등록

• remote MCP Server를 등록할 수 있어요. 등록된 MCP Server는 누구나 PlayMCP에서 써볼 수 있습니다.
• OAuth 인증과 Key/Token 인증을 사용하는 MCP를 등록할 수 있어요. 개인화된 툴 사용을 가능케 합니다.

2. AI 채팅

• PlayMCP에 등록된 MCP 툴을 사용해 볼 수 있는 AI 채팅을 제공
• 툴이 호출될 때마다 request / response 확인 가능

3. 그 외

• MCP 별로 툴콜 수, 사용자 수도 확인할 수 있고요.
• MCP 개발자를 위한 디스코드를 운영하고 있어서 PlayMCP 개발자들과 자유롭게 의견 교환도 가능합니다.

본격적인 개발에 앞서: MCP와 Tool 이해하기

먼저 PlayMCP에 Tool을 등록하기 전에 용어에 대한 이해가 필요합니다.

MCP(Model Context Protocol)란?

MCP는 “Model Context Protocol”의 약자로, AI 모델(LLM)이 외부 세계의 기능(Tool)을 호출하고 그 결과를 돌려받기 위한 표준화된 통신 규약입니다.

AI는 그 자체로 방대한 지식을 가지고 있지만, 실시간 날씨를 조회하거나, 특정 웹사이트의 최신 정보를 가져오는 등의 작업은 혼자 할 수 없습니다. MCP는 AI가 이런 외부 기능을 마치 함수를 호출하듯 명확하고 안전하게 사용할 수 있도록 만들어주는 ‘다리’ 역할을 합니다.

Tool이란?

Tool은 MCP 규격에 맞춰 AI가 사용할 수 있도록 제공하는 구체적인 기능 하나하나를 의미합니다. 예를 들어 ‘날씨 조회’, ‘미세먼지 농도 확인’과 같은 기능이 각각의 Tool이 될 수 있습니다.

Tool은 크게 아래와 같은 요소로 구성됩니다.

• name: AI가 이 Tool을 부를 때 사용할 이름. 도구의 고유 식별자 (get_short_term_forcast)
• title: 사람이 읽을 수 Tool 이름
• description: AI가 이 Tool의 용도를 이해할 수 있도록 설명하는 글
• inputSchema: 예상 매개변수를 정의하는 JSON 스키마
• outputSchema: 예상되는 출력 구조를 정의하는 선택적 JSON 스키마
• schema: AI가 이 Tool을 사용할 때 어떤 정보를 넘겨줘야 하는지(입력 파라미터)를 zod 라이브러리를 통해 명확하게 정의한 부분
• annotations: 도구 동작을 설명하는 선택적 속성

결국 Tool이란 AI에게 ‘이런 이름과 설명, 입력값을 가진 함수가 있으니 필요할 때 사용해!’라고 알려주는 기능의 명세서이자 실제 구현체인 셈입니다.

나만의 MCP Tool 서버 개발 및 등록하기

어떤 Tool을 만들었는가?

이번 프로젝트에서는 공공데이터포털의 API를 활용하여 실시간 날씨와 미세먼지 정보를 조회하는 Tool들을 만들었습니다. AI에게 “오늘 서울 날씨 어때?” 또는 “내일 부산 날씨와 미세먼지 어때?”라고 물었을 때, AI가 제가 만든 Tool을 사용해 정확한 정보를 찾아 답변하게 하는 것이 목표입니다.

MCP 서버 만들기

MCP 서버는 Node.js와 Express 프레임워크, @modelcontextprotocol/sdk를 사용하여 구축했습니다. 전체적인 구조는 다음과 같습니다.

• Tool 정의 (날씨, 미세먼지)

먼저 AI에게 제공할 기능(Tool)을 클래스 형태로 정의합니다.

입력값의 형태와 규칙을 정의하기 위해 zod 라이브러리를 사용하여 스키마(InputSchema)를 작성했습니다. 각 입력 필드에 .describe()로 설명을 추가해주어야 AI가 각 파라미터의 의미를 정확히 이해하고 사용할 수 있게 했습니다.

execute 메서드에서는 zod 스키마로 입력값을 검증하고, fetch를 사용해 외부 API(공공데이터포털)를 호출합니다. 그 후, 응답 데이터를 AI가 해석하기 좋은 형태로 가공하여 반환합니다.

• Tool 등록 (tools/register.ts)

정의된 Tool 클래스들을 McpServer 인스턴스에 등록하는 역할을 합니다. 하나의 서버여 2개의 tool을 등록하고,

registerAllTools 함수는 반복문을 돌며 준비된 Tool 목록을 MCP 서버에 하나씩 추가합니다. 이 과정을 통해 MCP 서버는 자신이 어떤 Tool들을 가지고 있는지 알게 됩니다.

• MCP 서버 설정 및 실행 (server.ts)

Express를 사용하여 웹 서버를 설정하고, CORS 정책 등 기본적인 미들웨어를 추가합니다.

핵심은 /mcp 경로로 들어오는 POST, GET, DELETE 요청을 처리하는 부분입니다. @modelcontextprotocol/sdk의 StreamableHTTPServerTransport가 이 로직을 담당하며, AI 클라이언트와의 세션 관리, 요청 및 응답 스트리밍 등을 처리해줍니다.

클라이언트(PlayMCP의 AI)가 처음 접속하면(isInitializeRequest) 새로운 세션을 만들고, 이후의 모든 요청은 발급된 세션 ID(mcp-session-id)를 통해 통신이 이루어집니다.

PlayMCP에 내 서버 연결하기

1. 서버 배포: 먼저 위에서 만든 Node.js 서버를 클라우드 서비스(e.g., Fly.io, Vercel, AWS 등)를 이용해 외부에서 접속 가능한 주소로 배포합니다.

2. PlayMCP 접속 및 등록: PlayMCP 사이트에 접속하여 로그인한 후, ‘MCP 등록하기’ 버튼을 클릭합니다.

3. 정보 입력: ‘Remote MCP Server’를 선택하고, 배포된 서버의 /mcp 주소(e.g., https://my-mcp-server/mcp)를 입력합니다. 제 서버는 별도의 인증을 구현하지 않았으므로 인증 방식은 ‘인증 없음’을 선택합니다.

인증 방식 설정 (Authentication): PlayMCP는 등록할 서버의 성격에 따라 두 가지 인증 방식을 지원합니다.

• Key/Token 인증:
  • 서버가 특정 API Key나 토큰을 헤더(Header)에 요구하는 경우 사용합니다.
  • 주로 “나만 쓰거나” 혹은 “특정 키를 가진 사람만 쓰게 하고 싶을 때” 유용합니다.
  • PlayMCP에 미리 키를 등록해두면, AI가 요청을 보낼 때마다 자동으로 헤더에 키를 실어 보냅니다.
• OAuth 인증:
  • “사용자 별로 다른 데이터”를 다뤄야 할 때 사용합니다 (예: 구글 캘린더, 노션 등).
  • 사용자가 툴을 처음 쓸 때 PlayMCP가 대신 로그인 창을 띄워주고, 발급받은 액세스 토큰(Access Token)을 MCP 서버로 전달해줍니다.
  • 제 서버는 공공데이터를 조회하는 공용 툴이라 인증이 필요 없지만, 개인화된 비서 서비스를 만든다면 이 기능이 필수적일 것입니다.

MCP Endpoint를 입력하고 정보 불러오기를 클릭하면 아래와 같이 사용가능한 tool list를 읽어옵니다.

4. 등록 완료: 정보를 모두 입력하고 ‘등록하기’를 누르면 PlayMCP가 제 서버에 접속하여 유효성을 검사합니다. 검사가 성공적으로 완료되면 목록에 제가 만든 MCP 서버가 나타납니다.

AI 채팅으로 실시간 동작 확인하기

• 등록 후 PlayMCP의 ‘AI 채팅’ 화면에서 내 Tool을 선택합니다.

“오늘 서울 종로구의 날씨를 알려줘”와 같이 실제로 AI에게 말을 걸었을 때, 제 서버 로그에 /mcp로 요청이 들어오는 것을 확인할 수 있었습니다.

AI는 제 get_short_term_forcast Tool을 사용하기 위해 필요한 파라미터(날짜, 좌표 등)를 스스로 판단하여 요청을 보냈고, 제 서버는 기상청 데이터를 가공하여 AI에게 전달했습니다.

최종적으로 AI는 이 데이터를 바탕으로 사용자에게 자연스러운 문장으로 날씨 정보를 답변해 주었습니다.

이 과정에서 툴이 호출될 때마다 request/response를 직접 확인할 수 있습니다.

마치며: PlayMCP 등록 후기 및 생각

개발 경험 돌아보기

처음 MCP 서버를 개발하면서 겪었던 몇 가지 혼란스러운 점들을 공유합니다.

1. /mcp와 /sse 엔드포인트의 역할

처음 명세를 보았을 때 /mcp와 /sse가 각각 정확히 어떤 역할을 하는지 이해하기 어려웠습니다.

• /sse: 서버가 클라이언트(AI)에게 이벤트를 단방향으로 스트리밍하는 연결입니다. 이를 통해 서버는 “준비되었다”는 신호나 로그 등을 보냅니다.
• /mcp: 클라이언트가 서버에게 실제 요청(Tool 실행, 리소스 조회 등)을 보내는 HTTP POST 엔드포인트입니다.

이 두 가지가 결합되어 양방향 통신이 완성된다는 개념을 잡는 데 시간이 조금 걸렸습니다.

2. Remote MCP Server와 Tool의 개념 차이

“Remote MCP Server”와 “Tool”이라는 용어가 혼재되어 있어 헷갈렸습니다.

• Remote MCP Server: 여러 개의 Tool을 담고 있는 그릇(Container)이자 웹 서버입니다. (예: my-weather-server)
• Tool: 그 서버 안에 들어있는 개별 기능들입니다. (예: get_weather, get_dust)

PlayMCP에는 “서버”를 등록하면, 그 안에 있는 “Tool”들이 자동으로 인식되어 AI가 사용할 수 있게 된다는 구조를 이해하고 나니 개발이 훨씬 수월해졌습니다.

3. JSON-RPC와 Handshake 프로토콜

MCP는 기본적으로 JSON-RPC 2.0 포맷을 사용합니다. HTTP 요청의 Body나 SSE 메시지 데이터가 모두 JSON-RPC 형태여서 디버깅할 때 이 구조를 눈여겨봐야 했습니다.

초기 연결(Handshake) 과정:

1. Client → Server (initialize): 클라이언트가 먼저 Protocol Version과 Capabilities(로깅, 샘플링 등)를 담아 initialize 요청을 보냅니다.
2. Server → Client (Result): 서버가 자신의 Protocol Version과 지원하는 기능(Capabilities)을 응답합니다.
3. Client → Server (notifications/initialized): 클라이언트가 “확인했다”는 의미로 initialized 알림을 보냅니다.

이 3단계가 완료되어야 비로소 tools/list나 tools/call 같은 실제 명령을 주고받을 수 있다는 점이 중요했습니다.

[출처]

• https://modelcontextprotocol.io/docs/getting-started/intro
• https://playmcp.kakao.com/