책에 포함된 노트요즘 바이브 코딩: Codex로 일하는 개발자의 완전 가이드

Chapter 11. MCP로 외부 시스템 연결

2026-04-25Views 108약 11분생성형 AI 활용

Chapter 11. MCP로 외부 시스템 연결

Codex를 처음 쓰면 대개 파일 수정 능력부터 봅니다. 코드를 읽고, 고치고, 테스트를 돌리고, 커밋까지 만드는 모습이 꽤 인상적이니까요. 그런데 실무에서 진짜 차이를 만드는 순간은 그다음에 옵니다.

이슈는 Linear에 있고, 스펙은 Notion에 있고, 리뷰와 머지는 GitHub에서 하고, 팀 대화는 Slack에서 하고, 데이터는 Postgres에 있습니다. 즉, 코드만 잘 다뤄서는 일이 끝나지 않습니다. 개발자의 하루는 편집기 바깥에 훨씬 더 많이 흩어져 있습니다.

바로 여기서 MCP가 필요합니다. MCP 서버는 Codex가 로컬 프로젝트 밖의 도구와 정보에 접근하도록 해 주는 연결점입니다. 쉽게 말해, Skills가 어떻게 일할지를 가르치는 플레이북이라면, MCP는 어디에 가서 무엇을 읽고 실행할지를 열어 주는 출입증입니다.¹

MCP를 이해하는 순간 Codex는 "코드 잘 고치는 도구"에서 "실제 업무 시스템을 오가는 에이전트"로 성격이 바뀝니다.

PART 03-11. MCP로 외부 시스템 연결

MCP는 API 연동보다 한 단계 더 실무적이다

MCP를 처음 들으면 "그냥 API 붙이는 거 아냐?"라고 생각하기 쉽습니다. 반은 맞고, 반은 틀립니다.

API 연동이 개발자 관점의 연결이라면, MCP는 에이전트 관점의 연결입니다. 서비스마다 제각각인 API를 Codex가 직접 다 배우는 대신, 각 서비스용 MCP 서버가 "쓸 수 있는 도구 목록"을 노출합니다. Codex는 그 도구를 함수처럼 호출하고, 결과를 다시 맥락으로 흡수합니다.

그래서 흐름이 단순해집니다.

GitHub MCP는 PR, 이슈, 저장소 정보를 다루는 도구를 제공한다.
Notion MCP는 페이지, 데이터베이스, 코멘트 같은 워크스페이스 객체를 다루는 도구를 제공한다.
Slack MCP는 채널, 스레드, 메시지, 리마인더 같은 협업 문맥을 다루는 도구를 제공한다.

이 구조가 좋은 이유는 분명합니다. Codex 입장에서는 "외부 시스템과 상호작용하는 방식"이 비슷해지고, 사용자 입장에서는 자연어로 요청하되 실제 실행은 도구 호출로 안정화할 수 있습니다.

Codex에서 MCP는 두 가지 방식으로 붙는다

실전에서 MCP 연결은 크게 두 갈래로 생각하면 편합니다.

첫 번째는 로컬 stdio 방식입니다. 내 컴퓨터에서 명령어로 MCP 서버를 띄우고, Codex가 그 프로세스와 통신하는 형태입니다. 보통 ~/.codex/config.toml의 mcp_servers 블록에 command, args, env를 적어 연결합니다.²

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "..." }

이 방식은 이해하기 쉽고, 로컬 네트워크나 개인 토큰을 활용하기 좋습니다. 사내망 안에서만 보이는 시스템이나, 아직 원격 MCP 엔드포인트를 따로 운영하지 않는 도구와 붙일 때 특히 실용적입니다.

두 번째는 원격 HTTP 방식입니다. 이 경우 Codex는 URL 기반 MCP 서버에 접속하고, 필요하면 OAuth 로그인으로 인증합니다. 예를 들어 Linear는 https://mcp.linear.app/mcp 같은 원격 엔드포인트를 쓰며, Codex에서 rmcp_client 기능을 켜고 로그인 절차를 거쳐 연결할 수 있습니다.³

