Codex MCP 연결 방법: 노션·GitHub 붙이기와 401 인증 오류 확인

Codex에게 "내 노션 문서를 읽고 정리해 줘", "GitHub 이슈를 보고 고쳐 줘" 같은 일을 맡기려면 먼저 연결이 필요합니다. Codex는 처음부터 노션이나 GitHub에 들어가 있지 않으니 MCP로 문을 열어 줘야 해요. 이 글은 Codex에 MCP 서버를 추가하는 두 가지 길(데스크톱 앱 화면, 터미널 명령)과 노션·GitHub 공식 서버를 붙이는 순서, 401 같은 인증 오류가 났을 때 확인할 곳을 정리합니다.

아래 내용은 OpenAI, Notion, GitHub 공식 문서를 2026년 10월 8일에 다시 읽고 대조한 것입니다. 각 문장의 근거는 끝의 출처 목록에 있어요.

Codex 앱 설치부터 필요하다면 Codex 데스크톱 앱 설치와 사용법을 먼저 보고 오세요. 9월 가톨릭대학교 AI 부트캠프에서도 학생들이 가장 많이 막힌 곳은 코딩이 아니라 설치였습니다.

Codex의 MCP 설정은 한 파일에 모입니다

MCP는 AI가 외부 도구에 붙는 방식을 통일한 표준입니다. Codex MCP 문서에 따르면 Codex는 MCP 설정을 config.toml이라는 설정 파일에 저장하고 기본 위치는 ~/.codex/config.toml입니다. ChatGPT 데스크톱 앱, Codex CLI, IDE 확장이 이 설정을 같이 씁니다. 앱에서 추가한 서버가 터미널의 codex에서도 보이고 반대도 마찬가지라 한 번만 설정하면 돼요.

프로젝트 폴더 안 .codex/config.toml에 넣으면 그 프로젝트에서만 쓰는 서버가 됩니다. 다만 문서는 이 파일을 신뢰한 프로젝트(trusted project)에서만 읽는다고 적어 두었습니다.

Codex가 붙을 수 있는 MCP 서버는 두 종류입니다.

노션과 GitHub의 공식 서버는 둘 다 주소로 접속하는 원격 서버입니다. 노션은 OAuth 로그인(브라우저에서 내 계정 접근을 허락하는 방식)으로, GitHub는 Codex 기준으로 개인 접근 토큰(PAT)으로 붙이는 방법이 공식 문서에 있어요. 아래에서 하나씩 봅니다.

데스크톱 앱에서 MCP 서버 추가하기

Codex MCP 문서가 안내하는 ChatGPT 데스크톱 앱 경로는 이렇습니다.

1. Settings를 열고 MCP servers를 고릅니다.
2. Add server를 누릅니다.
3. 이름을 적고 STDIO 또는 Streamable HTTP를 고른 뒤 실행 명령이나 주소를 넣습니다.
4. 저장하고 Restart를 누릅니다.

서버 목록에는 켜져 있는 서버와 OAuth 로그인이 필요한 서버가 표시됩니다. 로그인이 필요하면 Authenticate를 눌러 브라우저에서 허락합니다. 연결됐는지는 입력창에 /mcp를 쳐서 확인해요.

터미널에서 MCP 서버 추가하기

Codex CLI를 쓴다면 codex mcp 명령으로 같은 일을 합니다. 명령줄 옵션 문서에 정리된 하위 명령은 다음과 같습니다.

login과 logout은 Streamable HTTP 방식이면서 OAuth를 지원하는 서버에서만 동작합니다. codex 대화 화면(TUI)에서는 /mcp로 지금 쓸 수 있는 서버와 도구를 보고 /mcp verbose를 치면 서버별 진단 정보까지 나와요.

노션 연결하기

노션 공식 MCP 문서에 따르면 노션 MCP는 노션이 직접 운영하는 원격 서버입니다. OAuth로 연결을 허락하면 Codex가 내가 접근할 수 있는 노션 콘텐츠를 검색하고 읽고 고칠 수 있고 페이지와 데이터베이스도 만들 수 있어요. 노션의 클라이언트별 연결 안내에는 Codex 항목이 따로 있습니다.

터미널·설정 파일로 붙이기. ~/.codex/config.toml에 아래 두 줄을 넣습니다.

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

그다음 터미널에서 로그인합니다. 브라우저가 열리면 연결할 노션 워크스페이스를 고르고 허락합니다.

codex mcp login notion

설정 파일을 직접 여는 게 부담스럽다면 codex mcp add notion --url https://mcp.notion.com/mcp로 추가한 뒤 같은 로그인 명령을 실행해도 같은 설정이 됩니다.

