Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 15. 17:53

MCP와 AI 에이전트를 사용하여 정적 사이트를 완전한 에이전트 기반 AI 코스 사이트로 전환한 방법

요약

정적 사이트의 효율성을 유지하면서 MCP와 AI 에이전트를 활용해 동적인 학습 경험을 제공하는 아키텍처를 소개합니다. 콘텐츠 레이어와 에이전트 레이어를 분리하여 사용자의 진행 상황을 추적하고 문맥에 맞는 답변을 제공하는 방식을 다룹니다.

핵심 포인트

  • 정적 사이트(Quarto)와 AI 에이전트 계층의 분리 아키텍처 구축
  • MCP를 활용하여 에이전트가 사이트 콘텐츠 및 사용자 상태에 접근
  • 단순 챗봇을 넘어 학습자의 진행 상황을 검증하는 에이전트 구현
  • 웹, CLI, IDE(Cursor) 등 다양한 환경에서 일관된 학습 경험 제공

우리가 First Break AI를 구축하기 시작했을 때, 결과적으로 장점이 된 제약 사항이 하나 있었습니다. 우리는 레슨, 블로그, 오피스 아워(office hours), 로드맵, 문서 등을 갖춘 실제 코스 사이트를 원했지만, 단지 콘텐츠를 제공하기 위해 전체 웹 애플리케이션을 실행하고 싶지는 않았습니다. LMS(Learning Management System)도 필요 없었고, 커리큘럼을 위해 Next.js로 다시 작성할 필요도 없었으며, 모든 요청마다 서버 렌더링 페이지를 생성할 필요도 없었습니다. 정적 사이트(Static sites)는 빠르고 저렴하지만, 사이트 방문자와 상호작용하거나, 질문에 답하거나, 학습 여정을 도와줄 수는 없습니다. 우리는 AI를 단순한 FAQ 봇으로 취급하는 것을 멈춰야 한다는 것을 깨달았습니다. 대신 AI를 사이트 전체를 실행하는 에이전트 계층(agentic layer)으로 취급해야 합니다.

우리는 Quarto를 선택했습니다. .qmd 파일을 작성하고 quarto render를 실행하면 정적 HTML을 얻을 수 있습니다. 우리는 그 결과물을 Cloudflare Pages에 배포합니다. Pages는 로딩이 빠르고, URL은 깔끔하게 유지되며, 모든 것은 Git에 저장됩니다. 학습자들은 저장소(repo)를 포크(fork)하여 함께 따라올 수 있습니다. 무료 오픈 코호트(cohort)를 위해서는 바로 그 기반이 적절했습니다.

하지만 이 정적 사이트에는 동일한 문제가 있었습니다. 사용자가 누구인지 기억하지 못하며, 진행 상황을 확인하거나 다음에 무엇을 해야 할지 알려줄 수 없다는 점입니다. 그 위에 일반적인 챗봇 위젯을 붙이면 답변은 얻을 수 있지만, 당신의 콘텐츠에 기반한 답변은 아니며, 당신의 저장소를 검증하거나 터미널과 브라우저 간의 진행 상황을 동기화할 수 있는 에이전트도 아닙니다.

그래서 우리는 다른 질문을 던졌습니다. 사이트는 정적으로 유지하되, **AI 에이전트(AI agents)**가 그 위의 동적인 계층이 된다면 어떨까?

그것이 바로 First Break AI가 우리가 완전한 에이전트 기반(fully agentic) 코호트라고 부르는 것이 된 방식입니다. 사이트를 에이전트로 교체했기 때문이 아니라, 이제 에이전트가 문맥(context)에 따라 질문에 답하고, 루브릭(rubrics)에 따라 작업을 검증하며, 진행 상황을 추적하고, IDE 내부에서 나타나기 때문입니다. HTML은 여전히 평범한 Quarto 출력물입니다. 하지만 학습 경험은 그렇지 않습니다.

"AI 기반" 코스의 문제점

대부분의 "AI 기반" 코스는 다음 두 가지 중 하나를 의미합니다. 코스에 대해 아무것도 모르는 챗봇이거나, 첫날부터 특정 스택에 사용자를 가두는 플랫폼입니다.

