Mac에서 Aside CLI 설치하고 Codex MCP 연결하기 (aside not found 해결까지)

요즘 AI 코딩 도구를 사용하다 보면 한 가지 아쉬운 점이 생깁니다. 코드는 알아서 잘 작성하는데, 정작 브라우저에서 실행한 결과를 확인하는 건 여전히 번거롭다는 점입니다.

Codex CLI로 코드를 수정하고, 브라우저를 열어서 확인하고, 오류가 있으면 다시 Codex로 돌아오고... 이 과정을 반복하다 보면 개발보다 창 전환을 더 많이 하는 것 같은 기분이 듭니다.

그런데 Aside Browser와 MCP를 연결하면 Codex가 브라우저를 직접 제어하는 작업까지 맡길 수 있습니다.

이번에는 Mac에서 Aside CLI를 설치하고 Codex CLI에 MCP 서버를 등록하는 방법을 정리해 보겠습니다. 설치 중 만날 수 있는 aside not found 오류도 함께 다룹니다.

1. Aside CLI와 MCP는 무엇일까?

먼저 Aside는 AI 에이전트와 연동할 수 있는 브라우저 도구입니다. 일반적인 브라우저처럼 웹사이트에 접속할 수 있지만, CLI와 MCP 인터페이스를 통해 외부 AI 도구가 브라우저를 제어할 수 있다는 점이 특징입니다.

여기서 MCP는 Model Context Protocol의 약자입니다. 쉽게 말하면 AI에게 외부 프로그램을 사용할 수 있는 통로를 만들어 주는 표준입니다.

이번에 구축할 구조는 다음과 같습니다.

Codex CLI
    ↓
Aside MCP
    ↓
Aside Browser
    ↓
웹사이트 접속 및 화면 확인

예를 들어 Codex에 웹사이트 UI를 확인해 달라고 요청하면, 연결된 Aside 도구를 통해 브라우저를 조작하고 결과를 검사하는 방식으로 활용할 수 있습니다.

코드는 Codex가 작성하고, 브라우저 조작은 Aside가 담당하는 셈입니다. 서로 잘하는 일을 나눠 맡기는 구조죠.

2. Mac에서 Aside CLI 설치하기

먼저 Mac 터미널을 실행합니다. 이번 설치에서는 macOS의 zsh 환경을 기준으로 설명하겠습니다.

Aside CLI 설치 명령어는 다음과 같습니다.

curl -fsSL https://releases.aside.com/install.sh | bash

명령어를 실행하면 설치 스크립트를 내려받아 실행합니다. 외부 스크립트를 바로 실행하는 방식이므로, 보안이 신경 쓰인다면 파일을 먼저 내려받아 내용을 확인한 뒤 실행하는 편이 좋습니다.

Aside CLI는 어디에 설치될까?

설치 구조는 다음과 같습니다.

~/.aside/cli/
    └── Aside CLI.app
          └── Contents
                └── MacOS
                      └── aside

~/.local/bin/aside
    └── 실제 실행 파일을 가리키는 링크

즉, Aside CLI는 사용자 홈 디렉터리에 설치되고, 터미널에서 간편하게 실행할 수 있도록 심볼릭 링크가 생성됩니다.

프로젝트마다 Aside CLI를 새로 설치할 필요는 없습니다. 한 번 설치해 두면 여러 프로젝트에서 공통으로 사용할 수 있습니다.

3. Aside CLI 설치 확인하기

설치가 끝났다면 정상적으로 실행되는지 확인해 보겠습니다.

which aside
aside --version

정상적으로 설치되고 PATH까지 설정되어 있다면 다음과 비슷한 경로가 표시됩니다.

/Users/사용자계정/.local/bin/aside

그런데 여기서 의외의 상황을 만날 수 있습니다.

aside not found

분명 설치했는데 명령어를 찾을 수 없다고 합니다. 설치가 실패한 걸까요?

꼭 그렇지는 않습니다. 실행 파일이 존재하지만 터미널의 PATH에 해당 디렉터리가 등록되지 않았을 수도 있습니다.

4. aside not found 오류 해결하기

이 부분은 실제로 설치하면서 마주친 문제이기도 합니다.

먼저 Aside 실행 파일의 심볼릭 링크가 존재하는지 확인합니다.

ls -l "$HOME/.local/bin/aside"

제 환경에서는 다음과 같이 표시됐습니다.

/Users/miu/.local/bin/aside
 -> /Users/miu/.aside/cli/Aside CLI.app/Contents/MacOS/aside

이 결과는 심볼릭 링크가 생성되었다는 뜻입니다. 다만 링크가 있다고 해서 실제 실행 파일까지 정상이라고 단정할 수는 없습니다.

우선 PATH에 실행 디렉터리를 등록해 보겠습니다.

zsh 환경변수 등록하기

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
rehash

