본 편에서 해결하고자 하는 문제

이전 편은 Outline + Claude였으나, 모든 사람이 Claude 구독 플랜을 사용하는 것은 아니기에 Codex를 이용하는 방법도 제공합니다.

본 편을 따라 한 단계씩 진행하여 설정을 완료하면, Codex가 MCP를 통해 Outline 도구를 호출하여 다음과 같은 멋진 일들을 수행할 수 있습니다:

• Outline 문서 검색 또는 목록 나열
• 컬렉션(Collection) 내 문서 읽기 및 편집
• 컬렉션 생성
• 문서 이동
• MCP Server가 제공하는 기타 Outline 작업 실행

Codex App, Codex CLI 및 IDE 확장 프로그램은 Codex의 MCP 설정을 공유하므로, 설정을 완료하면 각 클라이언트에서 반복적으로 설정할 필요가 없습니다.

사전 준비

시작하기 전에 다음 환경이 갖춰져 있는지 확인하십시오:

1. Codex 설치
2. Node.js 설치
3. 정상적으로 연결 가능한 Outline

Outline API Token 생성

설정(Preferences) 진입

Outline에 로그인한 후, 왼쪽 하단 계정 옆의 "⋯"를 클릭하고 "설정 (Preferences)"을 선택합니다.

API & Access 활성화

왼쪽 설정 메뉴에서 "API & Access"를 선택한 다음, 오른쪽 상단의 "새 API 키 (New API Key)"를 클릭합니다.

키 이름, 범위(Scope) 및 만료일 설정

용도를 쉽게 식별할 수 있는 이름(예: "AI MCP", "Codex MCP" 등)을 입력하는 것을 권장합니다.

원래 프로세스의 설정은 다음과 같습니다:

• 범위 (Scope): 비워둠
• 만료일 (Expiration Date): 기한 없음

범위를 비워두는 것은 일반적으로 특정 API 권한을 제한하지 않음을 의미합니다. 이 설정은 조작이 가장 간단하지만 권한도 상대적으로 큽니다.

API Token 복사

생성이 완료되면 "복사 (Copy)"를 클릭하고, Token은 한 번만 표시되므로 안전한 위치에 먼저 임시 저장해 두십시오.

주의: API Token은 계정 인증서와 동일하므로 Git, 공개 문서, 블로그 게시물, 채팅 그룹 또는 암호화되지 않은 노트에 붙여넣지 마십시오.

Codex MCP 설정

Codex 설정 파일 열기

Codex는 MCP 및 기타 로컬 설정을 저장하기 위해 config.toml을 사용합니다.

사용자 수준의 설정은 Codex App, Codex CLI 및 IDE 확장 프로그램에 적용됩니다.

Windows

PowerShell을 열고 다음을 실행합니다:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null
New-Item -ItemType File -Force "$env:USERPROFILE\.codex\config.toml" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"

이 세 가지 명령은 순서대로 다음을 수행합니다:

1. .codex 디렉터리를 생성합니다.
2. config.toml 파일을 생성합니다.
3. 메모장(Notepad)으로 설정 파일을 엽니다.

또는 아무 폴더나 연 다음, 파일 경로 표시줄에 다음을 붙여넣을 수도 있습니다:

%USERPROFILE%\.codex

그 후 config.toml을 엽니다.

macOS: Finder를 사용하여 열기

1. Finder를 엽니다.
2. 상단 메뉴에서 "이동"을 클릭합니다.
3. "폴더로 이동..."을 선택합니다.
4. 다음 경로를 붙여넣습니다:

~/.codex/

1. 다음 파일을 찾아 엽니다:

config.toml

macOS: 터미널을 사용하여 열기

터미널에서 다음을 실행할 수도 있습니다:

mkdir -p "$HOME/.codex"
touch "$HOME/.codex/config.toml"
open -e "$HOME/.codex/config.toml"

이 세 가지 명령은 순서대로 설정 디렉터리를 생성하고, 설정 파일을 생성하며, macOS 텍스트 편집기(TextEdit)로 파일을 엽니다.

파일이 이미 존재하는 경우, 수정하기 전에 먼저 복사본을 만들어 백업해 두는 것을 권장합니다.

Outline MCP Server 추가

다음 설정을 config.toml에 추가하세요:

[mcp_servers.outline]
command = "npx"
args = [
...

다음 내용을 교체하세요:

유효한 HTTPS 인증서를 사용할 때의 간소화된 설정

Outline MCP Server가 이미 유효하고 신뢰할 수 있는 HTTPS 인증서를 사용 중이라면, Codex는 Node.js, npx 또는 mcp-remote 없이 직접 연결할 수 있습니다.

[mcp_servers.outline]
url = "https://YOUR_MCP_HOST/mcp"
http_headers = { Authorization = "Bearer YOUR_OUTLINE_API_TOKEN" }

예시:

[mcp_servers.outline]
url = "https://outline-mcp.example.com/mcp"
http_headers = { Authorization = "Bearer YOUR_OUTLINE_API_TOKEN" }

이는 더 간단한 운영 환경(Production) 설정 방식입니다.

주의: 이 예시는 Token을 config.toml에 직접 작성합니다. 설정 파일을 안전하게 보호하고 Git에 커밋하지 마세요.

Windows 및 macOS의 npx 경로 문제

Codex App은 원칙적으로 npx를 직접 실행할 수 있습니다.

만약 MCP 시작에 실패한다면, 데스크톱 프로그램이 npx의 실행 경로를 찾지 못하는 것일 수 있습니다.

Windows

PowerShell에서 다음을 실행합니다:

where.exe npx

다음과 같이 반환될 수 있습니다:

C:\Program Files\nodejs\npx.cmd

다음과 같이 변경할 수 있습니다:

command = "npx"

TOML의 단일 인용 부호(Single quote) 문자열로 변경:

command = 'C:\Program Files\nodejs\npx.cmd'

TOML의 단일 인용 부호 문자열에서는 Windows 역슬래시(\)를 \\로 이스케이프 처리할 필요가 없습니다.

macOS

터미널에서 다음을 실행합니다:

which npx

Apple Silicon Mac에서 Homebrew를 사용하는 경우 다음과 같이 반환될 수 있습니다:

/opt/homebrew/bin/npx

Intel Mac에서 Homebrew를 사용하는 경우 다음과 같이 반환될 수 있습니다:

/usr/local/bin/npx

그 다음:

toml
command = "npx"

부분을 실제 확인된 전체 경로로 변경합니다. 예를 들어:

toml
command = "/opt/homebrew/bin/npx"

주의: 예시 경로를 그대로 복사하지 마세요. 먼저 where.exe npx 또는 which npx를 사용하여 자신의 컴퓨터에서 실제로 반환된 결과를 입력해야 합니다.

Codex 재시작

config.toml을 수정한 후에는 사용 중인 Codex를 재시작해야 합니다.

• Codex App / ChatGPT 데스크톱 버전: 완전히 종료한 후 다시 엽니다.
• Codex CLI: 현재 세션을 종료하고 codex를 다시 실행합니다.
• IDE 확장 프로그램 (Extension): 확장 프로그램을 재시작하거나 에디터 창을 다시 로드합니다.

창을 닫는 것만으로는 프로그램이 완전히 종료되지 않았을 수 있습니다:

• Windows: 시스템 트레이에서 프로그램을 종료하거나, 작업 관리자에서 백그라운드에서 실행 중인지 확인합니다.
• macOS: Command + Q를 누르고, 필요한 경우 '활성 상태 보기 (Activity Monitor)'에서 프로그램이 여전히 실행 중인지 확인합니다.

재시작 시 Codex는 다음 과정을 수행합니다:

1. ~/.codex/config.toml을 읽습니다.
2. npx를 통해 mcp-remote를 실행합니다.
3. Authorization Header를 사용하여 Outline MCP Server에 연결합니다.
4. MCP Server가 제공하는 도구 (Tools)를 로드합니다.

처음 npx -y mcp-remote를 실행할 때는 패키지 다운로드가 필요할 수 있으므로, 이후 실행보다 대기 시간이 약간 더 길 수 있습니다.

Outline MCP 연결 성공 테스트

Codex CLI를 사용하여 확인

먼저 다음을 실행합니다:

codex mcp list

정상적인 경우 목록에 다음과 같이 나타납니다:

outline

또한 다음을 실행할 수 있습니다:

codex mcp --help

현재 버전에서 지원하는 MCP 관리 명령어를 확인합니다.

Codex CLI에 진입한 후 다음을 입력합니다:

/mcp

현재 세션에 로드된 MCP Server와 도구들을 확인할 수 있습니다.

대화를 통한 테스트

Codex에 다음과 같이 입력합니다:

Outline MCP에 연결할 수 있나요? 현재 사용할 수 있는 Outline 도구 목록을 알려주세요.

그 다음 실제 읽기 테스트를 진행합니다:

Outline에서 현재 볼 수 있는 문서와 문서 집합 (Collections)을 나열해 주세요.

특정 작업을 지정할 수도 있습니다:

Outline에서 "프론트엔드"라는 키워드가 포함된 문서를 검색해 주세요.

연결에 성공하면 Codex는 Outline 도구가 로드되었음을 표시하며, 워크스페이스의 문서 또는 Collection 정보를 반환할 수 있습니다.