자사 CMS에 MCP 서버 구축, 개발자 문서까지 공개【설계 판단】

MCP(Model Context Protocol)란?

MCP(Model Context Protocol)란 AI가 외부 시스템과 데이터를 직접 조작하기 위한 공통 규격입니다. API를 AI가 이해할 수 있는 “도구”의 형태로 번역해, Claude·Cursor 등 지원 클라이언트에서 그대로 호출할 수 있게 합니다.

안녕하세요. Webflow 전문가에서 AI 웹사이트 제작·AI 개발로 주 무대를 넓혀가고 있는 마사토입니다. 일본 미야기현 시오가마시에서 웹 제작 회사 Webharu를 운영하고 있습니다.

자사가 운영하는 사이트 운영 기반의 CMS에 REST API와 MCP 서버를 구축하고, 개발자용 문서까지 일반 공개했습니다. 이 글은 그 설계 판단을 그대로 기록한 것입니다. “MCP 서버는 어떻게 만드는가”, “AI에게 자사 시스템을 맡겨도 괜찮은가”라는 질문에 구현한 쪽에서 답합니다.

결론부터 쓰겠습니다.

AI 도입이 잘 되지 않는 원인의 대부분은 AI의 성능이 아니라 AI가 자사 데이터에 닿지 못한다는 점입니다. 연결 지점(API)와 AI의 손(MCP)만 준비하면, 지금 사내에서 쓰고 있는 AI가 그대로 실무를 움직입니다. 그리고 가장 시간을 들여야 할 곳은 구현이 아니라 “무엇을 만지지 못하게 할 것인가”의 설계입니다.

무엇을 만들었는가

만든 것은 CMS의 글을 외부에서 조작하기 위한 입구입니다. 입구는 2개입니다.

• REST API — 글의 생성·조회·수정·삭제, 카테고리 목록, 이미지 업로드. Bearer 인증의 API 키로 호출합니다
• MCP 서버 — 같은 조작을 Claude Code·Claude Desktop·Cursor 같은 AI 클라이언트에서 직접 호출할 수 있는 형태로 만든 것. 툴은 8개입니다

이 둘은 모두 CMS 본체와 완전히 동일한 발행 파이프라인을 지납니다. 브라우저 에디터로 써도, API로 보내도, AI에게 지시해도 검증·이력·감사 로그는 같습니다. 여기를 나누면 “에디터에서는 막히는데 API로는 통과된다”는 구멍이 생기므로 구현을 공통화했습니다.

글을 published로 바꾸는 순간, 정적 사이트의 빌드와 배포까지 자동으로 실행됩니다. Webhook을 짜거나 CI를 설정할 필요가 없습니다.

API만으로는 부족해 MCP까지 만든 이유

“API가 있으면 AI가 쓸 수 있는 것 아닌가”라고 생각할 수 있습니다. 실제로는 한 단계의 번역이 더 필요합니다.

MCP(Model Context Protocol)는 AI가 외부 시스템을 조작하기 위한 공통 규격입니다. API가 “시스템의 입구”라면, MCP는 “AI가 그 입구를 쓰기 위한 손”에 해당합니다.

API만 있는 상태로 AI에게 쓰게 하려면 엔드포인트 설명·인증 전달 방법·응답 읽는 법을 매번 프롬프트로 가르쳐야 합니다. 대화를 넘어가면 잊히고, 사람마다 쓰는 방식이 달라 결과도 흔들립니다. MCP로 만들어 두면 툴 목록과 인수의 형태를 AI 쪽이 구조로 이해하기 때문에 그 편차가 사라집니다.

또 하나 큰 점은 규격이 공통이라는 것입니다. 특정 AI 서비스 전용으로 만들면 갈아타는 때마다 다시 만들어야 합니다. MCP는 지원 클라이언트가 계속 늘고 있으므로 AI 쪽을 바꿔도 연결 지점은 그대로 씁니다. 오래 쓰는 업무 시스템일수록 이 부분이 크게 작용합니다.

AI에게 키를 맡길 때 설계로 막은 3가지

