바이브코딩으로 간단한 mcp 서버 만들기

지난번에 한 번 mcp 연결하는 방법을 설명드렸었죠.

 

 

Claude에서 처음 공개했던 정확한 MCP의 개념을 정리해본적이 없는 것 같아서 알려진 것을 토대로 작성해보겠습니다.

 

 

MCP Server란, 표준화된 프로토콜 인터페이스를 통해서 AI application에 어떠한 기능을 수행할 수 있도록 하는 프로그램입니다.

 

 

MCP Server는 Tools, Resources, Prompts라는 세 가지 영역으로 구성됩니다.

• Tools: LLM이 직접 호출하는 함수. 사용자의 요청에 따라 언제 어떤 것을 사용할지 LLM이 결정
  • Model이 통제
  • 지정된 입력과 출력 형식을 통해 수행할 작업을 정의
  • Tools의 작업은 두가지 방식 존재
    1. 사용 가능한 Tools 목록을 보는 방식
    2. 사용 가능한 Tools 중 context상 필요한 특정 도구를 실행
• Resources: read-only 권한으로 context에 데이터(db, 파일내용, api 문서)를 제공하는 소스 원천
  • AI가 해당 어플리케이션 영역에서만 사용하는 문맥을 이해하는데 필요한 데이터를 제공합니다.
  • 두 가지 패턴을 지원합니다.
    1. 직접 데이터를 가리키는 URI를 제공
    2. 리소스 템플릿 제공: [예시] travel://activities/{city}/{category} - 와 같은 동적URI 등
• Prompt: 모델이 언제 Tools와 Resourecs를 이용할지 지시하는 미리작성된 지침 규격
  • 사용자 통제

 

 

 

 

 

mcp서버 개발 관련 공식링크를 보면 기반이 STDIO와 HTTP인 경우로 나뉘어지는데 오늘은 간단한 예제이므로 HTTP 기반으로 만들겠습니다.

 

 

아니 블로거님. HTTP면 REST api나 홈페이지를 만들어야 하는 것 아닌가요?

-> 네 맞습니다. 어떤 기능을 발휘하는 스펙이 있어야하고 HTTP 프로토콜 기반이라면 REST API 가 대표적이라고 볼 수 있습니다. 참고로, 데이터 전달 방식에 따라 streamable HTTP 방식이 가장 권장됩니다. 하지만 REST API 를 새로 streamable하게 개발 또는 변경하는 것보다는, 기존에 개발되어있는 REST API 중에 하나를 이용해서 진행하겠습니다.

 

저는 개발된 서버의 swagger로 바이브코딩을 할 것이고 여러분들은 Pet store 같은 공개된 swagger를 이용하거나 기존에 개발하신 rest api의 문서화가 잘되어있다면 그 것의 swagger를 이용하셔도 되겠습니다.

 

Pet Store sample의 github url: https://github.com/swagger-api/swagger-petstore?utm_source=chatgpt.com

위 페이지 내에 Pet Store Sample 서버를 설치구동하는 방법이 나와있고, Readme.md에 보시면 swagger.yaml을 바로 보실 수 있습니다.

 

GitHub - swagger-api/swagger-petstore

 

[준비: ai agent client - antigravity/claude/chatgpt 중 하나]

cli로 안하고 client로 진행하지만, cli로 하셔도 큰 차이는 없습니다. 요즘은 antigravity로 작업해보고 있어서 antigravity로 하겠습니다만, claude나 gpt client도 메뉴만 ui나 이름이 조금씩 다를뿐 방식은 마찬가지 이니 따라오시면 되겠습니다.

 

1. 작업공간 준비

작업공간에 준비한 swagger.yaml을 복사해둡니다.

 

md파일이나 프롬프트로 대략 다음 문맥 유형, 단계를 거쳐 요구를 하시면 되겠습니다.