우리는 둘 다 원하지 않았습니다. 우리는 학습자들이 빠른 정적 페이지(static pages)로서 레슨을 읽고, "GGUF가 무엇인가요?"라고 질문했을 때 우리의 레슨 콘텐츠로부터 답변을 얻으며, 1단계가 실제로 통과되었는지 확인하기 위해 터미널에서 명령어를 실행하고, 우리가 오피스 아워(office hours)에서 사용하는 것과 동일한 도구들을 Cursor에 설치하기를 원했습니다. 웹사이트에 있든, CLI에 있든, 혹은 Claude와 페어 프로그래밍(pair-programming)을 하든 상관없이 동일한 코호트(cohort)와 동일한 루브릭(rubric)을 제공하는 것입니다.

이를 위해서는 **콘텐츠(content)**와 **에이전시(agency)**가 분리되어 있으면서도 의도적으로 연결된 아키텍처가 필요했습니다.

구성 요소들이 결합되는 방식

두 개의 레이어로 생각해보세요.

**콘텐츠 레이어(The content layer)**는 가장 좋은 의미에서 지루합니다. Quarto가 사이트를 구축하고, Cloudflare Pages가 이를 서빙합니다. 로드맵이나 Hugging Face의 레슨을 열 때, 여러분은 미리 렌더링된 HTML을 읽게 됩니다. Google은 실제 텍스트를 인식합니다. 레슨을 읽기 위해 JavaScript가 필요하지 않습니다. 이는 속도, 접근성, 그리고 SEO(검색 엔진 최적화) 측면에서 매우 중요합니다.

**에이전트 레이어(The agentic layer)**는 콘텐츠 내부에 있는 것이 아니라, 그 옆에 위치합니다. Cloudflare Worker가 우리의 MCP 서버 — AI 어시스턴트가 코호트 도구가 필요할 때 호출하는 Model Context Protocol 엔드포인트 — 를 호스팅합니다. FetchLens.ai는 사이트 내 "무엇이든 물어보세요(Ask Anything)" 위젯을 구동하며, 에이전트들이 사이트를 어떻게 사용하는지에 대한 관측성(observability)을 제공합니다. 작은 npm 패키지인 @aiedx/firstbreakai는 학습자에게 오프라인 체크를 위한 CLI와 로컬 MCP 서버를 제공합니다. Discord OAuth는 신원(identity)을 하나로 묶어줍니다. 한 번 로그인하면 동일한 학습자 기록이 웹사이트, 터미널, 그리고 위젯에서 여러분을 따라다닙니다.

두 번째 레이어의 그 어떤 것도 Quarto를 대체하지 않습니다. 우리는 .qmd를 React 컴포넌트로 변환하거나 레슨을 데이터베이스로 옮기지 않았습니다. 우리는 정적 페이지가 실제로 무언가를 수행하는 에이전트들과 대화할 수 있도록 HTTP 엔드포인트, 스크립트, 도구와 같은 **연결 조직(connective tissue)**을 추가했을 뿐입니다.

이를 쉬운 언어로 설명하면 다음과 같습니다:

  1. 학습자가 레슨을 읽습니다 (정적 HTML, 빠름).
  2. 질문이 생기면 → FetchLens 위젯이 Worker를 호출합니다 → 에이전트가 공개 웹(open web)이 아닌 코호트 지식(cohort knowledge)을 바탕으로 답변합니다.
  3. 연습 문제를 마치면 → firstbreakai validate 1이 로컬 루브릭(rubric) 체크를 실행합니다 → 로그인 상태라면 결과가 프로필에 동기화될 수 있습니다.
  4. Cursor에서 작업하면 → 원격 MCP URL이 IDE 에이전트에게 코호트가 다른 모든 곳에서 제공하는 것과 동일한 ask, find, validate, next 도구를 제공합니다.

동일한 두뇌, 다양한 접점. 사이트는 정적으로 유지됩니다. 에이전트는 공유 인프라입니다.

계층별 분석 — 우리가 실제로 구축한 것

모든 페이지에서 무엇이든 질문하기 (Ask Anything)

가장 가벼운 진입점은 위젯입니다. Quarto가 페이지를 렌더링한 후, 우리는 플로팅(floating) "Ask Anything" 버튼을 마운트하는 지연된 스크립트(deferred script)를 포함합니다. 이 버튼은 Worker 상의 FetchLens 기반 엔드포인트(endpoint)를 가리킵니다. 학습자 관점에서는 코호트 전체를 읽은 튜터처럼 느껴집니다. 실제로 그렇기 때문입니다.