각 명령어의 역할은 다음과 같습니다.

• echo: PATH 설정을 ~/.zshrc 파일에 추가합니다.
• source: 변경된 설정을 현재 터미널에 반영합니다.
• rehash: zsh의 명령어 검색 정보를 갱신합니다.

이제 다시 확인합니다.

which aside
aside --version

만약 여전히 실행되지 않는다면 실제 파일까지 확인해 봐야 합니다.

ls -lL "$HOME/.local/bin/aside"

여기서 파일이 없다는 오류가 발생하면 심볼릭 링크가 가리키는 대상 파일이 없는 상태일 수 있습니다. 반대로 파일이 정상적으로 표시된다면 실행 권한이나 터미널 환경을 추가로 점검해야 합니다.

핵심은 설치 실패와 PATH 문제를 구분하는 것! 무작정 재설치하기 전에 파일 위치부터 확인하면 불필요한 작업을 줄일 수 있습니다.

5. Codex CLI에 Aside MCP 등록하기

Aside CLI 준비가 끝났다면 이제 Codex와 연결할 차례입니다.

터미널에서 다음 명령어를 실행합니다.

codex mcp add aside -- "$HOME/.local/bin/aside" mcp

등록에 성공하면 다음과 같은 메시지가 출력됩니다.

Added global MCP server 'aside'.

여기서 중요한 점이 하나 있습니다.

MCP 등록 성공과 실제 MCP 실행 성공은 서로 다릅니다.

Codex가 설정을 저장했더라도 Aside CLI가 실행되지 않으면 MCP 연결은 정상적으로 동작하지 않을 수 있습니다.

Codex MCP 등록 상태 확인

codex mcp list

특정 MCP 설정만 확인하려면 다음 명령어를 사용합니다.

codex mcp get aside

Codex의 MCP 설정은 사용자 단위로 관리할 수 있습니다. 따라서 프로젝트마다 별도로 등록하지 않고 여러 작업 디렉터리에서 재사용할 수 있습니다.

6. Codex MCP 설정 파일은 어디에 있을까?

Codex CLI의 MCP 설정은 일반적으로 다음 파일에 저장됩니다.

~/.codex/config.toml

설정 파일을 확인하려면 다음 명령어를 실행합니다.

cat ~/.codex/config.toml

Aside MCP 등록 설정은 대략 다음과 같은 구조입니다.

[mcp_servers.aside]
command = "/Users/사용자계정/.local/bin/aside"
args = ["mcp"]

여기서 command는 실행할 프로그램의 위치이고, args는 Aside CLI를 MCP 서버 모드로 실행하기 위한 인수입니다.

특히 절대 경로를 지정하면 Codex가 Aside 실행 파일을 찾을 때 셸의 PATH 설정에 덜 의존하게 됩니다.

다만 실제 MCP 실행 여부는 별도로 확인해야 합니다.

7. Aside Browser 실행하고 Codex 연결하기

여기까지 왔다면 거의 마무리입니다.

하지만 Aside CLI만으로 모든 준비가 끝나는 것은 아닙니다. 브라우저 자동화를 사용하려면 Aside Browser 앱도 설치하고 실행해야 합니다.

1. Aside Browser 앱을 설치합니다.
2. Aside Browser를 실행하고 계정에 로그인합니다.
3. Codex CLI를 종료했다가 다시 실행합니다.
4. Codex에서 MCP 연결 상태를 확인합니다.

Codex CLI 실행 명령어:

codex

Codex 내부에서는 다음 명령어로 MCP 상태를 확인할 수 있습니다.

/mcp

Aside가 정상적으로 연결되면 브라우저 자동화 작업에 사용할 수 있습니다.

만약 Aside 데몬에 연결할 수 없다는 오류가 나온다면 Aside Browser 앱이 실행 중인지 먼저 확인해 보세요.

8. Codex와 Aside MCP로 무엇을 할 수 있을까?

설치 방법보다 중요한 것은 역시 활용 방법이겠죠.

저는 특히 웹 개발 과정에서 브라우저 검증을 자동화하는 용도가 유용하다고 생각합니다.

웹사이트 UI 테스트

예를 들어 Codex에 다음과 같이 요청할 수 있습니다.

Aside MCP를 이용해 localhost:3000에 접속하고 모바일 화면에서 레이아웃이 깨지는 부분이 있는지 확인해 줘. 문제가 발견되면 원인을 분석하고 수정해 줘.

브라우저 오류 확인

브라우저 화면을 분석하거나 DOM 요소를 검사하는 작업에도 활용할 수 있습니다.

현재 열린 웹사이트의 DOM 구조를 확인하고 버튼이 정상적으로 동작하는지 테스트해 줘. 오류가 발견되면 수정할 파일과 원인을 정리해 줘.

로그인된 웹사이트 점검

