MCP Server를 브라우저 자동화 환경에 연결할 때 필요한 버전 확인, 자격 증명 관리, 서비스 등록, 연결 검증 절차를 정리하고 도구 목록이 비어 있음, 인증 실패, 연결 시간 초과 같은 문제를 점검하는 순서까지 설명합니다.
MCP(Model Context Protocol)를 사용하면 AI 어시스턴트가 브라우저 작업마다 사용자가 직접 코드를 작성하지 않아도 필요한 도구를 순서대로 호출해 작업을 완료할 수 있습니다.
실제로 연결할 때 막히는 지점은 프로토콜 자체보다 무엇을 설치해야 하는지, 어디에 연결해야 하는지, 자격 증명을 어떻게 전달해야 하는지, 그리고 연결이 제대로 되었는지 어떻게 확인해야 하는지에 있는 경우가 많습니다. 이 네 가지를 차례대로 점검하면 대부분의 문제는 설정 단계에서 드러납니다.
먼저 세 가지를 확인하세요
첫째, 로컬 인터페이스를 제공하는 브라우저 자동화 환경 클라이언트가 필요하며, 해당 버전이 로컬 API를 지원해야 합니다. 오래된 버전에서는 인터페이스 자체가 없을 수 있는데, 겉으로는 도구 목록이 비어 있는 것처럼만 보일 수 있습니다. 둘째, Node.js 18 이상이 필요합니다. 대부분의 MCP Server는 TypeScript로 구현되어 Node runtime을 사용합니다. 셋째, MCP를 지원하는 AI 도구가 필요합니다.
클라이언트 버전 확인은 가장 먼저 하는 것이 좋습니다. 연결 실패나 빈 도구 목록 오류의 상당수는 서버가 아니라 오래된 버전 때문에 발생합니다.
어디에 연결하나요
클라이언트를 시작하면 로컬 머신에 API 서비스가 올라가고 loopback 주소에서 대기합니다. 포트는 클라이언트의 인터페이스 설정에서 확인하고 변경할 수 있습니다. 포트가 사용 중이면 다른 포트로 바꾼 뒤 클라이언트를 재시작하면 됩니다.
MCP Server는 이 로컬 주소를 통해 환경에 접근하므로 공용 Internet을 거치지 않습니다. 반대로 이 서비스는 로컬에만 두어야 하며 외부에 노출해서는 안 됩니다.
자격 증명은 어떻게 전달하나요
클라이언트 설정에서 API Key를 생성합니다. 구현에 따라 ID와 Key 두 부분을 사용하는 경우도 있습니다. 이 자격 증명은 사실상 계정에 속한 모든 환경을 제어할 수 있는 권한과 같으며, 이를 얻은 사람은 환경을 시작하거나 수정하거나 삭제할 수 있습니다.
기본 보안 조치를 생략하지 마세요. 자격 증명을 코드 저장소에 commit하지 말고 환경 변수나 로컬 설정 파일을 사용한 뒤 해당 파일을 ignore 목록에 추가하세요. 팀 구성원이 바뀌면 즉시 자격 증명을 rotate해야 합니다. 용도별로 별도 자격 증명을 만들 수 있다면 분리해 두는 것이 좋습니다. 문제가 생겼을 때 추적하기 쉽고 특정 자격 증명만 따로 revoke할 수 있습니다. AI 도구 설정에서는 endpoint와 자격 증명을 모두 환경 변수로 전달하고, 기록이 남을 수 있는 command line에 직접 작성하지 마세요.
서비스를 등록하세요
일반적인 등록 방식은 AI 도구의 설정 파일에 서비스 정의를 추가하는 것입니다. 내용은 세 부분입니다. 명령이나 entry file path 같은 시작 방식, 로컬 endpoint와 자격 증명을 담는 환경 변수, 그리고 도구 목록에 표시되는 이름인 서비스 식별자입니다.
등록한 뒤에는 AI 도구를 재시작해야 합니다. 대부분의 도구는 시작할 때 설정을 한 번만 읽기 때문에, 파일을 수정하고 재시작하지 않으면 사실상 변경하지 않은 것과 같습니다.
실제로 연결되었는지 확인하는 방법
두 단계로 확인하고 순서를 바꾸지 마세요.
먼저 도구 목록을 봅니다. 브라우저 관련 도구가 나타나야 하며, 이를 통해 서비스가 인식되었음을 확인할 수 있습니다. 그다음 현재 모든 환경을 나열하는 것처럼 읽기 전용 작업을 시킵니다. 읽기 전용 작업은 부작용이 없지만 인증, 네트워크, 서비스 세 계층을 한 번에 검증할 수 있습니다. 이 단계가 통과하지 않으면 이후 작업을 시도할 필요가 없습니다.
연결된 뒤에 할 수 있는 일
서비스가 정상적으로 연결되면 AI 어시스턴트는 일반적으로 환경 조회와 검색, 환경 생성 및 기본 파라미터 설정, 환경 시작과 중지, 환경에 네트워크 egress 연결, 그리고 페이지 내 탐색, 클릭, 입력, 스크린샷 같은 작업을 수행할 수 있습니다.
호출은 자연어로 이루어집니다. 목표를 설명하면 어시스턴트가 어떤 도구를 어떤 순서로 사용할지 결정합니다. 여기서 쉽게 혼동되는 점이 있습니다. AI는 무엇을 할지 결정하고, 환경 계층은 어떤 identity로 할지를 결정합니다. 이 둘을 분리해서 보면 문제가 생겼을 때 어느 계층을 확인해야 할지 더 쉽게 알 수 있습니다.
연결되지 않을 때의 문제 해결 순서
도구 목록이 비어 있다면 먼저 설정 파일 경로가 올바른지 확인하고, 다음으로 AI 도구를 재시작했는지 확인한 뒤, 마지막으로 서비스를 수동으로 실행해 자체적으로 시작되는지 확인합니다. 이 세 단계 중 하나라도 실패한다면 아직 프로토콜을 의심할 단계가 아닙니다.
인증 실패는 보통 두 가지 원인뿐입니다. Key를 복사할 때 불필요한 문자나 줄바꿈이 함께 들어갔거나, 환경 변수가 제대로 읽히지 않은 경우입니다. 설정을 반복해서 바꾸는 것보다 Key를 다시 복사하는 편이 더 빠를 때가 많습니다.
연결 시간 초과는 대부분 로컬 측을 가리킵니다. 클라이언트가 실행 중인지, 포트가 사용 중이거나 firewall에 차단되어 있지 않은지 확인하세요. 대부분의 MCP Server는 클라이언트가 계속 실행 중이어야 하며, 클라이언트를 닫으면 도구를 더 이상 호출할 수 없습니다.
서비스는 연결되지만 작업이 올바르게 수행되지 않는다면 대기 시점이 문제인 경우가 많습니다. 페이지 로딩 완료 여부를 어시스턴트가 추측하게 하지 말고, 어떤 상태까지 기다린 뒤 다음 단계로 넘어갈지 지시에 명확히 적으세요.
미리 생각하기 어려운 또 다른 문제는 여러 작업이 하나의 환경을 공유하는 경우입니다. 세션, Cookies, 캐시가 서로 덮어쓰고 작업끼리 간섭하기 시작하면 명확한 오류 대신 무작위 실패처럼 보입니다. 더 안정적인 방법은 각 작업에 독립된 환경을 할당하고 일괄 생성과 회수는 환경 계층에 맡기는 것입니다. PurpleMark의 환경 격리와 중앙 관리는 바로 이 계층에 있으며, MCP를 연결한 뒤에도 작업 오케스트레이션과 identity 관리는 서로 다른 영역입니다.
추가로 주의할 두 가지
자동화 framework가 브라우저 제어를 맡을 때는 driver 버전이 클라이언트가 사용하는 엔진 버전과 맞아야 합니다. 클라이언트는 보통 사용 가능한 driver path를 반환하지만 버전이 맞지 않을 수도 있습니다. 버전 관리 도구로 driver를 자동 동기화하는 편이 더 간단한 경우가 많고, 페이지 endpoint는 계속 클라이언트가 반환한 값을 사용해도 됩니다. 두 방식은 충돌하지 않습니다.
다른 하나는 동시 실행입니다. 브라우저 프로세스 하나가 약 300~500MB의 메모리를 사용하므로 한 머신에서 동시에 실행하는 환경은 5개 이하를 권장합니다. 이를 넘으면 시작 실패나 프로세스 crash가 발생할 수 있습니다. 페이지 작업에서도 고정 지연으로 기다리지 말고, 페이지 로드 timeout은 30초로 설정하고 요소에는 최대 20초의 명시적 대기를 사용하세요. sleep보다 안정적입니다.
하나의 경계
MCP는 AI가 브라우저를 어떻게 조작할지라는 기술적 문제를 해결하지만 어떤 플랫폼의 규칙도 바꾸지 않습니다. 작업 자체는 계속 대상 플랫폼의 서비스 약관을 따라야 합니다. 기술적으로 가능하다는 것과 규칙상 허용된다는 것은 별개의 판단입니다.
프로토콜과 인터페이스 세부 사항은 공식 문서를 기준으로 확인하고, 시작하기 전에 실행하려는 작업이 대상 플랫폼에서 허용되는지 확인하세요.