이번 구현에서 가장 고민한 부분입니다. 시스템을 AI에 연결하면 편리함과 동시에 “임의로 삭제된다·임의로 공개된다”는 위험이 생깁니다. 그리고 이것은 운영 규칙으로는 막을 수 없습니다. “AI에게 정중히 지시합시다”로 막을 수 있는 사고가 아니기 때문입니다.

① 기본값을 안전한 쪽에 둔다

상태를 명시하지 않은 생성은 반드시 초안이 됩니다. AI가 대화의 흐름에서 임의로 공개하는 일은 없습니다. 공개하고 싶을 때만 명시적으로 지정하게 합니다. 반대로 만들면 사고가 난 뒤에 되돌릴 수 없습니다.

② 키가 닿는 범위를 처음부터 좁힌다

API 키는 1개 사이트분의 권한만 갖습니다. 다른 사이트의 데이터에도, 관리 기능에도 전혀 닿지 않습니다. “일단 전부 만질 수 있는 키를 주고, 쓰는 쪽이 조심한다”는 설계를 하지 않는 것이 중요합니다.

③ 모든 조작을 기록하고, 언제든 멈출 수 있게 한다

언제·어느 키가·어느 글에 무엇을 했는지는 모두 감사 로그에 남습니다. 키는 정지하면 그 자리에서 효력을 잃습니다. 또한 누가 발급한 키인지도 기록하기 때문에 담당자가 바뀌어도 나중에 추적할 수 있습니다.

이 “누구의 키인가”는 사소해 보이지만 중요합니다. 키가 계정과 무관하게 살아있으면 “로그인은 막았는데 외부 API로는 아직 쓸 수 있다”는 상태가 만들어집니다. 그러지 않도록 멤버를 정지하면 그 사람이 발급한 키도 자동으로 정지되게 했습니다. 삭제가 아니라 정지라서 오작동해도 되돌릴 수 있습니다.

외부에 HTML을 만들게 하지 않는다는 판단

사소해 보이지만 설계 판단으로는 효과가 확실한 부분입니다. 글 본문은 Markdown만 받고, HTML 변환은 서버 쪽에서 처리합니다.

외부에서 HTML을 그대로 보낼 수 있게 설계하면 깨진 마크업과 예상하지 못한 태그가 운영 사이트에 섞입니다. AI가 생성한 것을 그대로 흘려보낸다면 더욱 그렇습니다. 입구를 Markdown으로 좁혀 두면 어디에서 온 글이든 사이트의 모양은 일정하게 유지됩니다. “AI에게 맡긴다”는 것은 맡길 범위를 정하는 일과 한 쌍입니다.

문서는 AI가 읽는다는 전제로 쓴다

이번에 가장 시대가 바뀌었다고 느낀 곳입니다. 개발자 문서를 만들 때 독자는 사람만이 아닙니다.

준비한 것은 3종류입니다. 사람이 읽는 레퍼런스(HTML), AI에게 요점을 전달하는 llms.txt, 그리고 사양 전문을 1개 파일로 정리한 llms-full.txt. 마지막 파일은 도입하는 쪽의 AI 에이전트에게 그대로 읽혀 구현시키기 위한 것입니다.

이것이 있으면 쓰는 쪽은 “문서를 읽고 이해한 뒤에 코드를 쓴다”는 과정이 필요 없습니다. AI에게 전문을 주고 “이걸 써서 글을 올리는 구조를 만들어”라고 말하면 움직입니다. 문서의 품질이 그대로 도입의 쉬움이 된다는 구조입니다.

【2026년 8월 추가】 두 번째 MCP 대응: 메일 API HaruMail로 설계를 진화시켰다

이 CMS 구현 후, 두 번째 MCP 대응 제품으로 메일 송수신 API HaruMail을 개발했습니다. 첫 번째 설계를 바탕으로 진화시킨 점이 2가지 있습니다.

