에이전틱 브라우저의 로컬 MCP 에이전트 제어 구현

에이전틱 브라우저에 내장한 로컬 MCP 서버의 요청 전달 경로, 두 가지 실행 방식, 사용자 탭 보호, 제어 중 표시, 민감 기능 통제와 알려진 한계를 정리합니다.

배경과 설계 목표

에이전틱 브라우저는 자체 기능을 패치한 Chromium 또는 Microsoft Edge 를 전용 프로필로 실행하고 제어하는 Rust 기반 Windows 애플리케이션입니다. 실행 파일에 --mcp 인수를 지정하면 MCP(Model Context Protocol) 서버로 동작하며, Claude 나 Codex 같은 MCP 클라이언트는 이 프로세스를 표준 입출력으로 연결해 브라우저를 조작합니다. 이 글은 해당 서버의 구현 방식을 정리합니다.

이 글에서 호스트는 브라우저를 실행하고 제어하는 Rust 프로세스를, 내장 확장은 브라우저에 기본으로 포함된 확장(URL 보관함)을 가리킵니다. 에이전트 동작의 상당수는 호스트가 아니라 내장 확장이 브라우저 확장 API 로 수행합니다.

설계 목표는 네 가지였습니다.

실제 프로필을 사용합니다. 로그인 세션이 있는 사용자의 브라우저를 그대로 조작합니다. 별도의 헤드리스 인스턴스나 브라우저 확장 설치가 필요하지 않습니다.

사용자의 작업 흐름을 보존합니다. 에이전트가 일하는 동안 사용자가 보던 탭, 창 포커스, 입력 흐름이 바뀌지 않아야 합니다.

조작 사실을 가시화합니다. 어느 탭을 에이전트가 제어 중인지 사용자가 페이지 내용을 믿지 않고도 확인할 수 있어야 합니다.

민감 기능을 통제합니다. 파일 첨부, 내장 확장 조회, 신뢰 범위 변경처럼 피해가 큰 기능은 제한하거나 기록하고, 일부는 에이전트 도구에서 제외합니다.

요청 전달 경로

먼저 도구 호출 요청의 예시입니다. 에이전트가 아래 요청을 보내면, 대상 탭에서 「로그인」 문구를 가진 요소를 찾아 화면 안으로 스크롤한 뒤 중심을 클릭합니다. 결과에는 클릭한 요소와, 클릭으로 새 탭이 열렸다면 그 탭의 정보가 담깁니다.

{"jsonrpc":"2.0","id":7,"method":"tools/call",
 "params":{"name":"browser_click","arguments":{"text":"로그인"}}}

이 요청은 다섯 단계를 거쳐 대상 페이지에 도달합니다. 단계 사이의 전송 수단과 크기 제한이 서로 다릅니다.

단계구성 요소역할다음 단계로의 전달
1MCP 클라이언트도구 목록을 읽고 tools/call 요청을 보냅니다.표준 입출력, 줄 단위 JSON-RPC(한 줄 1MiB 이하)
2agentic-browser --mcp프로토콜 협상, 도구 정의 제공, 인수 검증을 맡고 호출을 브라우저 쪽으로 넘깁니다.Windows 명명된 파이프, 현재 사용자 전용, 프레임 128KiB 이하
3브라우저 호스트내장 확장이 연 네이티브 메시징 연결이 서비스 모드로 전환됩니다. 파이프로 들어온 요청은 대기열에 쌓입니다.네이티브 메시징, 확장이 폴링으로 요청을 가져가고 결과를 회신(메시지 1MiB 이하)
4내장 확장 서비스 워커탭 선택, 스크립트 주입, 디버거 호출 등 브라우저 확장 API 로 동작을 실행합니다.scripting·debugger·tabs API
5대상 탭의 페이지페이지 안에서 요소를 찾고 이벤트를 보낸 뒤 JSON 결과를 돌려줍니다.-

적용 범위. 이 다섯 단계는 패치 Chromium 일반 실행에 해당합니다. Microsoft Edge 엔진에서는 호스트가 디버깅 프로토콜(CDP, Chrome DevTools Protocol) 연결을 직접 맺으므로 네이티브 메시징과 서비스 워커 단계가 없습니다. 차이는 「두 가지 실행 방식」 절에서 다룹니다.

