Guida의 MCP 서버는 어떻게 동작하는가

2025년 1월 20일 · 3분 읽기 ·

technical

Guida에는 Model Context Protocol (MCP) 서버가 내장되어 있습니다. Claude Code, Cursor, 기타 MCP 지원 클라이언트 같은 외부 AI가 브라우저를 조작할 수 있는 것은 이 서버가 있기 때문입니다.

이 글에서는 프로토콜, transport, 도구 등록, 그리고 AI가 마음대로 움직이지 않게 하는 3계층 안전 모델을 설명합니다.

MCP란

MCP는 AI 모델과 외부 도구를 연결하는 JSON-RPC 프로토콜입니다. AI는 “Navigate 도구를 url: https://example.com으로 호출” 같은 요청을 보내고, 서버가 실행한 뒤 결과를 반환합니다. 모델은 브라우저를 직접 만지지 않습니다. 모델이 보는 것은 도구의 입력·출력 계약입니다.

MCP에는 주로 다음 primitive가 있습니다.

Tools - AI가 호출할 수 있는 함수
Resources - AI가 읽을 수 있는 데이터
Prompts - 자주 쓰는 작업의 템플릿

Guida는 tools와 resources를 구현하고, 브라우저 자동화, 데이터 저장, 검색, 큐, 워커, 워크플로 원장 등을 100개 이상의 도구로 공개합니다.

Transport: 로컬 HTTP

Guida는 로컬 HTTP transport를 사용합니다. 서버는 내장 Kestrel로 실행되며 기본 URL은 다음과 같습니다.

http://127.0.0.1:9315/

stdio가 아니라 HTTP를 쓰는 이유는 실용적입니다. Guida는 CLI 도구가 아니라 WPF 데스크톱 앱입니다. stdin/stdout을 pipe하는 것보다 브라우저 UI, 승인 상태, 작업 기록, 워크스페이스 패널을 보여 둔 채 외부 MCP 클라이언트를 연결하는 편이 자연스럽습니다.

연결 시 클라이언트가 initialize하고, 서버가 capability를 반환하며, 클라이언트가 tools/list와 tools/call을 수행합니다.

Client -> initialize
Server -> capabilities
Client -> tools/list
Client -> tools/call

도구 등록

각 도구에는 이름, 설명, 매개변수 JSON Schema, 비동기 handler가 있습니다. 대표적인 도구는 다음과 같습니다.

도구	설명
`Navigate`	활성 탭을 URL로 이동
`Click`	CSS selector로 요소 클릭
`GetElements`	DOM 요소를 조회해 속성 추출
`Screenshot`	현재 viewport를 PNG로 촬영
`ExecuteScript`	앱의 Scripting Engine에서 `g.*` 스크립트 실행
`StoreGet` / `StorePut`	워크스페이스 저장소 읽기/쓰기
`QueueEnqueue` / `QueueDequeue`	작업 큐 관리
`SearchQuery`	인덱싱된 문서 전체 텍스트 검색

많은 도구는 g.* Scripting API를 지탱하는 같은 서비스에 위임합니다. Navigate는 g.nav.navigateToUrl()과 같은 브라우저 작업 계층을 사용합니다. MCP 계층은 JSON-RPC 요청을 서비스 호출로 옮기고 결과를 정리하는 adapter입니다.

다만 스크립트와 AI 도구가 완전히 같은 권한을 갖는 것은 아닙니다. 안전 모델이 다릅니다.

3계층 안전 모델

Guida에서 AI는 강력하지만 신뢰된 주체는 아닙니다. 브라우저에 도달하기 전에 세 계층을 통과합니다.

1. 허용된 도메인

AI가 URL로 이동하려면 대상 도메인이 허용되어 있어야 합니다. Guida에는 세 단계 설정이 있습니다.

세션 단위 - 앱을 닫을 때까지 유효
워크스페이스 단위 - 워크스페이스 폴더의 domains.json
전역 - 설정에서 항상 허용

*.example.com 같은 wildcard subdomain도 사용할 수 있습니다. 수동 브라우징은 별도이며, 제한은 MCP 시작 탐색에 적용됩니다.

2. 도구 승인

허용된 도메인에서도 감독 대상 도구 호출에는 명시적 승인이 필요합니다. Guida는 정확한 도구 이름, URL, selector, script code 같은 매개변수를 보여 주고 사용자가 허용하거나 거부할 수 있게 합니다.

3. 감사 로그

MCP 도구 호출은 감사 로그에 기록됩니다. 나중에 어떤 도구가 어떤 매개변수로 호출됐고 성공했는지 실패했는지 확인할 수 있습니다. AI에는 자신의 감사 로그를 삭제하는 도구가 없습니다.

인증 정보 경계

인증 정보는 DPAPI로 암호화됩니다. MCP 도구는 복호화 값을 반환하지 않습니다. 또한 MCP 시작 스크립트는 g.secrets.getSecret()을 사용할 수 없습니다. 이로써 AI가 스크립트를 통해 값을 읽고 저장소에 저장한 뒤 나중에 가져오는 경로를 막습니다.

왜 이 정도가 필요한가

AI에 브라우저를 넘기는 것은 편리하지만 일반 자동화보다 위험한 면도 있습니다. 보이는 브라우저, 명시적 승인, 허용된 도메인, 감사 로그, 인증 정보 분리가 있어야 AI 지원 브라우저 자동화를 실무에 쓰기 쉬워집니다.

Guida의 MCP 서버는 이 제어를 유지한 채 AI에 작업 능력을 넘기는 다리입니다.