Codex MCP — 외부 컨텍스트를 복붙 대신 연결하기

공식 참고 자료: MCP · Best Practices · Sandboxing

커리큘럼 흐름

Codex 시작하기 — 설치, 첫 작업, 체크포인트까지 — 입문 루프
Codex 지시문 — AGENTS.md를 진짜 쓸모 있게 만드는 법 — 저장소 규칙
Codex 샌드박싱 — 권한, 승인, 클라우드 환경 이해하기 — 권한과 승인
Codex 작업 설계 — 소원 말고 이슈처럼 프롬프트 쓰기 — 좋은 task shape 만들기
Codex Skills — 반복 프롬프트를 재사용 가능한 워크플로우로 바꾸기 — 반복 워크플로우를 재사용 자산으로 만들기
Codex 서브에이전트 — 병렬 실행과 위임 패턴 — 병렬 실행과 위임
Codex MCP — 외부 컨텍스트를 복붙 대신 연결하기 — 외부 시스템 연결 ← 현재 문서
Codex 리뷰와 자동화 — /review, worktree, 반복 엔지니어링 운영하기 — 반복 작업 운영
Codex Worktrees — 브랜치 충돌 없이 병렬 실행하기
Codex 핸드오프 — 병렬 레인을 머지 가능한 결과로 연결하기
Codex 검증 루프 — 머지 전에 동작을 증명하기
Codex 릴리스 준비도 — 프로덕션 전 최종 게이트
Codex 첫날 안전 루프 — 초반 실수를 줄이는 입문 워크플로우
Codex 팀 딜리버리 플레이북 — 중급 레인 운영
Codex 고위험 변경 거버넌스 — 크리티컬 릴리스를 위한 고급 통제
Codex 운영 매뉴얼 — 팀의 일/주/릴리스 리듬 정렬하기
Codex 사고 복구 플레이북 — 프로덕션 압박 상황에서의 결정론적 대응
Codex 사고 후 하드닝 루프 — 복구를 내구성 있는 통제로 전환하기
Codex 카오스 복원력 드릴 — 실패가 오기 전에 리허설하기
Codex 복원력 지표와 SLO — 실패 전에 신뢰성을 측정하기
Codex Ralph 지속 루프 — 긴 작업을 검증 가능한 완료까지 가져가기

이 문서에서 참고한 공식 문서

CLI와 IDE가 MCP 구성을 공유하는 방식 — MCP
codex mcp add와 /mcp 명령 — MCP, CLI Slash Commands
권한을 넓히기 전에 sandbox를 먼저 설계해야 하는 이유 — Sandboxing

왜 MCP가 중요한가

많은 사용자가 외부 문서, 티켓, 대시보드 정보를 프롬프트에 복붙합니다. 하지만 이 방식은 금방 한계가 옵니다.

최신성이 떨어짐
길어짐
출처 확인이 어려움
반복 작업에 약함

MCP의 핵심 가치는 repo 밖의 컨텍스트를 구조적으로 연결한다는 데 있습니다. 즉, Codex를 단순한 코드 편집기가 아니라 외부 시스템을 조회하고 그 근거를 작업 순서에 반영하는 실행기로 바꿉니다.

MCP가 특히 잘 맞는 상황

다음처럼 코드만 봐서는 충분하지 않은 작업에서 효과가 큽니다.

내부 문서 포털 검색
Jira, Linear, GitHub issue 조회
디자인/사양 시스템 참조
사내 API 문서, runbook, playbook 조회
데이터베이스나 운영 도구에 대한 제한적 조회
incident 회고, 장애 대응 문서, 운영 체크리스트 조회

핵심 질문은 간단합니다. "이 작업을 제대로 하려면 repo 밖 근거가 필요한가?" 그렇다면 복붙보다 MCP 연결이 대체로 더 낫습니다.

기본 설정: 어디에 저장되고 어떻게 켜는가

MCP 문서에 따르면 Codex의 MCP 설정은 config.toml에 저장됩니다. 보통 개인 전역 설정은 ~/.codex/config.toml에 두고, trusted project에서는 .codex/config.toml처럼 프로젝트 범위 설정도 둘 수 있습니다.

이 구성이 중요한 이유는 두 가지입니다.

CLI와 IDE extension이 같은 구성을 공유할 수 있음
프로젝트별로 신뢰할 수 있는 서버 집합을 분리할 수 있음

가장 흔한 진입점은 두 개입니다.

서버 추가: codex mcp add ...
세션에서 확인: /mcp

예를 들면 다음처럼 추가할 수 있습니다.

codex mcp add context7 -- npx -y @upstash/context7-mcp

세션 안에서는 /mcp로 현재 연결된 MCP 도구를 확인하고, 어떤 서버가 보이는지 먼저 검증하세요. 연결 자체보다 중요한 것은 세션에서 실제로 인식되는지 입니다.

