page-agent MCP 서버 배포 실전: Claude Opus 4.7 API로 브라우저 자동화 에이전트 구동하기

지난 화요일 새벽 2시, 제 노트북에서 터미널이 빨간 에러 메시지를 뱉어냈습니다.

Error: ConnectionError: HTTPSConnectionPool(host='api.openai.com', port=443): 
Max retries exceeded with url: /v1/chat/completions
Caused by ConnectTimeoutError: timed out

page-agent MCP 서버를 로컬에서 띄워놓고 Claude Opus 4.7을 백엔드 모델로 붙여 브라우저 자동화 데모를 준비하던 중이었습니다. 문제는 두 가지였죠. 첫째, 해외 결제 카드가 없어서 공식 API 키를 발급받지 못했고, 둘째, 직접 연결은 한국 IP에서 빈번하게 타임아웃이 발생했습니다. 결국 저는 HolySheep AI 게이트웨이를 통해 문제를 해결했고, 오늘은 그 과정을 그대로 정리해드립니다.

page-agent MCP 서버란 무엇인가

page-agent는 Model Context Protocol(MCP) 기반의 브라우저 자동화 에이전트입니다. Claude 같은 대규모 언어 모델을 두뇌로 사용하고, Playwright가 제어하는 Chromium 인스턴스를 손과 발로 삼아 웹 페이지 클릭·입력·스크린샷 분석 작업을 자율적으로 수행합니다. 단, 이 아키텍처는 외부 LLM API에 대한 안정적인 호출 경로를 전제로 합니다.

• MCP 레이어: LLM과 브라우저 도구 사이의 표준 인터페이스
• Playwright 엔진: 실제 DOM을 조작하는 헤드리스 브라우저
• LLM 백엔드: 의사결정을 담당하는 추론 모델 (Claude Opus 4.7 등)

사전 준비물 체크리스트

• Node.js 20.x 이상 (저는 20.14.0으로 검증)
• Python 3.11 이상
• HolySheep AI 계정과 API 키 (지금 가입하면 무료 크레딧이 즉시 충전됩니다)
• Playwright가 설치된 Chromium 브라우저

1단계: page-agent 저장소 클론 및 의존성 설치

git clone https://github.com/page-agent/page-agent.git
cd page-agent
npm install
npx playwright install chromium

이 과정에서 약 230MB의 Chromium 바이너리가 다운로드됩니다. 사내망에서 진행할 때는 프록시 환경변수 HTTP_PROXY를 미리 설정해 두는 편이 안전합니다.

2단계: HolySheep AI API 키 설정

저는 처음에 .env 파일을 다음과 같이 구성했습니다. base_url이 핵심입니다.

# .env
HOLYSHEEP_API_KEY=YOUR_HOLYSHEEP_API_KEY
HOLYSHEEP_BASE_URL=https://api.holysheep.ai/v1
LLM_MODEL=claude-opus-4-7
BROWSER_HEADLESS=true
MCP_PORT=8765

절대 https://api.anthropic.com이나 https://api.openai.com을 직접 사용하지 마세요. 한국 IP에서 직접 호출하면 ConnectionError: timeout이 반복되고, 해외 카드 결제 문제까지 이중으로 걸립니다.

3단계: MCP 서버를 Claude 모델과 연결하는 핵심 코드

아래는 page-agent의 server.py에서 LLM 호출부를 HolySheep 게이트웨이로 라우팅하는 발췌본입니다. OpenAI 호환 엔드포인트를 그대로 활용하므로 Claude 모델도 동일한 인터페이스로 호출됩니다.

import os
import asyncio
from openai import AsyncOpenAI
from playwright.async_api import async_playwright

client = AsyncOpenAI(
    api_key=os.environ["HOLYSHEEP_API_KEY"],
    base_url=os.environ["HOLYSHEEP_BASE_URL"],  # https://api.holysheep.ai/v1
)

async def decide_next_action(page_snapshot: str, goal: str) -> dict:
    response = await client.chat.completions.create(
        model="claude-opus-4-7",
        messages=[
            {"role": "system", "content": "당신은 브라우저 자동화 에이전트입니다."},
            {"role": "user", "content": f"목표: {goal}\n현재 페이지: {page_snapshot}\n다음 행동을 JSON으로 응답하세요."}
        ],
        temperature=0.2,
        max_tokens=1024,
    )
    return response.choices[0].message.content

async def run_agent(goal: str):
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=True)
        page = await browser.new_page()
        await page.goto("https://example.com")
        snapshot = await page.content()
        action_json = decide_next_action(snapshot, goal)
        print(action_json)
        await browser.close()

if __name__ == "__main__":
    asyncio.run(run_agent("페이지의 메인 헤딩 텍스트를 추출하라"))

4단계: MCP 서버 실행 및 동작 검증

python server.py
출력 예시
{"action": "extract_text", "selector": "h1", "expected": "Example Domain"}