우리는 Quarto가 페이지를 빌드하는 방식을 변경하지 않았습니다. 사이트 수준에서 포함(include) 항목을 추가했을 뿐입니다:

<script src="/public/scripts/fba-lens-widget.js" defer
  data-endpoint="https://fba-mcp.throbbing-thunder-4d33.workers.dev/widget/mcp"
  data-button-label="Ask Anything"></script>

정적 전달 방식은 변경되지 않았습니다. 에이전트는 비동기적으로 로드됩니다. 스크립트가 실패하더라도 레슨은 여전히 작동합니다.

IDE에서의 MCP

동일한 Worker가 HTTP를 통해 공개 MCP 서버를 노출합니다. Cursor, Claude Desktop, Claude Code 또는 OpenAI Codex를 사용한다면, URL 하나만 붙여넣는 것으로 AI 어시스턴트가 코호트 도구(질문하기, 레슨 찾기, 제출물 검증, 다음 단계 제안)를 갖게 됩니다.

Cursor의 경우, 설정은 ~/.cursor/mcp.json에 몇 줄만 추가하면 됩니다:

{
  "mcpServers": {
    "fba-cohort": {
...

이 순간, 코호트(cohort)는 단순히 "방문하는 웹사이트"에서 "에이전트가 호출할 수 있는 인프라"로 변모했습니다. Cursor에서 자신의 Quarto 블로그를 디버깅 중인 학습자는 탭을 전환하지 않고도 에이전트에게 코호트 요구 사항을 확인해 달라고 요청할 수 있습니다. 이것이 바로 실전에서의 에이전트 기반 학습 (agentic learning)입니다. 사이드바에 있는 챗봇이 아니라, 사람들이 이미 작업하고 있는 곳에 도구가 연결되어 있는 형태입니다.

실제로 검증하는 CLI

어떤 체크 항목들은 LLM (대규모 언어 모델)의 판단에 맡겨두어서는 안 됩니다. 1단계에서는 GitHub에 Quarto 블로그를 배포할 것을 요구합니다. _quarto.yml 파일을 생성했나요? .qmd 파일이 있나요? Git 원격 저장소(remote)가 GitHub를 가리키고 있나요? 이것들은 파일 시스템의 사실(facts)입니다. 우리는 이를 루브릭 (rubrics)에 인코딩하여 로컬에서 실행합니다:

npm install -g @aiedx/firstbreakai
firstbreakai doctor      # Git, Python, Quarto, HuggingFace CLI — 환경 무결성 확인
firstbreakai validate 1  # 1단계에 대한 루브릭 체크
...

AI 에이전트는 개방형 질의응답 (Q&A)을 처리합니다. 루브릭은 합격/불합격을 처리합니다. 이러한 분리는 에이전트가 단계 사이의 모호함을 학습자에게 안내할 수 있게 하면서도, 검증 과정에서 환각 (hallucination)에 의한 "제가 보기엔 괜찮아 보입니다"와 같은 잘못된 판단 없이 정직함을 유지하게 합니다.

또한 이 CLI는 npm에 @aiedx/firstbreakai로 게시되어 있으므로, 전역 설치 없이도 npx @aiedx/firstbreakai doctor를 사용할 수 있습니다. 터미널을 선호하든 IDE를 선호하든 동일한 패키지와 동일한 MCP 도구를 사용합니다.

사이트를 앱으로 만들지 않고 구현한 식별 (Identity)

정적 사이트에는 세션 (sessions)이 없습니다. 우리는 단지 로그인을 위해 Node 백엔드를 덧붙이고 싶지 않았습니다. Discord OAuth는 Worker에서 실행됩니다. 내비게이션 바에서 "로그인"을 클릭하고, 인증한 뒤, localStorage에 토큰을 저장하면 위젯과 CLI 모두 해당 식별 정보를 사용할 수 있습니다. 어떤 단계를 검증했는지, 어떤 레슨을 완료로 표시했는지와 같은 진행 상황은 Worker 뒤편의 D1에 저장됩니다.

Quarto 저장소는 여전히 모든 사용자에게 동일한 HTML을 빌드합니다. 인증은 오버레이 (overlay)일 뿐입니다. 이것은 우리에게 매우 중요한 부분이었습니다. 커리큘럼은 개방되어 있고 포크 (fork)할 수 있는 상태로 유지되며, 개인화는 유료 결제 장벽 (paywall)이 아닌 선택 사항입니다.

우리가 의도적으로 하지 않은 것들

우리는 코호트 (cohort)를 React나 Next.js로 다시 구축하지 않았습니다. Quarto는 긴 호흡의 레슨과 블로그 형태의 학습 경로를 구축하기에 적합한 도구였습니다.

우리는 일반적인 ChatGPT iframe을 삽입하고 이를 "AI 기반"이라고 부르지 않았습니다.

우리는 로그인을 통해 레슨을 숨기지 않았습니다. 자료는 공개되어 있습니다. Discord와 인증 (auth) 시스템은 커뮤니티와 학습 진도 관리를 위해 존재할 뿐, 콘텐츠를 차단하기 위한 용도가 아닙니다.

우리는 정적 사이트를 "똑똑하게" 만들려고 시도하지 않았습니다. 대신 **에이전트 (agents)**를 똑똑하게 만들었고, 그들을 정적 콘텐츠로 향하게 했습니다.

이 스택이 프로덕션 환경에서 유지될 수 있었던 이유

속도는 양호하게 유지되었습니다. 에이전트가 콘텐츠 로드 이후에 실행되기 때문입니다. SEO (검색 엔진 최적화) 또한 양호하게 유지되었습니다. 크롤러가 JavaScript를 기다리는 빈 껍데기가 아니라, 전체 HTML, 코스를 위한 JSON-LD, 그리고 홈페이지의 FAQ 스키마 (schema)를 가져갈 수 있기 때문입니다.

비용은 낮게 유지되었습니다. 정적 파일을 위한 Cloudflare Pages, 에이전트 계층 (agentic layer)을 위한 Worker 및 D1을 사용했습니다. 레슨 전달을 위해 항상 켜져 있어야 하는 앱 서버가 필요하지 않았습니다.

가장 중요한 점은, 모델이 코호트 규모에 맞춰 확장되었다는 것입니다. 레슨을 추가하는 것은 여전히 ".qmd 파일을 작성하고, 렌더링하고, 배포하는" 과정입니다. 에이전트 기능을 추가하는 것은 "MCP 서버에 도구 (tool)를 노출하거나 루브릭 (rubric)을 확장하는" 것입니다. 콘텐츠와 에이전시 (agency)가 별도의 트랙에서 진화하기 때문에, 소규모 팀이 인프라에 매몰되지 않고도 코호트를 운영할 수 있습니다.

Quarto는 콘텐츠 엔진입니다. AI 에이전트는 학습 엔진입니다. 이 둘이 결합되면 댓글창이 달린 비디오 플랫폼보다, 확장 가능한 조교 (teaching assistant)에 더 가까워집니다.

직접 시도해보고 싶다면

First Break AI는 무료입니다. 별도의 신청이나 선수 학습 조건이 없습니다. 코호트 01은 2026년 5월부터 7월까지 진행되며, 그 이후에도 모든 내용은 온라인에 유지됩니다.

로드맵 (roadmap) 또는 레슨 0 (Lesson 0)부터 시작하세요. npm install -g @aiedx/firstbreakai 명령어로 CLI를 설치하세요. IDE에 MCP 서버를 추가하세요. 사람의 개입 (humans in the loop)도 원한다면 Discord에 참여하세요.

우리는 여전히 반복적인 개선(iterating)을 진행 중입니다 — 로그인 시 로드맵 체크마크 표시, 더 많은 검증 루브릭(validation rubrics), 에이전트 트래픽에 대한 더 깊은 FetchLens 관측성(observability) 등을 준비하고 있습니다. 하지만 핵심 아이디어는 안정적입니다: 콘텐츠를 위한 정적 사이트(static site), 행동이 필요한 모든 것을 위한 에이전트(agents).

만약 여러분이 이와 유사한 것 — MCP, 에이전트 기반 도구(agentic tooling), 생동감이 느껴져야 하는 정적 사이트 — 을 구축하고 있다면, 여러분이 어떤 방식으로 접근하고 있는지 진심으로 듣고 싶습니다. 그리고 만약 AI 분야에서 첫 기회를 찾고 있다면, 코호트(cohort)가 열려 있습니다.

First Break AI는 AIEdx에 의해 구축되었습니다. 에이전트 기반 인프라(Agentic infrastructure)는 FetchLens.ai를 통해 구동됩니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0