전역 설정과 프로젝트 설정을 나누는 기준

실무에서는 모든 서버를 전역으로 두기보다, 아래 기준으로 나누는 편이 안전합니다.

전역 `~/.codex/config.toml`에 두기 좋은 것

여러 저장소에서 공통으로 쓰는 문서 검색 서버
개인 지식 베이스나 개인 생산성 도구
팀과 무관한 개인 워크플로우용 서버

프로젝트 `.codex/config.toml`에 두기 좋은 것

특정 제품/고객/조직에만 해당하는 내부 도구
해당 repo에서만 신뢰되는 서버
프로젝트 온보딩과 함께 공유되어야 하는 컨텍스트

특히 프로젝트 범위 구성은 "이 저장소에서 무엇을 신뢰하는가"를 코드와 함께 남길 수 있다는 장점이 있습니다.

MCP를 붙인 뒤 프롬프트가 달라져야 한다

MCP를 연결했는데도 예전처럼 긴 배경 설명을 복붙하면 이점이 줄어듭니다. MCP 이후의 프롬프트는 맥락의 위치와 사용 순서를 지정해야 합니다.

예를 들어 이렇게 말할 수 있습니다.

이 repo의 결제 로직을 보기 전에,
연결된 issue tracker와 runbook에서 refund 관련 최근 변경 사항을 먼저 요약해줘.
그 다음 코드 영향 범위를 정리해줘.

좋은 프롬프트의 특징은 아래와 같습니다.

어떤 외부 소스를 먼저 볼지 적음
무엇을 추출할지 적음
그 결과를 코드 작업에 어떻게 연결할지 적음

반대로 나쁜 프롬프트는 단순히 "관련 문서도 참고해" 수준에서 끝납니다.

실전 프롬프트 패턴 5가지

1. 먼저 외부 사실을 정리하게 만들기

연결된 MCP 도구에서 이번 분기 로그인 장애 회고와 auth runbook을 먼저 읽고,
현재 저장소의 auth middleware 변경 전에 알아야 할 제약만 5줄로 정리해줘.

이 방식은 바로 구현으로 점프하기 전에, 외부 사실을 먼저 압축하게 만듭니다.

2. 외부 문서와 코드 차이를 찾게 만들기

연결된 문서 서버에서 API 인증 문서를 확인하고,
이 repo의 실제 구현과 어긋나는 부분만 diff 관점으로 요약해줘.

문서 drift 확인에 좋습니다.

3. 티켓 맥락을 읽고 변경 범위를 제한하기

연결된 issue tracker에서 PAY-481과 연결 티켓을 읽고,
이번 수정에 꼭 필요한 파일 후보만 우선순위로 제안해줘.

이 방식은 scope를 좁히는 데 도움이 됩니다.

4. 운영 문서를 근거로 체크리스트를 만들기

incident runbook과 release checklist를 읽고,
이번 배포 전에 확인해야 할 항목만 실행 순서대로 체크리스트로 정리해줘.

코드 수정 외의 운영 준비에도 유용합니다.

5. 답변 안에 근거와 출처를 남기게 하기

연결된 문서 서버를 사용해서 이 질문에 답해줘.
핵심 규칙을 네 말로 요약하고,
어떤 외부 소스를 참고했는지 밝힌 뒤,
그 다음 최소 변경안을 제안해줘.

이 방식은 출력이 눈에 보이는 근거에 묶여 있게 만들어서, 운영성 높은 작업에서 특히 유용합니다.

좋은 MCP 운영 원칙

1. read-only부터 시작

처음부터 write capability가 있는 서버를 넓게 붙이지 마세요. 조회 가치가 큰 시스템부터 읽기 전용으로 연결하는 편이 훨씬 안전합니다.

2. 신뢰 가능한 서버만 좁게 연결

문서, 티켓, 검색 같이 가치가 높은 시스템부터 붙이세요. "연결할 수 있다"와 "항상 연결해야 한다"는 다릅니다.

3. 팀 규칙은 저장소 지시문에 남기기

어떤 MCP 서버를 신뢰하는지, 어떤 용도로 쓰는지 AGENTS.md 같은 저장소 규칙 문서에 남겨두면 온보딩과 리뷰가 쉬워집니다.

4. 시크릿과 권한을 최소화하기

MCP도 결국 외부 시스템 접점입니다. 샌드박스와 동일하게 최소 권한 원칙이 중요합니다.

5. 연결보다 사용 순서를 설계하기

좋은 운영은 서버 수가 아니라 조회 순서와 의사결정 흐름에서 나옵니다. 예: "티켓 → runbook → 코드" 같은 순서를 팀이 반복적으로 쓰면 훨씬 안정적입니다.