Aside가 접근할 수 있는 기존 브라우저 세션을 활용하면 관리자 페이지나 대시보드를 점검하는 용도로도 사용할 수 있습니다.

다만 로그인된 계정에서 자동 클릭과 입력을 수행할 수 있으므로, 게시·삭제·결제처럼 실제 변경이 발생하는 작업은 반드시 내용을 확인하고 진행하는 것이 안전합니다.

9. Aside MCP와 Playwright MCP는 어떤 차이가 있을까?

브라우저 자동화 도구를 알아보다 보면 Playwright MCP도 자주 등장합니다.

둘 다 브라우저와 상호작용할 수 있지만 사용 환경과 접근 방식에서 차이가 있습니다.

비교 항목	Aside MCP	Playwright MCP
주요 목적	Aside 브라우저 제어	Playwright 기반 브라우저 자동화
브라우저 환경	Aside Browser 사용	설정된 브라우저 환경 사용
기존 세션 활용	Aside 브라우저 세션 활용 가능	실행 및 연결 구성에 따라 다름
활용 사례	로그인된 화면 점검, 브라우저 작업	웹 테스트, 자동화, 반복 검증

어느 쪽이 무조건 좋다고 이야기하기는 어렵습니다.

현재 사용 중인 Aside 브라우저의 화면과 세션을 활용하고 싶다면 Aside MCP가 적합하고, 독립적인 테스트 브라우저와 자동화 시나리오가 필요하다면 Playwright MCP도 좋은 선택입니다.

10. 설치 과정에서 자주 발생하는 문제 FAQ

Q. Aside CLI를 프로젝트마다 설치해야 하나요?

아니요. 사용자 홈 디렉터리에 한 번 설치하면 여러 프로젝트에서 공통으로 사용할 수 있습니다.

Q. Codex MCP 등록 성공 메시지가 나왔는데 왜 실행되지 않나요?

MCP 등록은 설정을 저장하는 과정입니다. Aside 실행 파일이 정상적으로 존재하고 실행되는지, 브라우저 앱이 실행 중인지 추가로 확인해야 합니다.

Q. aside not found 오류가 발생하면 재설치해야 하나요?

반드시 재설치할 필요는 없습니다. 먼저 ~/.local/bin/aside 파일 존재 여부와 PATH 환경변수를 확인하는 것이 좋습니다.

Q. Mac에서 PATH를 수정했다면 재부팅해야 하나요?

일반적으로 필요하지 않습니다. source ~/.zshrc 명령으로 현재 셸에 변경 사항을 반영할 수 있습니다.

Q. Aside Browser 없이 MCP만 사용할 수 있나요?

Aside CLI의 브라우저 제어 기능을 사용하려면 Aside Browser와 관련 백그라운드 서비스가 실행 중이어야 합니다.

11. 최종 설치 명령어 정리

마지막으로 설치 과정을 간단하게 정리하겠습니다.

# 1. Aside CLI 설치
curl -fsSL https://releases.aside.com/install.sh | bash

# 2. PATH 등록
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
rehash

# 3. Aside CLI 확인
which aside
aside --version

# 4. Codex MCP 등록
codex mcp add aside -- "$HOME/.local/bin/aside" mcp

# 5. MCP 등록 확인
codex mcp list
codex mcp get aside

# 6. Codex 실행
codex

이미 MCP를 등록했다면 4번 명령어는 다시 실행하지 않아도 됩니다.

또한 PATH 설정이 이미 등록되어 있다면 같은 내용을 ~/.zshrc에 중복으로 추가하지 않는 것이 좋습니다.

마무리: 이제 Codex에게 브라우저도 맡겨보자

처음에는 단순히 Aside CLI를 설치해서 Codex에 연결하면 끝날 줄 알았습니다.

그런데 실제로 진행해 보니 MCP 등록은 성공했는데 터미널에서는 aside 명령어를 찾지 못하는 상황이 발생했습니다.

역시 개발 환경 설정은 한 번에 끝나면 조금 섭섭한 법인가 봅니다.

그래도 원리를 알고 보면 해결 방법은 어렵지 않습니다. 실행 파일 위치를 확인하고, PATH를 등록한 뒤, MCP 연결 상태를 점검하면 됩니다.

앞으로는 Codex가 코드를 작성하는 데서 끝나는 것이 아니라 브라우저에서 실제 동작까지 확인하는 개발 환경을 구축해 볼 생각입니다.

코드 수정과 화면 검증을 반복하는 웹 개발자라면 Aside MCP 연결을 한 번 시도해 볼 만합니다.

설치 중 같은 오류를 만났다면 이번 정리가 도움이 되었으면 좋겠습니다.

참고 자료

• OpenAI Codex MCP 공식 문서
• Aside Browser MCP 설치 및 활용 예시
• Google 검색 품질 및 SEO 가이드