데스크톱 앱으로 붙이기. 위의 앱 경로에서 이름은 notion, 종류는 Streamable HTTP, 주소는 https://mcp.notion.com/mcp로 넣고 저장한 뒤 Restart와 Authenticate를 누릅니다. 이 화면 순서는 노션 문서가 아니라 Codex MCP 문서의 일반 절차를 노션 주소에 대입한 것입니다.

플러그인으로 붙이는 길도 있습니다. Codex의 플러그인 문서는 플러그인에 MCP 서버가 묶여 있을 수 있다고 설명하고, 계정을 빠르게 잇는 Sign in with ChatGPT 베타 지원 대상에 노션을 넣어 두었습니다. 다만 이 로그인은 이름·이메일·프로필 사진만 넘길 뿐 노션 데이터 접근을 허락하는 게 아니라서 플러그인이 요청하는 권한은 따로 검토하고 승인해야 해요. 플러그인은 데스크톱 앱의 Plugins 탭에서 찾아 설치합니다. 노션 플러그인이 그 탭에 실제로 어떻게 보이는지는 확인하지 못했습니다.

연결한 뒤 확인할 것은 세 가지입니다.

• 쓰기는 묻게 하기. 노션의 보안 안내는 콘텐츠를 바꾸는 동작 전에 확인 단계를 켜 두라고 권합니다. Codex에서는 서버별 default_tools_approval_mode로 정하고 writes를 고르면 읽기 전용으로 표시되지 않은 도구를 쓸 때마다 묻습니다.

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"
default_tools_approval_mode = "writes"

• 읽어 온 내용은 믿지 않기. 같은 안내는 노션 페이지에 누군가 심어 둔 지시문이 AI의 행동을 바꾸는 프롬프트 주입을 경고합니다. 도구가 돌려준 내용은 믿을 수 없는 입력으로 보고, 데이터를 밖으로 보내거나 고치는 동작은 승인 전에 읽어 보라고 해요.
• 자동화에는 아직 못 씁니다. 노션 문서 FAQ에 따르면 노션 MCP는 지금 OAuth 승인을 사람이 직접 거쳐야 하고 사람 없이 도는 자동 인증은 준비 중입니다. 매일 정해진 시간에 혼자 도는 작업이라면 노션 API를 스크립트로 부르는 쪽을 검토하세요. 키 보관은 API 키로 내 도구 연결하기에 정리해 두었습니다.

GitHub 연결하기

GitHub의 공식 서버는 github/github-mcp-server이고 GitHub가 운영하는 원격 주소는 https://api.githubcopilot.com/mcp/입니다. 이 저장소에는 Codex 전용 설치 안내가 있고 거기서는 개인 접근 토큰(PAT)으로 붙입니다. 저장소 README에 따르면 원격 서버에 OAuth로 붙으려면 MCP를 쓰는 프로그램 쪽에서 GitHub 앱이나 OAuth 앱을 준비해 둬야 합니다. 그런데 Codex용 안내의 원격 연결 절에는 OAuth 방식이 없어요. OAuth는 같은 안내의 로컬 Docker 구성에만 나옵니다(아래).

1. 토큰을 좁게 발급합니다. GitHub 설정에서 토큰을 만들 때 필요한 권한만 고릅니다. 안내서는 최소 권한으로 시작하고 도구 요청이 권한 부족으로 실패할 때만 하나씩 늘리라고 권해요. 처음에는 읽기만 맡길 생각이라면 주소 끝에 readonly를 붙인 https://api.githubcopilot.com/mcp/readonly를 쓰는 방법도 있습니다. 원격 서버 문서에 따르면 이 주소는 읽기 도구만 제공합니다.

2. 토큰 값은 설정 파일에 쓰지 않습니다. Codex에는 토큰을 담을 환경변수의 이름만 알려 줍니다.

codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN

이 명령은 설정 파일에 아래와 같은 내용을 남깁니다.

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT_TOKEN"

3. Codex가 실행되는 환경에 그 변수를 둡니다. bearer_token_env_var는 Codex가 실행될 때 그 이름의 환경변수 값을 읽어 Authorization 헤더로 보내는 설정입니다. 터미널이라면 같은 창에서 변수를 넣은 뒤 codex를 실행하면 돼요. 데스크톱 앱이 터미널에서 설정한 환경변수를 받아 오는지는 공식 문서에서 확인하지 못했습니다. 앱에서 GitHub 도구가 안 보이면 이 부분부터 의심해 보세요.

토큰을 어디에 어떻게 보관할지는 API 키로 내 도구 연결하기의 보관 원칙이 그대로 적용됩니다. 채팅창에 붙여 넣지 않고, 파일에는 빈 값으로 만든 뒤 직접 채우고, 노출됐으면 지우는 게 아니라 폐기하고 새로 발급합니다. GitHub 안내서에는 토큰 값을 설정 파일에 직접 적는 Docker 예시도 있습니다. 그 파일이 공유되거나 커밋되면 토큰이 같이 나가니 위의 환경변수 방식을 권합니다.