• 위험 조작의 2단계화: 메일 발송은 AI의 잘못된 조작이 가장 무서운 조작입니다. 그래서 발송 계열 툴은 모두 “초안 생성”까지만 할 수 있게 하고, 실제 발송은 confirm_send라는 별도 툴로만 실행되도록 설계했습니다. “AI가 조심하게 한다”가 아니라 애초에 한 번에 발송할 수 없는 API 설계로 사고를 구조적으로 막습니다.
• 툴 단위의 최적화: 외부 SaaS의 범용 MCP를 시험했을 때, 연결하는 것만으로 많은 정보를 읽어들여 컨텍스트의 대부분을 소모해 실용에 이르지 못한다는 실측이 있었습니다(Webflow MCP 검증 글). 이 배움에서 툴 수를 줄이고 반환하는 정보를 작게 유지하는 것을 설계 원칙으로 삼고 있습니다.

2개를 구현해 보고, SaaS의 MCP 대응에는 재현 가능한 “틀”이 있다는 것을 알게 됐습니다. 틀의 전체는 SaaS를 MCP 대응시키는 방법에 정리해 두었습니다.

이 구조를 그대로 상품으로 만듭니다

여기까지는 자사 CMS 이야기지만, 필요한 요소는 업종을 가리지 않습니다.

• 밖에서 읽고 쓸 수 있는 API
• AI가 그것을 도구로 쓸 수 있게 하는 MCP
• AI 자신이 읽을 수 있는 문서
• 그리고 무엇을 만지지 못하게 할 것인가의 설계

“AI를 도입했는데 결국 스크린샷을 붙여 복붙하고 있다” — 이 상태에서 벗어나기 위해 부족한 것은 대개 이 4가지입니다. Webharu에서는 이 한 세트를 API·MCP 개발로 진행하고 있습니다. 이미 API가 있다면 MCP를 씌우는 것만으로 충분하고, 없다면 연결 지점부터 만듭니다.

실물은 공개 문서에서 그대로 보실 수 있습니다. 제안서 속의 그림이 아니라 지금 움직이고 있는 것입니다.
→API·MCP 개발 서비스 상세

자주 묻는 질문

MCP와 API는 무엇이 다른가요?

API는 “시스템의 입구”, MCP는 “AI가 그 입구를 쓰기 위한 손”입니다. API만으로도 프로그램에서는 조작할 수 있지만, AI에게 쓰게 하려면 인증 전달 방법과 응답 읽는 법을 매번 설명해야 합니다. MCP로 만들면 툴 목록과 인수의 형태를 AI가 구조로 이해하므로 설명 없이도 안정적으로 움직입니다.

AI가 임의로 데이터를 삭제하거나 공개하지는 않나요?

설계로 막습니다. 상태를 명시하지 않은 생성은 반드시 초안이 되게 하고, 키가 닿는 범위는 1개 사이트분으로 좁히며, 모든 조작을 감사 로그에 기록합니다. 키는 정지하면 그 자리에서 효력을 잃고, 누가 발급한 키인지도 기록됩니다. 운영 규칙이 아니라 기본값과 권한 범위로 지키는 것이 원칙입니다.

MCP 서버를 자체적으로도 만들 수 있나요?

사양이 공개되어 있으므로 개발 리소스가 있다면 만들 수 있습니다. 다만 구현 자체보다 어떤 조작을 허용하고 무엇을 만지지 못하게 할 것인가라는 권한 설계가 더 어렵고, 사고도 거기서 생깁니다. 기존 시스템에 API가 없다면 먼저 연결 지점 설계부터 시작해야 합니다.

이미 API가 있다면 MCP만 추가할 수 있나요?

가능합니다. 기존 API의 사양이 정리되어 있다면 그 위에 MCP 서버를 씌우는 것만으로 충분합니다. 저희는 그 구성을 단독 플랜으로 준비해 두었습니다.

llms.txt란 무엇인가요?

사이트나 서비스의 사양을 AI가 읽기 쉬운 형태로 정리한 텍스트 파일입니다. 개발자 문서에 함께 두면 도입하는 쪽의 AI 에이전트가 그대로 읽어 구현할 수 있어, “문서를 읽고 이해한 뒤에 코드를 쓴다”는 과정이 필요 없어집니다.