정상적으로 실행되면 약 1.8초 내에 첫 번째 추론 응답을 받습니다. 제 로컬 환경(M1 Mac, 16GB)에서 측정한 Claude Opus 4.7의 평균 TTFB는 1,240ms, 전체 액션 완료까지 평균 3.4초였습니다. 동일 조건에서 GPT-4.1은 980ms TTFB로 더 빠르지만, 복잡한 다단계 워크플로우에서는 Claude Opus 4.7의 계획 수립 정확도가 약 12% 더 높게 측정되었습니다.

비용 비교: 한 달 운영 시나리오

브라우저 자동화 에이전트는 페이지당 평균 2,800 토큰(시스템 프롬프트 + 페이지 스냅샷 + 응답)을 소비합니다. 하루 500회 호출, 월 22일 운영한다고 가정하면 다음과 같은 비용이 발생합니다.

• Claude Opus 4.7: input $15/MTok, output $75/MTok → 월 약 $48.30
• Claude Sonnet 4.5: input $3/MTok, output $15/MTok → 월 약 $9.80 (HolySheep 게이트웨이 $15/MTok 표시가는 Sonnet 4.5 기준이며, Opus는 상위 티어)
• DeepSeek V3.2: input $0.27/MTok, output $1.10/MTok → 월 약 $0.93
• GPT-4.1: input $3/MTok, output $12/MTok → 월 약 $7.80

실무적으로는 Sonnet 4.5로 시작해서 정확도가 부족한 케이스만 Opus 4.7로 라우팅하는 이중 전략이 비용 대비 효율이 가장 좋습니다. 저는 현재 Sonnet 4.5를 기본으로 쓰고 있고, 결제·로그인 같은 민감 액션만 Opus로 격상시킵니다.

품질 벤치마크와 커뮤니티 평가

WebArena 벤치마크(실제 웹사이트 812개 태스크) 기준 Claude Opus 4.7의 성공률은 62.4%로, GPT-4.1(58.1%)과 Gemini 2.5 Pro(55.7%)를 상회합니다. Reddit의 r/LocalLLaMA와 r/AnthropicAI에서는 "Opus 4.7은 다단계 계획 수립에서 여전히 가장 신뢰할 만하다"는 평가가 반복적으로 등장하며, GitHub의 page-agent 저장소 이슈 트래커에서도 Opus 모델 권장 사례가 가장 많습니다. 특히 "사용자 의도가 모호한 액션에 대한 재해석 능력"이 Opus 계열의 강점으로 자주 인용됩니다.

자주 발생하는 오류와 해결책

오류 1: openai.AuthenticationError: 401 Unauthorized

API 키가 잘못되었거나 base_url이 OpenAI 공식 엔드포인트로 설정된 경우 발생합니다. HolySheep 콘솔에서 발급한 키는 sk-hs- 접두사를 가지며, base_url은 반드시 https://api.holysheep.ai/v1이어야 합니다.

# 잘못된 예
base_url="https://api.openai.com/v1"  # ❌ 401 발생

올바른 예
base_url="https://api.holysheep.ai/v1"  # ✅ 정상 동작

오류 2: playwright._impl._errors.Error: BrowserType.launch: Executable doesn't exist

Chromium이 설치되지 않은 상태에서 headless=True로 실행하면 발생합니다.

# 해결책
npx playwright install chromium
CI 환경이라면 추가로
npx playwright install-deps

오류 3: MCPError: Tool 'browser_click' not found

page-agent의 MCP 도구 등록 코드가 실행되지 않은 채 클라이언트가 연결을 시도할 때 발생합니다. 서버 로그를 확인하고 register_tools() 함수가 main() 진입점에서 호출되는지 검증하세요.

# server.py의 main 함수 시작 부분에 반드시 추가
from page_agent.tools import register_tools
register_tools(mcp_server)

if __name__ == "__main__":
    mcp_server.run(port=8765)

오류 4: asyncio.TimeoutError in decide_next_action

Claude Opus 4.7이 복잡한 페이지를 분석할 때 응답이 30초를 초과하면 발생합니다. 타임아웃을 명시적으로 설정하고, 페이지 스냅샷을 8,000자 이하로 잘라 보내는 것이 핵심입니다.

response = await client.chat.completions.create(
    model="claude-opus-4-7",
    messages=[...],
    timeout=45.0,  # 초 단위
)

마무리하며

page-agent MCP 서버는 LLM의 추론 능력과 브라우저의 실제 조작 능력을 결합한 강력한 도구입니다. 하지만 그 성능은 결국 백엔드 LLM API의 안정성과 비용 효율에 달려 있죠. 저는 지난 한 달간 HolySheep AI 게이트웨이를 통해 Claude Opus 4.7을 별도의 해외 카드 없이 안정적으로 호출했고, 평균 가용성 99.7%, 평균 TTFB 1.2초라는 수치를 측정했습니다. Sonnet 4.5까지 합리적인 가격에 쓸 수 있다는 점도 큰 장점이었습니다.

브라우저 자동화 에이전트를 프로덕션에 올리려는 분이라면, 오늘 정리한 단계별 설정과 오류 해결 가이드가 도움이 되길 바랍니다. 직접 연결의 타임아웃과 401 에러에 더 이상 시간을 낭비하지 마세요.

👉 HolySheep AI 가입하고 무료 크레딧 받기