Docker를 쓴다면 OAuth 로그인도 됩니다. 같은 안내서의 로컬 Docker 구성은 GitHub 공식 이미지를 내 컴퓨터에서 실행하고, 처음 쓸 때 브라우저 로그인을 띄워 토큰을 메모리에만 둡니다. 토큰을 만들고 보관하는 일이 없어지는 대신 Docker 설치가 필요해요. 설정은 안내서의 예시를 그대로 옮기세요.

4. 확인합니다. 안내서의 확인 순서는 /mcp에서 github 아래 도구가 보이는지 본 다음 "내 GitHub 저장소 목록을 보여 줘"처럼 읽기 요청을 하나 보내는 것입니다.

막힐 때 확인할 것

에러 메시지가 길어도 어디서 막혔는지부터 나누면 원인을 빨리 찾습니다. 아래는 공식 문서에 적힌 원인과 해결만 모은 표입니다.

노션처럼 OAuth로 붙인 서버는 "연결을 끊고 다시 붙이기"가 Codex에서는 두 명령입니다. codex mcp logout notion으로 저장된 인증을 지우고 codex mcp login notion으로 다시 로그인해요. 앱 문서에는 로그인이 필요할 때 누르는 Authenticate 버튼만 나오고 저장된 인증을 지우는 방법은 확인하지 못했습니다.

진단 정보가 더 필요하면 codex 대화 화면에서 /mcp verbose를 칩니다. 무엇이 나왔는지 그대로 Codex에게 보여 주고 "이 진단에서 어디가 문제인지 설명해 줘"라고 물어도 돼요. 이때 토큰 값이 화면에 찍혀 있지 않은지 먼저 봅니다.

Codex 자체 로그인에서 막혔다면

"codex 401"로 검색했는데 MCP 서버가 아니라 Codex 로그인 자체가 문제일 수도 있습니다. 인증 문서에 따르면 ChatGPT 계정으로 로그인한 세션은 쓰는 동안 토큰을 만료 전에 자동으로 갱신해서 보통은 다시 로그인할 일이 없어요. 그래도 막히면 로그아웃 후 다시 로그인합니다.

• 데스크톱 앱. 프로필 메뉴에서 지금 어떤 계정으로 로그인했는지 보고 Log out을 누른 뒤 다시 로그인합니다.
• CLI. codex login status로 지금 인증 방식을 보고 codex logout 후 다시 로그인합니다.

API 키로 로그인했다면 ChatGPT 요금제 사용량이 아니라 API 요금으로 따로 과금됩니다. 같은 문서는 API 키 로그인에서는 OAuth 연결 방식 때문에 일부 플러그인을 쓸 수 없다고도 적어 두었어요. 처음에는 ChatGPT 계정 로그인을 권합니다.

Codex에 어떤 MCP를 먼저 붙일까

Codex MCP 문서는 자주 쓰는 서버로 이런 목록을 듭니다. 추천 순위가 아니라 문서에 나온 순서입니다.

• OpenAI Docs MCP: OpenAI 개발자 문서 검색
• Context7: 최신 개발 문서 연결
• Figma(로컬·원격): 피그마 디자인 읽기
• Playwright, Chrome DevTools: 브라우저 조작과 확인
• Sentry: 오류 로그 보기
• GitHub: git만으로 안 되는 PR·이슈 관리

고르는 기준은 Claude Code에서와 같습니다. 지금 손으로 반복해서 옮기는 정보 하나를 정하고 거기에 필요한 서버부터 붙이세요. 서버마다 enabled_tools로 쓸 도구만 남기고 나머지는 꺼 둘 수 있습니다. 서버를 고르는 생각의 순서는 MCP 서버 추천 5개와 최소 설정에 Claude Code 기준으로 정리해 두었어요.

Claude Code와 같이 쓴다면

Codex와 Claude Code를 같이 쓰고 싶다면, 공식 문서로 확인되는 방법은 세 가지입니다.

1. 같은 MCP 서버를 양쪽에 붙입니다. 노션 연결 안내에는 Codex와 Claude Code 항목이 나란히 있습니다. Claude Code에서는 claude mcp add --transport http notion https://mcp.notion.com/mcp로 추가하고 /mcp에서 로그인해요. 인증은 도구마다 따로 합니다.

2. Claude Code 설정을 Codex로 가져옵니다. 가져오기 문서에 따르면 데스크톱 앱의 Settings > Import(아직 없으면 General의 Import other agent setup)에서 Claude Code를 고르면 지침 파일, settings.json, 스킬, 플러그인, MCP 서버 설정 등을 Codex로 옮겨 옵니다. 가져올 항목은 Select items to import 화면에서 직접 고릅니다.