MCP 서버와 명명된 파이프

서버는 표준 입력에서 한 줄씩 JSON-RPC 메시지를 읽습니다. 한 줄이 1MiB 를 넘으면 해당 줄을 버리고 오류 응답을 돌려줍니다. 프로토콜은 기존 날짜 버전 네 가지(2024-11-05 부터 2025-11-25 까지)를 지원하고, 요청마다 _meta 에 프로토콜 버전(2026-07-28)과 클라이언트 기능을 싣는 새 방식(server/discover 포함)도 지원합니다. 새 방식에서는 버전이 어긋나면 지원 버전 목록을 담은 오류를 돌려줍니다. 알림 메시지에는 응답하지 않으며 브라우저 동작도 일으키지 않습니다.

모든 도구에는 readOnlyHint 주석을 붙였습니다. 페이지 소스 보기, 뷰포트 조회, 대기처럼 상태를 바꾸지 않는 도구만 참(true)이고, 나머지는 거짓(false)입니다. 도구 정의 함수가 이 값을 필수 인수로 받으므로 분류를 빠뜨린 도구는 정의할 수 없습니다. 분류가 맞는지는 단위 시험에서 보관함과 탭 보관 계열 도구 일부를 대조해 검증합니다.

MCP 프로세스와 브라우저 호스트 사이의 파이프는 프로필 폴더 경로의 해시를 이름에 넣어 프로필마다 분리합니다. 생성 시 보호된 접근 제어 목록으로 소유자에게만 접근을 허용하고, 원격 클라이언트 연결을 거부하며, 같은 이름의 파이프를 다른 프로세스가 먼저 만들어 가로채는 것을 첫 인스턴스 플래그로 막습니다.

도구 구성

도구는 약 100개이며 기능별로 묶으면 아래 표와 같습니다. 이 가운데 입력과 화면 계열(클릭, 입력, 키, 스크롤, 대기, 스크린샷, 소스 보기, 표현식 평가)이 에이전트 제어의 중심입니다.

범주대표 도구비고
탭과 탐색browser_list_tabs · browser_new_tab · browser_navigate · browser_switch_tab탭 ID 는 목록 도구가 돌려주는 문자열
입력과 화면browser_click · browser_type · browser_press_key · browser_scroll · browser_wait_for · browser_screenshot요소는 CSS 선택자, 보이는 문구, 좌표 중 하나로 지정
검사browser_inspect_tab · browser_view_source · browser_get_cookies쿠키 값은 include_values 를 줄 때만 반환
모바일 시험browser_set_viewport · browser_get_viewport창 크기는 바꾸지 않고 콘텐츠 영역만 에뮬레이션
확장 개발extensions_reload · extensions_evaluate · extensions_get_errors서비스 워커, 팝업, 옵션 페이지의 디버깅 대상 목록 제공
보관 기능 연동onetab_* · url_repo_* · adblock_*탭 보관, URL 보관함, 광고 차단 규칙 관리
운영update_status · cert_list · vpn_status브라우저가 꺼져 있어도 동작하는 도구 포함

도구 정의는 이름, 설명, 입력 스키마, 필수 인수, 읽기 전용 여부를 한 번에 선언하는 보조 함수로 만듭니다. 입력 스키마에는 문자열 길이, 정수 범위, 열거값을 명시해 잘못된 인수가 브라우저까지 도달하지 않게 합니다. 아래는 browser_click 의 정의입니다.

tool(
    "browser_click",
    &format!(
        "Click an element. Target it with exactly one of selector, text, or the viewport coordinates x and y. The element is scrolled into view first, then clicked at its center. Returns the clicked element, a covering element if the point is obstructed, and any tab the click opened. Works on web, chrome:// and extension pages. {MODE_NOTE}"
    ),
    json!({
        "tab_id": tab_id, "selector": selector, "text": visible_text,
        "x": integer(0, 100000), "y": integer(0, 100000),
        "button": { "type": "string", "enum": ["left", "right", "middle"] },
        "click_count": integer(1, 3), "nth": nth,
        "timeout_ms": timeout(0, 30000, 2000)
    }),
    &[],
    false,
),

