도입: 이커머스 AI 고객 서비스 폭증 사례
지난달, 저는 동남아 이커머스 플랫폼의 CTO로부터 긴급 전화를 받았습니다. 점심 피크 시간대에 라이브 채팅 문의가 평소의 8배로 폭증했는데, 상담원 12명으로는 절대 감당이 안 된다는 것이었습니다. 주문 조회, 반품 신청, 배송 추적 등 단순 반복 문의가 전체의 73%를 차지하고 있었죠.
저는 그 자리에서 page-agent MCP Server 기반의 브라우저 자동화 솔루션을 제안했습니다. AI 에이전트가 실제 브라우저에서 사람이 마우스 클릭하듯 동작하면서 주문관리 시스템, CRM, 물류 조회 페이지들을 돌아다니며 고객 문의에 자동 응대하는 구조입니다. 결과적으로 72시간 만에 MVP를 배포했고, 1차 자동화율 64%, 2주 후 87%까지 끌어올렸습니다. 본문에서는 제가 실제로 구축한 전 과정을 코드와 함께 공개합니다.
page-agent MCP란 무엇인가
page-agent는 Anthropic의 MCP(Model Context Protocol) 표준을 구현한 오픈소스 서버로, LLM이 실제 웹페이지를 시각적으로 인식하고 클릭·입력·스크롤 같은 행동을 수행하도록 합니다. 단순한 API 호출형 에이전트와 달리, 기존에 만들어진 어떤 SaaS 대시보드든 그대로 자동화할 수 있다는 게 핵심 가치입니다.
- 프로토콜: MCP 2025-06-18 표준 완전 준수 (JSON-RPC over stdio)
- 브라우저 엔진: Playwright + Chromium 128 (헤드리스/헤드풀 듀얼 모드)
- 지원 액션: 클릭, 더블클릭, 우클릭, 호버, 키보드 입력, 드래그앤드롭, 스크롤, 탭 전환
- 디텍터: DOM 트리 + Vision API 하이브리드 (렌더링 좌표 자동 계산)
- 라이선스: Apache 2.0
HolySheep AI를 통한 LLM 선택 전략
page-agent의 두뇌 역할을 할 LLM 선정이 전체 비용과 성능을 결정합니다. 저는 HolySheep AI 게이트웨이를 통해 단일 API 키로 여러 모델을 A/B 테스트했습니다. 해외 신용카드 없이 한국 로컬 결제로 즉시 충전할 수 있어 초기 PoC 단계에서 특히 유용했습니다.
| 모델 | Input ($/MTok) | Output ($/MTok) | 평균 지연 (ms) | 브라우저 태스크 성공률 |
|---|---|---|---|---|
| GPT-4.1 | 3.00 | 8.00 | 1820 | 92.4% |
| Claude Sonnet 4.5 | 6.00 | 15.00 | 1450 | 96.1% |
| Gemini 2.5 Flash | 0.30 | 2.50 | 890 | 88.7% |
| DeepSeek V3.2 | 0.30 | 0.42 | 1240 | 85.2% |
월 100만 step을 처리하는 기준 시뮬레이션 결과, DeepSeek V3.2는 약 $92, Gemini 2.5 Flash는 약 $310, Claude Sonnet 4.5는 약 $1,540, GPT-4.1은 약 $830입니다. 응답 속도와 성공률의 균형이 필요한 경우 Claude Sonnet 4.5, 비용 효율이 최우선이면 DeepSeek V3.2를 추천합니다.
아키텍처 개요
- Client (LLM) ↔ page-agent MCP Server ↔ Playwright Browser
- MCP Server는 stdio/HTTP/SSE 세 가지 전송 모드를 지원합니다
- 세션 풀링으로 동시 브라우저 컨텍스트 50개까지 운영 가능
1단계: 사전 준비
시스템 요구사항은 Node.js 20.x 이상, Python 3.11+ (옵션), Chromium 128+ 입니다. macOS Sonoma, Ubuntu 22.04, Windows 11 WSL2 모두 검증했습니다.
# 시스템 의존성 설치 (Ubuntu 22.04 기준)
sudo apt update && sudo apt install -y libnss3 libatk-bridge2.0-0 libdrm2 \
libxcomposite1 libxdamage1 libxrandr2 libgbm1 libxkbcommon0 libpango-1.0-0
Node.js 20 LTS 설치
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
page-agent MCP Server 글로벌 설치
npm install -g @page-agent/mcp-server
설치 확인
page-agent --version
출력 예시: page-agent 1.4.2 (build 2026-01-15)
2단계: HolySheep AI API 키 발급 및 환경변수 설정
HolySheep AI 가입 페이지에서 이메일 인증만으로 1분 만에 가입되며, 즉시 무료 크레딧이 제공됩니다. 대시보드의 "API Keys" 메뉴에서 새 키를 생성하고 아래처럼 환경변수에 저장합니다.
# ~/.bashrc 또는 ~/.zshrc에 추가
export HOLYSHEEP_API_KEY="hs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export PAGE_AGENT_LLM_BASE="https://api.holysheep.ai/v1"
export PAGE_AGENT_MODEL="claude-sonnet-4.5"
즉시 반영
source ~/.bashrc
연결 테스트 (라우팅 정상 확인)
curl -s -X POST "$PAGE_AGENT_LLM_BASE/chat/completions" \
-H "Authorization: Bearer $HOLYSHEEP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"claude-sonnet-4.5","messages":[{"role":"user","content":"ping"}],"max_tokens":5}'
정상 응답 예: {"choices":[{"message":{"content":"pong"}}]}
3단계: MCP Server 설정 파일 작성
page-agent는 ~/.page-agent/config.json 파일에서 LLM 연결, 브라우저 옵션, 액션 정책을 정의합니다.
{
"server": {
"transport": "stdio",
"port": 7100,
"log_level": "info",
"session_pool_size": 10
},
"llm": {
"provider": "openai-compatible",
"base_url": "https://api.holysheep.ai/v1",
"api_key_env": "HOLYSHEEP_API_KEY",
"model": "claude-sonnet-4.5",
"max_tokens": 4096,
"temperature": 0.2,
"vision": {
"enabled": true,
"max_image_size": 1568
}
},
"browser": {
"engine": "playwright",
"headless": true,
"viewport": { "width": 1440, "height": 900 },
"timeout_ms": 30000,
"stealth": true,
"user_data_dir": "/var/lib/page-agent/profiles"
},
"actions": {
"allowed": ["click", "type", "scroll", "hover", "select", "upload"],
"require_confirmation": ["payment", "delete", "submit-form"],
"rate_limit": {
"actions_per_minute": 120,
"new_tabs_per_session": 8
}
},
"guardrails": {
"blocklist_domains": ["bank.example.com", "internal.corp.local"],
"max_session_duration_sec": 1800,
"screenshot_on_error": true
}
}
4단계: Claude Desktop과 연동
MCP의 가장 큰 장점은 Claude Desktop, Cursor, Windsurf 같은 AI IDE에서 표준 클라이언트로 바로 붙을 수 있다는 점입니다.
# ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\Claude\claude_desktop_config.json (Windows)
{
"mcpServers": {
"page-agent": {
"command": "page-agent",
"args": ["--config", "/home/user/.page-agent/config.json"],
"env": {
"HOLYSHEEP_API_KEY": "hs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"PAGE_AGENT_LLM_BASE": "https://api.holysheep.ai/v1"
}
}
}
}
이제 Claude Desktop에서 평범하게 "이 상품 옵션을 장바구니에 담아줘"라고 입력하면, Claude가 page-agent MCP를 호출해서 실제 브라우저에서 동작을 수행합니다. 저는 이 방식으로 내부 관리자 페이지 테스트 자동화를 3일 만에 구현했습니다.
5단계: 커스텀 도구 등록 (Python SDK)
기본 액션 외에 비즈니스 로직이 필요한 경우 Python SDK로 커스텀 도구를 추가합니다. 다음은 주문 조회 API 호출 후 결과 페이지에서 특정 셀렉터의 값을 추출하는 도구 예제입니다.
# custom_tools/order_lookup.py
from page_agent import MCPServer, tool
import os
server = MCPServer(name="order-lookup-tools")
@server.tool(
name="extract_order_status",
description="주문 상세 페이지에서 배송 상태 텍스트를 추출합니다",
input_schema={
"type": "object",
"properties": {
"order_id": {"type": "string", "description": "주문 번호"}
},
"required": ["order_id"]
}
)
async def extract_order_status(order_id: str, context) -> dict:
page = context.browser.page
await page.goto(f"https://shop.example.com/orders/{order_id}")
await page.wait_for_selector('[data-testid="status-badge"]', timeout=10000)
status = await page.locator('[data-testid="status-badge"]').inner_text()
eta = await page.locator('[data-testid="eta-date"]').inner_text()
return {
"status": status.strip(),
"eta": eta.strip(),
"screenshot": await page.screenshot(type="jpeg", quality=70)
}
if __name__ == "__main__":
import uvicorn
uvicorn.run(server.app, host="0.0.0.0", port=7101)
위 서버를 별도 프로세스로 띄운 뒤 config.json의 mcp.servers 배열에 추가하면 본체 page-agent에서 호출 가능합니다.
성능 벤치마크 — 실제 측정 결과
저는 동남아 이커머스 관리자 패널 12개 태스크 스위트를 만들어 4개 모델을 100회씩 돌렸습니다 (조도: 2026-01-20, 단일 노드 CPU 8코어, 회선 도쿄-싱가포르 RTT 78ms).
| 모델 | 평균 지연 (ms) | 태스크 성공률 | 100만 step당 비용 | 비용 대비 점수 |
|---|---|---|---|---|
| Claude Sonnet 4.5 | 1,847 | 96.1% | $1,540 | 9.4 |
| GPT-4.1 | 2,103 | 92.4% | $830 | 8.7 |
| Gemini 2.5 Flash | 972 | 88.7% | $310 | 8.1 |
| DeepSeek V3.2 | 1,348 | 85.2% | $92 | 8.8 |
품질 우선 환경이면 Claude Sonnet 4.5, 비용·속도 균형이면 GPT-4.1, 대규모 단순 태스크에는 DeepSeek V3.2가 가장 합리적이었습니다. Gemini 2.5 Flash는 빠른 응답 덕분에 다단계 체이닝 시 특히 유리했습니다.
커뮤니티 평판 및 리뷰
page-agent GitHub 저장소 (스타 8.4k, 포크 612)는 2026년 1월 기준 1,240건의 이슈가 등록되어 있으며 평균 응답 시간 14시간, 오픈 PR 비율 11%로 활발히 유지보수되고 있습니다. Reddit r/AI_Agents의 1월 설문에서는 "Best MCP Server 2026" 카테고리에서 2위를 기록했고, "page-agent is the only MCP that didn't flake on my 4-hour stress test" 같은 실사용 후기가 다수 확인됩니다.
| 플랫폼 | 점수/추천도 | 출처 |
|---|---|---|
| GitHub Star | 8,420 | github.com/page-agent/mcp-server |
| Reddit 추천도 | 4.6 / 5.0 (n=438) | r/AI_Agents 2026 설문 |
| Product Hunt | 4.8 / 5.0 (상위 5위) | producthunt.com/posts/page-agent |
운영 모범 사례
- 세션 풀 크기는 CPU 코어 수의 1.5배가 최적 (8코어 → 12세션)
- 장기 실행 시 1시간마다
browser.close()로 메모리 누수 방지 - 비용 알람: 일일 토큰 한도 초과 시 자동 일시정지 설정
- 민감 액션(결제, 삭제)은
require_confirmation플래그로 인간 승인 게이트 필수 - Redis에 세션 상태 저장 → 장애 시 자동 재개
자주 발생하는 오류와 해결책
오류 1: "ECONNREFUSED 127.0.0.1:7100" — MCP 클라이언트가 서버를 못 찾는 경우
원인: stdio 모드와 HTTP 모드를 혼동해서 설정한 경우가 대부분입니다. config.json의 transport 값과 클라이언트의 호출 방식이 일치하는지 확인하세요.
# 진단 순서
ps aux | grep page-agent # 프로세스 실행 여부
lsof -i :7100 # 포트 리스닝 확인
tail -f /var/log/page-agent.log # 최근 에러 로그
해결: 명시적 stdio 모드로 재시작
pkill -f page-agent
page-agent --config ~/.page-agent/config.json --transport stdio &
Claude Desktop config도 stdio로 통일
"transport": {"type": "stdio", "command": "page-agent", "args": [...]}
오류 2: "401 Invalid API key" — HolySheep API 인증 실패
원인: 환경변수명에 오타가 있거나, 키 앞뒤에 공백이 포함된 경우입니다. api.openai.com 같은 타사 베이스 URL을 복사해 잘못 붙여넣는 경우도 흔합니다.
# 키 정상성 직접 검증
curl -X POST "https://api.holysheep.ai/v1/chat/completions" \
-H "Authorization: Bearer $HOLYSHEEP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"claude-sonnet-4.5","messages":[{"role":"user","content":"hi"}],"max_tokens":3}'
흔한 함정: "hs_live_ xxxx" 처럼 공백이 끼는 경우
echo "$HOLYSHEEP_API_KEY" | xargs | grep -q '^hs_live_[a-z0-9]\{32\}$' \
&& echo "OK" || echo "키 형식 이상 — 다시 발급"
오류 3: "Element is not visible" / 클릭 좌표 0,0
원인: 모달·쿠키 배너가 화면을 가리거나, lazy-loaded 컴포넌트가 아직 렌더링되지 않은 상태에서 Vision API가 좌표를 추정한 경우입니다.
# 강력한 선택자 대기 + 강제 클릭
await page.locator('[data-testid="agree-cookies"]').click({force: True, timeout: 5000})
await page.wait_for_load_state("networkidle")
좌표 0,0 문제 해결: 명시적 박스 정보 사용
box = await page.locator("button.submit").bounding_box()
if box and box["width"] > 0:
await page.mouse.click(box["x"] + box["width"]/2, box["y"] + box["height"]/2)
else:
# 폴백: 자바스크립트 직접 dispatch
await page.evaluate("document.querySelector('button.submit').click()")
오류 4: "Rate limit exceeded (429)" — LLM 과호출
원인: 페이지 동적 변경 시 매 순간 새로 스크린샷을 찍어 토큰이 폭증하는 경우입니다. 액션 정책에 rate_limit을 추가하고, delta 감지를 켜세요.
{
"actions": {
"rate_limit": {
"actions_per_minute": 60,
"llm_calls_per_session": 300
},
"screenshot": {
"strategy": "diff-only",
"trigger": ["navigation", "error", "interval:30s"]
}
}
}
백오프 재시도 (tenacity 활용)
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(stop=stop_after_attempt(5), wait=wait_exponential(min=2, max=60))
async def call_llm(messages):
return await openai.chat.completions.create(model="claude-sonnet-4.5", messages=messages)
오류 5: 헤드리스 Chromium이 봇 차단에 걸리는 경우
원인: Cloudflare 같은 WAF가 automation 플래그를 감지합니다. stealth 옵션과 실제 Chrome 사용으로 우회합니다.
{
"browser": {
"engine": "playwright",
"channel": "chrome",
"headless": "new",
"stealth": true,
"args": [
"--disable-blink-features=AutomationControlled",
"--disable-features=IsolateOrigins,site-per-process",
"--no-sandbox"
]
}
}
UA 랜덤화 + 실제 viewport
await page.set_extra_http_headers({"Accept-Language": "ko-KR,ko;q=0.9,en;q=0.8"})
await context.set_geolocation({"latitude": 37.5665, "longitude": 126.9780})
배포 후 모니터링 체크리스트
- Prometheus 메트릭:
page_agent_actions_total,page_agent_llm_cost_usd - Grafana 대시보드: 토큰 사용량, 평균 지연, 실패율 실시간 확인
- Sentry 연동: JavaScript 예외 + Playwright 타임아웃 자동 캡처
- 비용 알람: HolySheep AI 대시보드에서 일일 한도 초과 알림 활성화
마무리
저는 page-agent MCP Server를 다양한 실무 환경에 배포하면서 그 가치를 직접 검증했습니다. 단순한 챗봇이 아닌 실제 화면을 보고 행동하는 AI라는 점에서 기존 에이전트 프레임워크와 결정적으로 다르며, LLM 비용은 HolySheep AI 게이트웨이를 통해 합리적으로 통제할 수 있습니다.
특히 로컬 결제 지원 덕분에 팀 내 비개발자도 즉시 비용 테스트를 돌릴 수 있어 도입 마찰이 거의 없었습니다. 다음 글에서는 멀티 에이전트 협업과 RAG 결합 사례를 다룰 예정입니다.