[features]
rmcp_client = true

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"

둘 중 무엇이 더 좋다고 단정할 필요는 없습니다.

로컬 stdio는 내 환경 통제가 쉽고, 원격 HTTP는 설치가 간단하며 인증 흐름이 깔끔합니다. 중요한 것은 "이 연결이 내 프로젝트의 어디에 필요한가"입니다. 한마디로, 기술보다 업무 흐름에 맞춰 선택하는 편이 낫습니다.

먼저 연결할 가치가 큰 5개 시스템

아래 다섯 개는 한국 개발자 실무에서 Codex와 붙였을 때 체감이 큰 축입니다.

시스템	왜 붙이나	Codex가 잘하는 일
GitHub	코드 변경과 협업의 중심	이슈 읽기, PR 초안 만들기, 리뷰 맥락 정리
Slack	요청과 진행 상황이 모이는 곳	스레드 문맥 읽기, 진행 상황 보고, 멘션 기반 작업 시작
Notion	스펙과 회의 기록의 저장소	PRD 읽기, 구현 체크리스트 생성, 문서 업데이트
Linear	제품팀과 개발팀의 과제 허브	이슈 조회, 관련 작업 연결, 상태 기반 구현 우선순위 파악
Postgres	데이터 구조와 품질의 핵심	스키마 점검, 문서 검색, 안전한 쿼리 보조

이 다섯 개가 중요한 이유는 단순합니다. "무엇을 만들까"에서 "어떻게 굴러가고 있지"까지 한 사이클을 거의 덮기 때문입니다.

GitHub MCP: Codex를 진짜 개발 워크플로 안으로 넣는 연결

GitHub MCP는 가장 먼저 붙일 가치가 큽니다. 이유는 명확합니다. 에이전트가 코드를 고치는 것만으로는 부족하고, 변경 내역을 협업 시스템에 올려야 비로소 일이 끝나기 때문입니다.

실무에서 GitHub MCP가 빛나는 순간은 이런 때입니다.

버그 수정 요청을 받았을 때 관련 이슈를 읽고, 브랜치를 만들고, 수정 후 테스트 결과를 요약하고, PR 설명까지 초안으로 작성하는 흐름입니다. 사람이 일일이 복붙하던 맥락 전달이 줄어듭니다.

커뮤니티 예시에서도 GitHub MCP는 로컬 Codex CLI와 함께 자주 쓰입니다. 예를 들어 Slack에서 받은 요청을 바탕으로 Codex가 로컬 프로젝트를 수정하고, 진행 상황은 Slack 스레드에 남기고, 코드 변경과 PR 생성은 GitHub MCP로 처리하는 식입니다.⁴

로컬 설정 예시는 다음과 같은 감각으로 이해하면 됩니다.

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "github_pat_..." }

여기서 핵심은 권한입니다. GitHub 토큰은 편할수록 위험해집니다. 저장소 범위를 최소화하고, 처음에는 중요하지 않은 저장소에서만 써 보는 편이 낫습니다. Codex가 똑똑하다고 해서, 토큰까지 똑똑하게 제한해 주지는 않습니다.

Slack MCP: 요청과 보고가 같은 스레드에서 닫힌다

Slack을 붙이면 Codex의 존재감이 확 달라집니다. 이제 사용자는 터미널 앞에 앉아 있지 않아도 됩니다. 공식 Codex Slack 연동에서는 채널이나 스레드에서 @Codex를 멘션해 코딩 작업을 시작할 수 있고, Codex는 클라우드 태스크를 만들고 결과를 다시 스레드에 답합니다.⁵

또 Slack MCP 서버 자체는 워크스페이스 데이터에 대한 안전한 접근을 제공하도록 설계되어 있습니다.⁶ 이 말은 중요합니다. Slack은 단순 메신저가 아니라 팀의 살아 있는 문맥 창고이기 때문입니다. 최근 결정, 첨부 링크, 장애 공유, 임시 합의가 모두 여기에 쌓입니다.