두 가지 실행 방식

같은 도구가 엔진에 따라 다른 방식으로 실행됩니다. 도구 정의와 결과 형식은 같고, 입력이 전달되는 수준만 다릅니다.

항목Microsoft Edge 엔진패치 Chromium 일반 실행
제어 수단호스트가 CDP 연결을 직접 맺고 Input.dispatchMouseEvent 같은 호출로 입력을 보냅니다.원격 디버깅 포트 없이 실행하므로 호스트는 CDP 를 쓰지 못합니다. 내장 확장이 페이지 스크립트를 주입해 DOM 이벤트로 조작합니다.
isTrusted참. 이벤트가 스크립트가 아닌 실제 사용자 입력에서 왔는지 나타내는 브라우저 속성입니다.거짓
스크린샷전체 페이지 캡처를 CDP 가 처리합니다.보이는 영역 중심입니다.
파일 입력CDP 로 파일 입력 요소에 경로를 지정합니다.페이지에서 File 객체를 만들어 넣습니다.

일반 실행은 원격 디버깅 없이 동작하도록 설계했으므로 상시 열린 디버깅 포트가 없습니다. 대신 엔진 쪽에는 필요한 기능만 최소한으로 허용했습니다. 확장의 디버거는 확장·내부 페이지의 표현식 평가와 검사에 한정하고, 일반 웹 페이지에는 백그라운드 탭 캡처용 메서드 2개와 뷰포트 에뮬레이션용 메서드 5개만 허용합니다. 엔진은 이 기능을 지원한다는 사실을 기능 식별자(AgenticBrowserBackgroundCapture/1, AgenticBrowserEmulation/1)로 알리고, 호스트는 식별자가 있을 때만 해당 도구를 실행합니다. 식별자가 없는 엔진에서는 해당 도구가 다른 방식으로 대체되지 않고 사유와 함께 거부됩니다.

요소 지정과 입력

요소 탐색, 가시성 판정, 포커스, 이벤트 생성은 페이지 안에서 실행하는 단일 스크립트(agent-page.js)가 담당합니다. 같은 파일을 두 경로에서 사용합니다. Edge 경로에서는 호스트가 Runtime.evaluate 로 실행하고, 일반 실행에서는 확장이 scripting.executeScript 로 주입합니다. 두 경로 모두 마지막에 함수 이름과 인수로 같은 진입점을 호출하므로 동작 차이가 입력 전달 수준에만 남습니다.

기능동작
선택자 해석열린 shadow root 를 최대 300개까지 순회해 모읍니다. 웹 컴포넌트 안의 요소도 선택자와 문구로 찾을 수 있습니다.
가시성 판정연결 여부, 클라이언트 사각형, visibility, display, 크기를 확인합니다. 같은 조건에 여러 요소가 맞으면 보이는 요소를 앞에 두고 nth 로 고릅니다.
가려짐 보고클릭 지점에 다른 요소가 덮고 있으면 클릭한 요소와 덮고 있는 요소를 함께 결과에 싣습니다. 에이전트가 오버레이 때문에 클릭이 빗나간 상황을 스스로 알 수 있습니다.
입력값 비반환browser_type 은 입력한 문자열과 필드 값을 결과에 싣지 않고 글자 수와 필드 종류만 보고합니다. 비밀번호 필드에도 입력할 수 있지만 값은 어디에도 남기지 않습니다.

스크립트는 전역 이름 공간을 오염시키지 않도록 지역 globalThis 매개변수에 등록하고, 버전 숫자가 같으면 다시 실행하지 않습니다. 모든 반환값은 JSON 으로 직렬화되는 단순 객체여야 한다는 규칙을 코드 머리말에 명시했습니다.

사용자 탭 보호