CLI에서는 로컬 세션에서 /import를 치는데, 작업이 돌고 있을 때나 원격 세션에서는 쓸 수 없어요. 어느 쪽이든 원래 Claude Code 설정은 바뀌지 않습니다. 다만 문서는 사용자 지정 인증이나 헤더, 환경변수를 쓰는 MCP 서버는 가져온 뒤 다시 로그인해야 할 수 있다고 적어 두었습니다. GitHub처럼 토큰을 쓰는 서버는 가져온 뒤 다시 확인하세요.

3. 규칙 파일을 하나로 둡니다. Codex는 작업 전에 AGENTS.md를 읽습니다. Claude Code 메모리 문서에 따르면 Claude Code는 작업 폴더와 그 위 폴더에 CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md가 하나도 없을 때 AGENTS.md를 대신 읽습니다(v2.1.277 이상, 일부 세션 제외). CLAUDE.md가 있거나 AGENTS.md를 못 읽는 세션이라면 CLAUDE.md 안에 @AGENTS.md 한 줄을 넣어 불러오면 돼요. 비밀값 규칙이나 연결 규칙을 AGENTS.md에 적어 두면 두 도구가 같은 규칙을 따릅니다.

Codex를 MCP 서버로 띄워 Claude Code에서 부르는 방법을 소개한 글을 볼 수 있는데, 이 방법은 지금 쓸 수 없습니다. Codex MCP 서버 제거 안내에 따르면 codex mcp-server 명령은 제거됐어요. 대안으로 안내하는 app server는 MCP가 아닌 별도 방식이고 아직 실험 단계라 운영용으로는 지원하지 않는다고 적혀 있습니다. Codex가 외부 MCP 서버에 붙는 기능은 그대로 있어요.

MCP, 스킬, 서브에이전트가 각각 무엇을 맡는지는 MCP와 Skills 차이를 참고하세요.

정리

• Codex의 MCP 설정은 ~/.codex/config.toml 하나에 모이고 데스크톱 앱, CLI, IDE 확장이 같이 씁니다. 앱은 Settings > MCP servers, 터미널은 codex mcp add입니다.
• 노션은 주소 https://mcp.notion.com/mcp를 추가하고 codex mcp login notion 또는 앱의 Authenticate로 OAuth 로그인합니다. 쓰기는 writes로 묻게 합니다.
• GitHub는 Codex 안내서 기준으로 PAT를 쓰고 값이 아니라 환경변수 이름만 --bearer-token-env-var로 넘깁니다. 읽기만 맡길 땐 /readonly 주소를 씁니다.
• 401이 나면 MCP 서버 토큰 문제인지 Codex 로그인 문제인지부터 구분하고, OAuth 서버는 logout 후 login, 토큰 서버는 새 토큰 발급으로 풉니다.
• Claude Code와 함께 쓸 땐 같은 서버를 양쪽에 붙이거나 Import로 옮기고 규칙은 AGENTS.md 하나에 둡니다.

출처와 확인 (2026-10-08)

• Codex: Model Context Protocol (설정 파일 위치와 공유, 지원 방식과 인증, 앱의 MCP servers 경로, codex mcp add·list·login, /mcp, bearer_token_env_var, 인증 없이 연결되는 경우, 시작·도구 대기 시간, enabled_tools, default_tools_approval_mode, 예시 서버 목록. developers.openai.com/codex/mcp도 이 주소로 연결됨)
• Codex: Command line options (codex mcp 하위 명령과 옵션, OAuth 명령은 원격 서버만, /mcp verbose, /import, codex mcp-server 제거)
• Codex: Codex MCP server removal (codex mcp-server 제거, app server는 실험 단계)
• Codex: Authentication (토큰 자동 갱신, 로그아웃과 codex login status, API 키 로그인 과금과 플러그인 제한)
• Codex: Plugins (플러그인의 MCP 서버, Sign in with ChatGPT 베타 대상)
• Codex: Import from another agent (Settings > Import, /import, 가져오는 항목, MCP 인증 재확인)
• Codex: Custom instructions with AGENTS.md
• Notion MCP (노션 운영 원격 서버, OAuth, 할 수 있는 일)
• Connect to Notion MCP (Codex·Claude Code 설정, 인증 문제 해결, 자동 인증 미지원)
• Notion MCP security best practices (프롬프트 주입, 변경 전 확인)
• Notion MCP supported tools (요청 한도 대처)
• github/github-mcp-server (원격 주소, 호스트별 OAuth 준비 조건, 토큰 보안)
• GitHub MCP Server: Install in OpenAI Codex (PAT 설정, --bearer-token-env-var, Docker OAuth, 확인 순서, 문제 해결 표)
• GitHub MCP Server: Remote server (/readonly 주소)
• Claude Code: Memory (AGENTS.md 읽기 조건, @AGENTS.md 가져오기)