Slack MCP가 특히 강한 패턴은 두 가지입니다.

하나는 요청 시작점입니다. 예를 들어 출근길 지하철에서 이렇게 보낼 수 있습니다.

@Codex 로그인 검증 에러 고치고, 테스트 돌리고, PR 만들어줘

다른 하나는 진행 보고 채널입니다. Codex가 작업 중간 상태, 실패 원인, 최종 PR 링크를 같은 스레드에 남기면 사람이 뒤늦게 들어와도 상황을 곧바로 따라잡을 수 있습니다.⁴

한국 팀에서 이 연결이 특히 좋은 이유는, 메신저가 개발 도구보다 먼저 열려 있는 시간이 길기 때문입니다. "일이 시작되는 곳"과 "일이 보고되는 곳"이 같아지면 handoff가 눈에 띄게 줄어듭니다.

Notion MCP: 스펙을 복붙하지 말고, 그대로 읽게 하자

많은 팀이 아직도 이렇게 일합니다.

기획자가 Notion에 PRD를 써 둡니다. 개발자는 그 내용을 읽고, 필요한 부분을 복사해 AI에게 붙입니다. 빠져도 안 되고, 너무 길어도 안 됩니다. 한마디로 귀찮고, 자주 틀립니다.

Notion MCP를 붙이면 이 과정이 훨씬 자연스러워집니다. Codex는 Notion 페이지나 데이터베이스를 직접 읽고, 필요한 구조를 추출하고, 구현 계획이나 체크리스트로 바꿀 수 있습니다. Codex에서는 원격 MCP 서버로 Notion을 등록하고, 로그인 절차를 통해 워크스페이스 권한을 승인하는 방식으로 연결할 수 있습니다.⁷

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

그리고 인증은 보통 다음처럼 이어집니다.

codex mcp login notion

이 연결이 실무에서 주는 가장 큰 이점은 정확도보다 문맥 보존입니다. 사람이 복붙하면 요약이 섞이고, 빼먹음이 생기고, 최신 버전이 아닌 내용을 들고 올 때도 있습니다. 반면 Codex가 원문 스펙을 직접 읽으면 "무엇이 소스 오브 트루스인가"가 분명해집니다.

예를 들어 Next.js + Supabase SaaS를 만든다고 해봅시다. Notion의 PRD에는 회원가입 플로우, 구독 해지 정책, 관리자 권한 규칙이 적혀 있습니다. 이걸 Codex가 직접 읽으면 단순 구현뿐 아니라, 누락 테스트 후보와 엣지 케이스 후보까지 더 자연스럽게 뽑아낼 수 있습니다.

Linear MCP: 해야 할 일을 에이전트도 같은 칸반에서 보게 만들기

Codex를 쓰면서 자주 생기는 문제가 하나 있습니다. 잘 만들기는 하는데, 지금 무엇이 더 중요한지 모른다는 점입니다.

Linear를 붙이면 이 문제가 크게 줄어듭니다. Linear MCP를 Codex CLI나 IDE 확장에 연결하면 Codex는 기존 이슈를 검색하고, 새 이슈를 만들고, 관련 컨텍스트를 복사하지 않고도 참조할 수 있습니다.³

이 연결이 특히 좋은 팀은 기획과 개발이 Linear 중심으로 굴러가는 팀입니다.

"이 버그가 어떤 프로젝트에 묶여 있지?"
"이 기능은 이미 비슷한 이슈가 있었나?"
"지금 스프린트에 포함된 범위가 어디까지지?"

이런 질문에 답할 수 있어야 Codex가 더 현실적인 구현을 합니다. 단순히 코드만 잘 짜는 것이 아니라, 우선순위와 업무 단위를 이해한 상태로 움직이기 시작합니다.

