AI 에이전트가 제품 데모를 구축할 수 있도록 원격 MCP 서버를 구축한 방법

저는 Demo My Product을 만들었습니다. 이 서비스는 스크린샷으로 클릭 가능한 제품 워크스루(walkthroughs)를 만듭니다. 가입하지 않고도 예시를 통해 클릭해 볼 수 있습니다: [https://demomyproduct.com/d/zs2pfbuwu2]

데모를 만드는 작업의 대부분은 반복적입니다. 스크린샷을 업로드하고 순서대로 배열합니다. 각 단계에 제목을 작성하고, 중요한 버튼 위에 핫스팟(hotspot)을 그리고, 툴팁(tooltip)을 작성합니다. 그런 다음 누군가 보기 전에 모든 이메일 주소를 흐리게 처리합니다. 이는 구조화되고 지루한 작업이었고, 저는 AI 에이전트가 이 작업을 수행하기를 원했습니다. 그래서 이 제품은 원격 MCP (Model Context Protocol) 서버와 함께 출시되었으며, Claude, Cursor 또는 ChatGPT가 사용자 대신 데모를 구축하고 게시할 수 있습니다.

본 포스트에서는 이것이 어떻게 구성되었는지 그리고 그 과정에서 제가 내린 결정들을 다룹니다.

에이전트가 작업하는 대상

먼저, 일반적인 용어로 데이터 모델을 설명하겠습니다. 데모는 단계 목록입니다. 각 단계는 핫스팟이 있는 이미지로 구성됩니다. 핫스팟은 툴팁과 클릭 액션(click action)을 가집니다: 다음 단계로 이동하거나, 아무 단계로든 점프하거나, 링크를 열거나, 데모를 종료하는 것입니다.

단계의 특정 영역을 흐리게 처리할 수 있습니다. 이 블러 처리는 원본 이미지 위에 겹쳐지는 것이 아니라 게시된 이미지에 렌더링되므로, 원본 픽셀이 시청자에게 절대 노출되지 않습니다. 게시된 데모는 공개 링크와 iframe 임베드(embed)를 얻으며, 단계별로 조회수, 완료율, 그리고 사람들이 이탈하는 지점을 보여주는 깔때기(funnel)가 제공됩니다.

모델은 작고 명시적이어서 에이전트가 이를 잘 추론할 수 있습니다.

• 사용자 기기에 설치하거나 업데이트할 것이 없습니다.
• 로그인은 브라우저에서 OAuth를 사용하므로, 아무도 API 키를 설정 파일에 붙여넣을 필요가 없습니다.
• 앱 내부에서 에이전트를 차단할 수 있습니다: 설정(Settings) → 연결된 에이전트(Connected agents) → 연결 해제(Disconnect). 그러면 즉시 접근 권한을 잃습니다.

전송 및 인증 (Transport and auth)

서버는 Streamable HTTP를 사용합니다: 단일 URL로 POST하는 JSON-RPC입니다. 토큰이 없는 요청은 표준 MCP 인증 체인지를 받습니다:

POST https://demomyproduct.com/mcp   (토큰 없음)
→ 401 {"jsonrpc":"2.0","error":{"code":-32000,"message":"missing authorization header"}}
→ WWW-Authenticate: Bearer resource_metadata="https://demomyproduct.com/.well-known/oauth-protected-resource/mcp", scope="demos"

이 보호된 리소스 메타데이터는 클라이언트를 인증 서버, https://demomyproduct.com/api/auth로 안내합니다. 해당 서버는 다음을 게시합니다:

• 클라이언트가 **동적 클라이언트 등록(dynamic client registration)**을 사용할 수 있게 하는 registration_endpoint를 제공하여, 아무도 클라이언트 ID를 미리 등록할 필요가 없습니다.
• DCR의 새로운 대안인 **클라이언트 ID 메타데이터 문서(client ID metadata documents)**에 대한 지원
• PKCE with S256
• 스코프 openid profile offline_access demos

규격(spec)을 준수하는 것이 모든 클라이언트에서

에이전트는 에디터에서 사용자가 할 수 있는 모든 것을 수행할 수 있습니다. 데모를 나열하고 생성하며, 스크린샷을 추가하고, 단계 제목을 작성하고, 핫스팟과 툴팁을 배치하며, 민감한 영역을 흐리게 처리하고, 데모 설정을 변경하고, 게시하는 작업까지 할 수 있습니다.

서버로 이미지 가져오기

스크린샷이 까다로운 부분입니다. 저는 이미지 데이터를 도구 인자(tool arguments)를 통해 전달하지 않습니다. 에이전트는 일회성 업로드 링크를 요청하고 이미지를 그곳으로 전송합니다 (PNG 또는 JPEG, 최대 10MB). 서버는 이를 단계로 변환합니다. 이 방식은 에이전트가 이미지 자체를 제공하기 때문에 로그인 뒤에 있는 페이지를 포함하여 모든 페이지에서 작동합니다.

공개 페이지 캡처 (Pro)

Pro 플랜에서는 두 번째 경로가 있습니다. 에이전트는 서버에 공개 URL을 제공합니다. 서버는 이를 브라우저에서 열고 스크린샷을 찍은 다음, 페이지의 버튼과 링크를 반환합니다. 이 마지막 부분이 가장 중요합니다. 이것이 없다면, 에이전트는 픽셀로부터 핫스팟 좌표를 추측해야 할 것입니다. 요소 목록(element list) 덕분에 핫스팟이 실제 버튼 위에 정확히 위치할 수 있습니다.

로그인이 필요한 페이지는 이런 방식으로 캡처할 수 없습니다. 그런 경우에는 에이전트가 자체 스크린샷 업로드로 대체합니다.

가드레일 (Guardrails)

에이전트는 사용자의 플랜 제한을 가지고 사용자처럼 행동합니다. 플랜이 허용하는 만큼 많은 데모를 게시할 수 있습니다. Pro에서 제공되는 페이지만 캡처할 수 있습니다. 게시하려면 인증된 이메일 주소가 필요합니다. 또한 호출당, 업로드당, 캡처당 속도 제한(rate limits)이 있습니다: 분당 120회 호출, 시간당 60회 업로드, 시간당 30회 캡처입니다.

에이전트가 생성하는 모든 것은 일반 에디터에 표시됩니다. 게시 전후로 검토하고 수정할 수 있습니다. 이것은 의도된 것입니다. 저는 에이전트의 결과물이 블랙박스가 되는 것을 원하지 않습니다. 사용자가 직접 고칠 수 있는 초안입니다.

스택 (Stack)

이 앱은 Next.js를 기반으로 구축되었으며, 결제는 Stripe를 사용합니다.

작동하는 프롬프트

제가 시작하는 프롬프트들은 다음과 같습니다:

• "이 폴더의 네 장 스크린샷을 사용하여 'Onboarding tour'라는 이름의 데모를 만들고, 각 버튼의 메인 버튼에 핫스팟을 추가한 후 게시해 주세요."
• "내 Billing tour 데모를 열고, 모든 단계에서 이메일 주소를 흐리게 처리(blur)한 다음 다시 게시해 주세요."
• "https://example.com/pricing과 https://example.com/signup을 두 단계 데모로 캡처하고, 회원가입 버튼에 툴팁(tooltip)을 지정한 다음 임베드 코드(embed code)를 알려주세요." (Pro)

직접 사용해 보기

에이전트를 연결하는 방법에 대한 가이드는 https://demomyproduct.com/help/build-demos-with-ai-agents에서 확인하실 수 있습니다. 무료 플랜은 카드 없이 데모 하나를 게시하며, 에이전트는 이 데모 위에서 작동합니다.

제가 가장 듣고 싶은 피드백은 에이전트 워크플로우에 관한 것입니다. 어떤 도구들이 빠졌다고 생각하시나요? 에이전트가 어디서 잘못하는지 알려주세요. 댓글을 남겨주시면 제가 여기서 답변드리겠습니다.