팀에 도입할 때 추천하는 순서

한 번에 많은 서버를 여는 대신 아래 단계로 올리면 실패가 줄어듭니다.

문서 검색처럼 read-only 가치가 큰 서버 1개 추가
/mcp로 세션 인식 확인
프롬프트에서 조회 순서를 명시하는 패턴 정착
팀 규칙 문서에 신뢰 서버와 사용 목적 기록
필요한 경우에만 추가 서버 확장

이 순서는 "연결은 많지만 아무도 안 쓰는 상태"를 피하는 데 도움이 됩니다.

skill과 함께 쓰면 더 강하다

MCP는 컨텍스트를 가져오고, skill은 절차를 패키징합니다. 둘을 조합하면 반복적인 업무 흐름이 더 강해집니다.

예시:

release note skill이 MCP로 이슈/PR 정보를 읽고 초안을 생성
bug triage skill이 incident 문서와 ticket 상태를 함께 참조
docs update skill이 공식 문서를 MCP로 조회해 drift를 점검
onboarding skill이 팀 runbook과 architecture 문서를 먼저 읽고 환경 점검 순서를 안내

즉, MCP는 재료를 공급하고 skill은 조리 순서를 고정합니다. 반복되는 운영 흐름일수록 둘을 함께 설계하는 편이 좋습니다.

sandbox와 MCP를 따로 생각하면 안 되는 이유

MCP를 붙이면 Codex가 더 많은 외부 사실을 보게 됩니다. 그래서 sandbox 중요도가 줄어드는 게 아니라 오히려 커집니다.

특히 아래를 함께 점검하세요.

이 서버는 read-only인가?
write가 있다면 정말 필요한가?
어떤 프로젝트에서만 허용해야 하는가?
시크릿 노출 범위는 최소화됐는가?
실패 시 Codex가 어디까지 자동으로 진행해도 되는가?

외부 연결이 늘수록 권한 설계도 더 정교해야 합니다.

흔한 실패 패턴과 바로잡는 법

“서버는 연결했는데 Codex가 안 쓴다”

프롬프트에서 어떤 외부 맥락이 필요한지, 어떤 순서로 읽어야 하는지를 분명히 말하지 않았을 수 있습니다.

대응: "무슨 정보를 어디서 먼저 읽고, 그걸 무엇에 쓸지"를 문장에 넣으세요.

“연결이 너무 많아 무엇을 믿어야 할지 모르겠다”

팀이 신뢰하는 MCP 서버 집합이 너무 넓을 가능성이 큽니다.

대응: 핵심 서버 몇 개만 남기고, 역할이 겹치는 서버는 줄이세요.

“MCP가 있으니 복붙 프롬프트를 줄일 수는 있는데 결과가 산만하다”

외부 근거를 요약하거나 우선순위화하지 않고 바로 구현으로 넘어갈 때 생깁니다.

대응: 먼저 요약, 그다음 영향 범위, 마지막으로 구현 순서를 요구하세요.

“MCP가 있으니 sandbox는 덜 중요하다”

오히려 반대입니다. 외부 연결이 늘수록 권한 경계 설계는 더 중요합니다.

서버를 추가하기 전 체크리스트

정말 repo 밖 정보가 필요한가?
이번 작업에 필요한 서버만 연결하려는가?
read-only로 시작할 수 있는가?
전역 구성보다 .codex/config.toml로 두는 편이 더 안전한가?
어떤 서버를 신뢰하는지 팀이 합의했는가?

MCP를 붙여 Codex에 요청하기 전 체크리스트

/mcp로 실제 인식된 서버를 확인했는가?
어떤 외부 소스를 먼저 읽을지 적었는가?
프롬프트에 조회 순서와 기대 산출물을 적었는가?
먼저 요약과 출처를 요청했는가?
외부 요약을 먼저 받고 구현으로 넘어가고 있는가?

바로 써먹는 미니 운영 플레이북

문서 기반 버그 수정

/mcp로 서버 인식 확인
runbook/incident 문서 요약 요청
티켓 상태와 최근 변경 사항 요약 요청
코드 영향 범위 정리 요청
수정 진행

사양 drift 점검

외부 API 문서 조회
repo 구현과 비교
불일치 항목만 정리
수정 또는 문서 업데이트 결정

릴리즈 준비

릴리즈 체크리스트와 관련 티켓 조회
빠진 항목 요약
검증 순서 재정리
반복되면 skill + automation으로 승격

Codex를 “코드 편집기”에서 “맥락을 연결한 작업자”로 바꾸는 전환점이 바로 MCP입니다. 중요한 것은 서버 개수보다, 신뢰할 수 있는 연결을 작은 집합으로 유지하고 작업 순서에 녹여 넣는 운영 방식입니다.

연결된 가이드