작은 팁을 하나 덧붙이면, Linear는 구현 시작 전에 붙일수록 좋습니다. GitHub는 결과물을 올리는 쪽에 가깝고, Linear는 무엇을 할지 정하는 쪽에 가깝기 때문입니다. 둘을 함께 쓰면 "무엇을 만들까"와 "어떻게 협업할까"가 자연스럽게 이어집니다.

Postgres MCP: 데이터는 가장 천천히 망가지고, 가장 비싸게 복구된다

Postgres 연결은 조금 더 조심해서 접근해야 합니다. 이유는 간단합니다. GitHub나 Notion은 잘못 다뤄도 대개 되돌릴 수 있지만, 데이터는 한 번 잘못 건드리면 후폭풍이 오래갑니다.

그래서 Postgres MCP는 두 갈래로 나눠 생각하는 편이 안전합니다.

첫째는 문서·베스트프랙티스형 MCP입니다. 예를 들어 pg-aiguide는 PostgreSQL 공식 문서와 생태계 문서를 검색하고, AI가 더 나은 스키마와 쿼리를 만들도록 돕는 공개 MCP 서버를 제공합니다.⁸ 이것부터 붙이면 안전하게 체감 효과를 얻기 좋습니다.

codex mcp add --url "https://mcp.tigerdata.com/docs" pg-aiguide

둘째는 실제 데이터베이스 접근형 MCP입니다. 이 경우는 반드시 안전장치를 먼저 생각해야 합니다. 실무 가이드들은 공통적으로 최소 권한, 읽기 전용 역할, 파라미터 바인딩, 단일 쿼리 제한, 짧은 타임아웃, 행 수 제한, 감사 로그 같은 가드레일을 권합니다.⁹

이 원칙은 정말 중요합니다.

"AI에게 DB도 붙여 보자"는 생각은 멋져 보이지만, 운영 DB에서 SELECT 하나도 잘못 설계하면 생각보다 큰 비용이 납니다. 그래서 처음에는 이런 순서가 좋습니다.

문서 검색형 Postgres MCP로 스키마 설계와 SQL 품질부터 높인다.
그다음 읽기 전용 진단형 도구만 제한적으로 연다.
마지막까지도 쓰기 작업은 강한 승인 절차 아래에 둔다.

특히 Supabase를 쓰는 팀이라면 더 그렇습니다. 결국 밑단은 Postgres이기 때문에, 마이그레이션과 인덱스 전략, 제약조건 설계 품질이 서비스의 체력과 바로 연결됩니다.

Skill + MCP 페어링이 실무 생산성을 만든다

MCP만 붙여도 좋지만, 진짜 생산성은 Skill과 같이 쓸 때 나옵니다. 이유는 단순합니다. MCP는 도구를 열어 주고, Skill은 그 도구를 어떤 순서와 기준으로 쓸지 정리해 주기 때문입니다.

좋은 조합은 대체로 아래 세 가지 패턴으로 수렴합니다.

읽고 나서 계획하는 패턴

Notion MCP로 PRD를 읽고, Linear MCP로 관련 이슈를 모은 뒤, prd-to-implementation-plan 같은 Skill로 구현 계획을 만드는 방식입니다.

이 패턴은 기획이 자주 바뀌는 스타트업에 잘 맞습니다. 사람이 수동으로 요약하면 자꾸 해석이 섞이는데, Codex는 원문을 읽고 정해진 Skill 절차대로 구현 항목을 뽑아낼 수 있습니다.

읽고 나서 행동하는 패턴

GitHub MCP로 이슈와 기존 PR을 읽고, bugfix-with-tests Skill로 수정 절차를 밟고, 다시 GitHub MCP로 PR을 여는 방식입니다.

이 패턴은 Express + MongoDB 운영 API 서버 같은 프로젝트에 특히 잘 맞습니다. 버그 수정 자체보다 "관련 이슈를 읽고, 재현 조건을 확인하고, 테스트까지 넣고, 머지 가능한 형태로 정리하는 것"이 더 중요할 때가 많기 때문입니다.