• [swagger.yaml 파일의 경로]에 mcp 서버를 만들고 싶은 application의 swagger.yaml이 있다
• mcp로 쓰고싶은 기능설명 - 저같은 경우는 재직사 솔루션 관련 문서 핸들링을 많이하기 때문에 솔루션 내 문서 보관 폴더 등을 조회하고 폴더 내 문서목록을 보는 기능, 해당 폴더에 문서를 업로드 하는기능, 문서를 요약하는 기능 등을 만들어 달라고 했었습니다. Pet Store를 사용하신다면 아주 간단하게 하셔도 되겠습니다. "해당 yaml 내에는 Pet Store를 운영하기 위해 필요한 기능들이 들어간다. 상점 주인으로서 필요한 기능들만 추려서 MCP 서버를 개발해줘, 어떤 기능을 추렸는지와 그 기능을 사용한 이유를 알려줘"
• 개발이 완료되었을때, swagger.yaml을 요약시킴과 동시에 mcp서버로 구현된 기능 목록을 달라고하고 부족한 부분이 있으면 추가해달라고하면 되겠습니다.
• 개발단계가 마무리되면 mcp server를 빌드하는방법, 그리고 agent에 추가하는 방법을 문서화 해달라고 하시면 되겠습니다.
• 토큰이 조금 더 들기는하지만 계획 문서를 파일로 저장해달라고하면 심지어 개발언어를 몰라도 따라가기 좋습니다. claude 공식문서에 있는 python 예제는 다른 글에서 다루거나 넘어갈 것이고, ts나 다른언어로도 개발되므로 아는 언어가 있다면 사전에 ai와 대화를 통해 지원되는 언어 목록을 받아서 그중에서 하나를 명시해주면 좋습니다.
• "개발 소스는 A폴더, 계획, To-do List 등 사전 문서작업사항은 B폴더, 중간단계 혹은 초기 개발 이후 수정을 할 때 마다  작업진행 상황 정리 문서는 C폴더에 정리해줘, 완료 후 기능명세서, mcp server 빌드, 설치 방법, 사용자가이드가 담긴 사후 문서는 D폴더에 정리해줘" 라고 남길 필요가 있고, 저러한 문서들을 만들어 달라는 내용도 프롬프트나 md파일에 담는 것을 권장드립니다. 
• 우리는 이제 C폴더를 보면서 ai가 이상하게 개발한 부분이 있는지, 초기 개발 이후 디버그 단계에서 수정해야될 부분은 없는지 팔로우 하면 됩니다. 

 

 

 

이 정도만해도 꽤 많은 노하우를 알려드렸다고 생각하니 중간에 여러 과정들은 넘어가겠습니다. 

 

자 이제 개발이 완료되었죠. 사용하시는 ai에 따라 다르겠습니다만, 저는 antigravity로 진행했고, 여기에 연결할 수 있는 방법을 작성해달라고 해두었기 때문에 antigravity에 mcp서버를 연결할 수 있는 방법을 전달 받았습니다. Windows PC 기준 [%USERPROFILE%\.gemini\config\mcp_config.json]에 추가하면 된다고 제가 알고있는 바와 같은 방식 형식과 함께을 안내해주었습니다. 방법에 따라 여기에 내용을 추가했습니다.

 

 

그리고 antigravity로 돌아와서, 좌측하단의 [Settings] -> 좌측 탭의 [Customizations] -> [Installed MCP Servers]에서 [Refresh]를 클릭합니다. 그러면 개발 과정이 잘 진행된 경우 초록색 동그라미 표시와 함께 MCP Server가 연결됩니다.

 

 

 

 

이제 chat에서 살짝 ping 쏴봅니다.

 

연결되었다고 하네요.

 

저는 이전에도 여러개를 했지만 조금 완성도 있는 결과물을 보여드리기 위해 문서 저장소 관련으로 개발된 시스템의 MCP Server 구현을 진행해보았습니다. 지정한 어떤 문서 본문을 달라고해보겠습니다. 저는 oauth2 authorization code 방식 인증도 구현해서 mcp 관련 기능을 수행할때 최초 한 번은 인증창도 뜹니다.