11  Sa2web MCP 접근 활성화

11.1 목표

Codex, Claude Code, Cursor 같은 MCP 지원 AI 클라이언트가 Sa2web 원격 브라우저를 읽고 조작할 수 있도록 합니다.

11.2 준비 사항

  • Node.js 20+.
  • @sa2web/mcp 설치.
  • 에이전트 로그인 URL 준비.
  • 에이전트 계정에 필요한 SaaS, 워크스페이스, 내부 사이트, 프록시 권한이 있음.

에이전트 로그인 URL의 clientId와 clientSecret은 비밀로 취급해야 합니다.

11.3 설치

npm install @sa2web/mcp -g
npx playwright install --with-deps

설치 후 다음 명령어 사용 가능:

sa2
sa2-browser
sa2-mcp

11.4 에이전트 사용자 생성

다음으로 이동:

사용자 관리 > 에이전트 목록

새 에이전트 사용자(예: mcp-agent)를 추가하고 저장합니다. 그림 11.1 참조.

그림 11.1: Sa2web 에이전트 사용자 추가

여기서 기본 비밀번호는 https://<APP_DOMAIN>/app/login에서 수동 프론트엔드 로그인용입니다. 사용자 목록에서 에이전트 사용자를 찾거나 프론트엔드에 로그인하여 변경할 수 있습니다. 에이전트 사용자 이름은 기본적으로 a로 시작합니다.

사용자 추가 후 에이전트 사용자 목록에서 확인 가능. 그림 11.2 참조.

그림 11.2: Sa2web 에이전트 사용자 목록

그런 다음 MCP 클라이언트 설정을 위해 에이전트 사용자의 clientId와 clientSecret을 복사합니다. “” 버튼을 클릭하여 로그인 URL을 복사할 수도 있습니다. URL은 다음과 같습니다:

https://192.168.1.105/agent/login?clientId=6d0593b03fa748aa8dee7452ef6221c8&clientSecret=d985786d946e4826aadd07d579c59b06bf41a32aff4a415f8981070915d940a9

이미 clientId와 clientSecret이 포함되어 있어 MCP 클라이언트 설정에서 직접 사용 가능합니다.

11.5 에이전트 사용자 권한 부여

다음으로 이동:

사용자 관리 > 그룹 목록

그룹 목록 페이지에서 새 그룹(예: agent)을 생성합니다. 그림 11.3 참조. 사용자를 클릭하고 mcp-agent 같은 에이전트 사용자를 그룹에 추가한 후 저장합니다. 그런 다음 그룹에 필요한 SaaS, 워크스페이스, 내부 사이트, 프록시 및 기타 권한을 승인합니다.

그림 11.3: Sa2web 에이전트 그룹

새 브라우저에서 에이전트 로그인 URL을 엽니다. 예: https://192.168.1.105/agent/login?clientId=6d0593b03fa748aa8dee7452ef6221c8&clientSecret=d985786d946e4826aadd07d579c59b06bf41a32aff4a415f8981070915d940a9. Sa2web 홈 페이지로 리디렉션됩니다. 그림 11.4 참조. 에이전트의 승인된 콘텐츠가 올바른지 확인합니다.

그림 11.4: Sa2web 에이전트 자동 로그인 페이지

11.6 MCP 클라이언트 설정

사용하는 AI 에이전트 클라이언트가 요구하는 형식으로 설정을 작성합니다. 예:

{
  "mcpServers": {
    "sa2-remote-browser": {
      "command": "sa2-mcp",
      "env": {
        "SA2_LOGIN_URL": "https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...",
        "SA2_LOGIN_REDIRECT_PATH": "/app/login",
        "SA2_HEADLESS": "false",
        "SA2_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

다음 예제는 Codex 데스크톱을 사용하여 Sa2web MCP를 추가하는 방법을 보여줍니다. Codex에서 settings 메뉴를 클릭하고 설정 화면을 엽니다. 그림 11.5 참조. Plugins를 찾아 플러그인 페이지를 열고 MCP 서버 추가를 클릭합니다.

그림 11.5: Codex에 Sa2web MCP 추가

이제 이 MCP를 테스트합니다. Sa2web MCP를 사용하여 워크스페이스 사이트를 탐색하고 콘텐츠를 수집하기 위해 다음 프롬프트를 입력합니다:

Open the workspace 'demo2' using sa2-remote-browser, collect the main content of the page, and summarize it.

메시지 전송 후 Codex가 sa2-remote-browser를 사용하여 Sa2web 대상 사이트에 접근하고 콘텐츠를 수집합니다. 그림 11.6 참조.

그림 11.6: Codex에서 Sa2web MCP 데모 결과
경고

실제 clientSecret 값을 공개 Git 저장소, 스크린샷, 공개 티켓에 커밋하지 마세요.

11.7 AI 권한

AI 계정은 여전히 Sa2web 권한 시스템으로 제어됩니다. 필요한 것만 부여하세요:

  • SaaS 사이트.
  • 워크스페이스.
  • 내부 사이트.
  • 네트워크/프록시 접근.
  • 기타 필요한 권한.

공식 문서에 따르면 대상 사이트는 iframe#rbi-frame에 위치하며, MCP 서버가 Playwright를 통해 해당 iframe을 제어하고 에이전트는 대상 웹사이트에 직접 접근하지 않습니다.

경고

AI가 영업 비밀이나 개인 데이터를 노출할 위험을 줄이려면 백엔드에서 사이트의 타겟 URL 보호를 미리 활성화하고, SaaS 계정 정보, 회사 기밀 URL, 민감한 키워드를 숨기거나 차단하세요.

11.8 수락 체크리스트

참고:

  • https://www.sa2web.com/docs/en/appendix/mcp