에이전트가 사용자가 보는 탭을 직접 조작하면 사용자가 보던 화면이 갑자기 바뀌거나, 입력 중인 창의 포커스를 빼앗기는 문제가 발생합니다. 이를 방지하기 위해 에이전트 전용 대상 탭이라는 개념을 도입했습니다.

  1. 에이전트가 연 탭은 백그라운드(비활성) 음소거 상태로 열고, 기본 조작 대상으로 지정합니다. 사용자가 보던 탭은 바뀌지 않습니다.
  2. tab_id 없이 호출한 도구는 이 대상 탭을 조작합니다. 대상이 없거나 닫혔으면 사용자의 활성 탭으로 되돌아갑니다.
  3. 대상 탭 번호는 storage.session 에 함께 기록합니다. 서비스 워커가 중간에 재시작해도 대상을 잃지 않습니다.
  4. 에이전트 탭은 메모리 부족 시의 자동 폐기(tab discarding)에서 제외합니다. 백그라운드 탭이 메모리에서 해제되어 조작이 중단되는 일을 막기 위해서입니다.
  5. browser_switch_tab 은 기본적으로 대상만 바꾸고, activate: true 를 지정할 때만 그 탭을 활성화해 사용자에게 보입니다.

스크린샷도 같은 원칙을 따릅니다. 사용자에게 보이는 탭은 화면에서 캡처하고, 백그라운드 탭은 디버거의 Page.captureScreenshot 으로 활성화 없이 캡처합니다. 이 호출을 위해 엔진에는 내장 확장이 웹 페이지를 대상으로 두 개의 CDP 메서드(Page.captureScreenshot, Page.getLayoutMetrics)만 쓸 수 있게 하는 패치를 넣었습니다.

에이전트 전용 창을 쓰지 않은 이유. 전용 창을 따로 열면 사용자 창과 완전히 분리되지만, 창이 하나 더 보이고 두 창 사이의 포커스 이동이 생깁니다. 백그라운드 탭으로 두는 편이 사용자 화면에 주는 간섭이 적다고 판단했습니다. 대가로 백그라운드 탭은 렌더링이 멈춰 지연 로딩이나 애니메이션이 동작하지 않을 수 있습니다.

에이전트 제어 중 표시

에이전트가 탭을 조작하는 동안 두 가지 표시를 보입니다. 이 표시는 항상 활성화되며 끌 수 없습니다.

표시위치신뢰 수준
탭 그룹 이름표 「에이전트 제어 중」탭 표시줄(브라우저 자체 화면)페이지가 위조하거나 지울 수 없음. chrome:// 페이지와 확장 페이지에도 표시됨
붉은 테두리와 상단 배지웹 페이지 위 오버레이페이지가 같은 모양을 흉내 낼 수 있으므로 보조 표시

페이지 위 오버레이는 닫힌 shadow root 안에 그리고, 격리된 월드(isolated world)에서 실행합니다. 포인터 이벤트를 받지 않고 고정 위치라 레이아웃에도 영향을 주지 않으며, 페이지 스크립트는 오버레이 내부와 상태 변수에 접근할 수 없습니다. 다만 오버레이 요소 자체는 페이지의 문서 트리에 붙어 있어 페이지가 지우거나 가릴 수 있으므로, 다음 조작 때 요소와 스타일을 다시 그립니다. 마지막 조작 뒤 약 5초가 지나면 두 표시가 모두 사라지고, 화면 캡처에는 포함되지 않습니다.

페이지가 오버레이와 같은 모양을 그려 사용자를 오인하게 할 수 있으므로, 신뢰의 기준은 탭 표시줄의 그룹 이름표로 정했습니다.

민감 기능 통제

에이전트가 호출할 수 있는 기능 가운데 위험이 큰 기능은 세 가지 방식으로 통제합니다. 호출 자체를 차단하는 방식, 실행 조건을 사전에 검사하는 방식, 기록을 남기는 방식입니다.

에이전트 도구로 제공하지 않는 기능

기능통제 방식
스크립트 허용 호스트 변경내장 확장이 스크립트를 주입할 수 있는 사이트 목록으로, 설정 화면에서 사용자가 직접 변경합니다. 에이전트용 변경 도구가 없고, 내장 확장의 설정 화면은 입력, 화면, 소스 보기, 표현식 평가 도구의 호출을 거부합니다.
전용 인증서 등록조회 도구만 있습니다. 등록과 제거는 사용자가 인증서 지문(fingerprint)을 직접 확인한 뒤 명령줄이나 호스트가 띄우는 확인 창에서만 수행합니다. 에이전트가 승인 인수를 스스로 채워 신뢰 범위를 넓히는 일을 구조적으로 막기 위함입니다.
에이전트가 만든 주입 규칙기본적으로 비활성 상태로 저장되고, JavaScript 가 들어 있으면 사용자가 규칙 화면에서 검토한 뒤 직접 활성화해야 실행됩니다.