읽고 나서 점검하는 패턴

Postgres MCP나 문서형 DB MCP로 관련 정보를 모으고, migration-safety-review Skill로 위험도를 평가하는 방식입니다.

이 조합은 속도보다 사고 방지가 더 중요한 작업에 잘 맞습니다. 마이그레이션, 권한 정책, 인덱스 변경은 항상 이런 식으로 다뤄야 합니다.

정리하면 이렇습니다.

MCP가 손이라면 Skill은 손동작의 순서입니다. 손만 열어 두면 산만해지고, 순서만 있으면 아무것도 못 만집니다. 둘이 붙어야 비로소 일하는 방식이 됩니다.

agents/openai.yaml로 '이 프로젝트가 기대하는 연결'을 선언하자

실무에서 은근히 많이 낭비되는 시간이 있습니다.

"이 레포에서는 어떤 MCP를 써야 하죠?" "Linear도 붙여야 하나요?" "Notion 스펙을 읽고 구현하라는 건가요, 아니면 그냥 코드만 보면 되나요?"

이런 혼란을 줄이려면 프로젝트 안에 agents/openai.yaml 같은 선언 파일을 두고, 이 저장소가 기대하는 에이전트 의존성을 명시해 두는 편이 좋습니다. 핵심은 자동화 그 자체보다 운영 의도 문서화입니다.

예를 들면 이런 식입니다.

project: next-supabase-saas
skills:
  - prd-to-implementation-plan
  - next-supabase-pr-review
  - migration-safety-review
mcp:
  required:
    - github
    - notion
    - linear
  optional:
    - slack
    - pg-aiguide
workflows:
  - name: feature-delivery
    steps:
      - read notion PRD
      - inspect linked linear issue
      - implement in codebase
      - open GitHub PR

이 파일의 역할은 거창하지 않습니다.

사람에게는 온보딩 문서이고, 팀에게는 합의된 의존성 목록이며, Codex 운영 관점에서는 "이 프로젝트가 기대하는 외부 문맥"을 정리한 지도입니다. 특히 프로젝트가 커질수록 config.toml 같은 개인 설정만으로는 의도가 공유되지 않기 때문에, 저장소 안에 이런 선언 레이어를 두는 편이 훨씬 낫습니다.

requirements.toml로 허용된 MCP만 쓰게 만들어라

MCP가 강력해질수록 꼭 같이 와야 하는 것이 거버넌스입니다. 이전 장에서 샌드박스와 승인 정책을 다뤘다면, 여기서는 그 원칙을 외부 시스템 연결에 적용해야 합니다.

핵심은 간단합니다.

쓸 수 있는 MCP 서버를 미리 정하고, 그 밖은 기본 차단으로 가는 것.

예를 들어 팀 정책이 이렇다고 해봅시다.

GitHub, Linear, Notion만 조직 승인 서버로 허용한다.
Slack은 읽기/쓰기 범위를 분리해서 승인한다.
데이터베이스 계열 MCP는 읽기 전용 서버만 허용한다.
프로덕션 변경이 가능한 서버는 항상 사람 승인 단계를 거치게 한다.

이런 정책을 requirements.toml로 관리하면, 개인이 임의로 강한 권한의 MCP를 추가해 쓰는 일을 줄일 수 있습니다. 특히 엔터프라이즈나 보안 민감 조직에서는 "어떤 MCP를 쓸 수 있나"가 기능 문제보다 먼저 결정되어야 합니다.

여기서 중요한 운영 원칙은 네 가지입니다.

allowlist 우선: 승인된 서버만 허용한다.
권한 분리: 읽기와 쓰기를 같은 서버라도 다르게 본다.
민감 시스템 축소: 운영 DB, 배포, 결제 시스템은 최소 범위만 연다.
감사 가능성 확보: 누가 어떤 서버를 통해 어떤 작업을 했는지 추적 가능해야 한다.

Codex를 팀에 배포할수록 이 원칙은 더 중요해집니다. 개인 실험에서는 "편하게 붙여 보자"가 통하지만, 조직 운영에서는 "무엇을 못 하게 막을 것인가"가 더 중요합니다.

한국 팀에 맞는 첫 번째 실전 조합

처음부터 모든 시스템을 다 붙일 필요는 없습니다. 오히려 실패 확률만 올라갑니다. 한국 개발팀이라면 아래 조합으로 시작하는 것이 현실적입니다.

Next.js + Supabase SaaS 팀 기준으로 보면,

요구사항 원문은 Notion에서 읽는다.
우선순위와 작업 단위는 Linear에서 읽는다.
실제 코드 변경과 PR은 GitHub에서 처리한다.
진행 보고가 꼭 필요할 때만 Slack을 붙인다.
Postgres는 문서 검색형 MCP부터 시작한다.

이 흐름이 좋은 이유는 균형이 맞기 때문입니다.

기획 문맥, 작업 문맥, 코드 문맥은 확보하되, 데이터와 메신저 자동화는 보수적으로 붙입니다. 처음부터 Slack 쓰기 권한, DB 쓰기 권한, 배포 권한까지 다 열면 멋있어 보일 수는 있지만 팀은 जल्दी 피곤해집니다.

MCP를 붙일 때 자주 망하는 패턴

MCP는 강력하지만, 세팅만 많고 성과는 없는 상태로 가기 쉽습니다. 대개 아래 패턴에서 망합니다.

연결 수집이 목적이 된다. 실제로 안 쓰는 서버가 늘어난다.
읽기 전용으로 충분한데 쓰기 권한부터 연다.
Skill 없이 MCP만 잔뜩 붙여서 도구 호출이 산만해진다.
프로젝트 의존성을 문서화하지 않아 팀원마다 연결 상태가 다르다.
승인 정책 없이 로컬 토큰을 과하게 넣고 자동 실행부터 켠다.

특히 세 번째가 치명적입니다.

MCP 서버가 많아질수록 Codex가 할 수 있는 일은 늘어나지만, "지금 어떤 순서로 무엇을 해야 하는가"는 오히려 흐려질 수 있습니다. 그래서 외부 연결이 늘어날수록 AGENTS.md와 Skills의 중요성이 더 커집니다. 연결이 많을수록 지도가 더 필요해지는 셈입니다.

결국 MCP는 Codex의 세계를 넓히는 것이 아니라, 일의 경계를 없애는 일이다

개발자는 원래 여러 시스템 사이를 뛰어다니며 일합니다. 브라우저에서 스펙을 보고, 메신저에서 요청을 받고, 이슈 트래커에서 우선순위를 확인하고, GitHub에서 협업하고, 데이터베이스 상태를 확인합니다.

MCP는 이 분절된 이동을 줄여 줍니다. Codex가 그 시스템들을 직접 드나들 수 있게 되면, 사람은 "복붙 전달자"가 아니라 "판단자와 리뷰어"에 더 가까워집니다.

이 변화가 꽤 큽니다.

예전에는 AI에게 일을 시키려면 우리가 맥락을 다시 포장해서 넘겨야 했습니다. 이제는 Codex가 필요한 문맥을 직접 읽고, 필요한 도구를 호출하고, 다시 결과를 협업 흐름 안으로 돌려놓을 수 있습니다. Slack 스레드에 진행 상황을 남기고, GitHub에 PR을 만들고, Notion 스펙을 읽고, Linear 이슈를 참조하는 순간, Codex는 더 이상 편집기 안의 조수가 아닙니다.⁴⁵

바로 이 지점에서 MCP의 진짜 의미가 드러납니다.

Codex는 코드를 쓰는 에이전트가 아니라, 일을 끝내는 에이전트가 된다.

다음 장에서는 이렇게 넓어진 작업 범위를 더 효율적으로 분산하는 방법, 즉 Subagent와 병렬 워크플로를 다뤄보겠습니다.