조건 검사

browser_upload_file 은 호스트가 경로를 먼저 검사합니다. 대상은 절대 경로의 일반 파일이어야 하며(폴더 불가), 한 번에 10개, 파일당 50MiB, 합계 100MiB 를 초과할 수 없습니다. 브라우저의 데이터 폴더, .ssh·.aws 같은 자격 증명 폴더, 다른 브라우저의 프로필에 있는 파일은 거부합니다. 일반 실행에서는 파일을 512KiB 조각으로 읽어 페이지에서 File 객체를 만들며, 호스트는 조각을 읽을 때마다 경로를 다시 검사합니다. 검사 시점과 사용 시점 사이에 경로가 바뀌는 문제(TOCTOU)를 줄이기 위해서입니다. 결과에는 파일 이름, 크기, 형식만 있고 경로와 내용은 없습니다.

보안 기록

파일 첨부와 내장 확장 조회는 성공, 실패, 거부 여부와 무관하게 앱 데이터의 security-log.jsonl 에 한 줄씩 남깁니다. 기록은 MCP 처리 지점에서 남기므로 엔진과 무관하게 같은 형식입니다. 확장 조회는 조회 범위를 알 수 있는 인수만 남기고, 조회한 값이나 실행한 코드의 본문은 남기지 않습니다. 페이지 주소의 쿼리 문자열도 지웁니다. 확인하지 않은 기록이 있으면 다음 브라우저 시작 때 조회 화면이 자동으로 열립니다. 기록은 사용자 컴퓨터에만 보관되며 외부로 전송되지 않습니다.

알려진 한계와 남은 과제

파일 첨부 경로 검사, 보안 기록에 비밀값이 남지 않는 것, 대상 탭 규칙, 프로토콜 협상, 일부 도구의 읽기 전용 분류는 단위 시험으로 검증합니다. 시험으로 확인하지 못했거나 알려진 한계는 다음과 같습니다.

일반 실행의 클릭과 입력은 isTrusted 가 거짓인 비신뢰 DOM 이벤트입니다. 브라우저가 사용자 제스처로만 인정하는 동작은 에이전트로 시험할 수 없습니다. 실제로 우클릭 메뉴 시험이 이 경우에 해당했습니다.

동시 호출은 파이프 인스턴스를 하나만 두는 구조입니다. 한 호출이 연결 중일 때 다른 호출은 파이프 사용 중(ERROR_PIPE_BUSY)을 받습니다. 클라이언트는 이 오류에서 재시도하지만, 동시 호출 시 연결이 멈추는 현상이 관찰되었고 그 원인은 아직 확정하지 못했습니다. 연결 자가 복구와 진단 기록을 적용해 두었습니다.

백그라운드 탭은 브라우저가 렌더링을 멈추므로 지연 로딩과 애니메이션에 의존하는 페이지는 browser_switch_tab 의 activate: true 가 필요합니다.

엔진 패치의 실행 시험은 부분적입니다. 백그라운드 탭 캡처를 위한 C++ 패치는 별도 서버에서 컴파일한 뒤 설치본에서 전환 없는 캡처가 성공하는 것을 확인했습니다. 다만 엔진 쪽 단위 시험은 갱신하거나 실행하지 못했습니다.

에이전트에게 사용자의 실제 브라우저를 맡기면 편의와 위험이 함께 커집니다. 이 구현은 편의를 늘리는 기능보다 사용자가 에이전트의 행동을 알아차리고, 되돌리고, 나중에 확인할 수 있게 하는 기능에 더 많은 구현 비중을 두었습니다. 남은 과제는 동시 호출에서 파이프가 사용 중으로 응답하는 문제의 원인을 확정하는 것입니다.