Codex MCP 서버 연결 방법: 외부 개발 도구 연동하기

Codex MCP 서버를 연결하면 코드 저장소 안의 정보뿐 아니라 최신 개발 문서, 브라우저 테스트, 디자인 파일, 이슈와 관측 데이터 같은 외부 도구를 작업 흐름에 포함할 수 있습니다. 하지만 연결만 성공했다고 바로 모든 도구를 허용하면 토큰 노출이나 의도하지 않은 쓰기 작업으로 이어질 수 있습니다. STDIO와 원격 HTTP의 차이부터 CLI 등록, config.toml, OAuth, 최소 권한과 오류 진단까지 순서대로 정리했습니다.

Codex MCP란 무엇인가

MCP(Model Context Protocol)는 AI 모델이 외부 도구와 컨텍스트를 정해진 방식으로 발견하고 호출하도록 연결하는 규격입니다. Codex에 MCP 서버를 추가하면 개발 문서를 검색하거나 브라우저를 검사하고, 디자인 자료나 이슈를 조회하는 기능을 도구처럼 사용할 수 있습니다. 먼저 에이전트와 도구 호출 구조가 필요하다면 AI 에이전트 구축 기본 가이드에서 구성 요소를 확인할 수 있습니다.

OpenAI 공식 문서에 따르면 Codex 호스트는 로컬 프로세스로 실행하는 STDIO 서버와 주소로 접속하는 Streamable HTTP 서버를 지원합니다. ChatGPT 데스크톱 앱, Codex CLI와 IDE 확장은 같은 Codex 호스트에서 MCP 설정을 공유하므로 한 번 등록한 뒤 다른 클라이언트에서도 사용할 수 있습니다. 반면 ChatGPT 웹은 로컬 설정 파일을 직접 읽지 않고 플러그인을 통해 원격 MCP 도구를 사용합니다.

연결 전에 준비할 것

• Codex CLI가 설치되어 있고 로그인이 완료됐는지 확인합니다.
• 연결할 MCP 서버의 공식 저장소, 배포 주체와 설치 문서를 확인합니다.
• 서버가 STDIO인지 Streamable HTTP인지 구분합니다.
• 필요한 런타임과 실행 명령, 서버 URL을 준비합니다.
• OAuth, Bearer 토큰 또는 별도 헤더가 필요한지 확인합니다.
• Codex에 실제로 필요한 도구만 목록으로 정리합니다.
• 운영 데이터가 아닌 테스트 프로젝트에서 먼저 연결합니다.

STDIO와 Streamable HTTP 중 무엇을 선택할까

구분	STDIO MCP	Streamable HTTP MCP
실행 위치	Codex가 로컬 명령으로 프로세스를 시작	URL에 배포된 서버로 접속
주요 설정	command, args, env, cwd	url, OAuth·Bearer 토큰, 헤더
적합한 상황	로컬 문서·브라우저·개발 도구 연결	팀 공용 서비스와 원격 API 연결
주의점	패키지 실행 권한과 로컬 파일 접근	서버 신뢰성, TLS, 인증과 데이터 전송

개인 개발 환경에서 빠르게 검증하려면 STDIO가 단순할 수 있습니다. 팀이 중앙에서 관리하고 여러 개발자가 같은 서비스를 사용한다면 원격 HTTP가 편리하지만 인증과 네트워크 경계를 더 엄격하게 검토해야 합니다.

방법 1: CLI로 STDIO MCP 서버 연결하기

CLI에서는 서버 이름 뒤에 MCP 서버를 실행할 명령을 적습니다. 다음은 OpenAI 공식 문서에 나온 개발 문서용 Context7 등록 예시입니다.

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

-- 앞은 Codex MCP 등록 옵션이고, 뒤는 실제 STDIO 서버 실행 명령입니다. 인터넷에서 찾은 패키지를 곧바로 npx -y로 실행하기 전에 패키지 이름, 배포자, 최신 변경과 설치 스크립트를 확인하세요. 조직 환경에서는 버전을 고정하고 승인된 패키지 레지스트리를 사용하는 편이 안전합니다.

환경 변수가 필요한 경우

codex mcp add dev-tools \
  -- node ./mcp-server.js

인증값이 필요해도 실제 비밀값을 명령 인수나 셸 기록에 그대로 남기지 마세요. 아래 config.toml 예시처럼 Codex에는 환경 변수 이름만 전달하고 값은 운영체제의 비밀 저장소, CI 시크릿 또는 실행 환경에서 주입하는 편이 안전합니다.

방법 2: 원격 HTTP MCP 서버 연결하기

원격 서버는 URL로 등록합니다. OAuth 클라이언트를 미리 등록해야 하는 서비스라면 공식 문서의 다음 형식을 사용할 수 있습니다.

codex mcp add example \
  --url https://mcp.example.com/mcp \
  --oauth-client-id my-client

등록 과정에서 Codex가 표시하는 OAuth 콜백 URL을 공급자 설정에 정확히 입력해야 합니다. 서버가 일반 OAuth 로그인을 지원한다면 등록 후 다음 명령으로 인증을 시작합니다.

codex mcp login example

회사 내부 서버에는 유효한 TLS 인증서를 사용하고, 공개 인터넷에 서버를 노출해야 하는지 먼저 검토하세요. URL의 경로와 쿼리가 바뀌면 OAuth 콜백 식별에도 영향을 줄 수 있으므로 운영 주소를 확정한 뒤 등록하는 것이 좋습니다.

연결 상태 확인하기

codex mcp list
codex mcp --help

codex mcp list에서는 등록된 서버를 확인하고, codex mcp --help에서는 현재 설치된 CLI가 지원하는 명령을 확인할 수 있습니다. Codex TUI 안에서는 /mcp를 입력해 활성 서버와 현재 세션에 노출된 도구를 확인합니다.

방법 3: config.toml로 세부 설정하기

Codex는 기본적으로 ~/.codex/config.toml에 MCP 설정을 저장합니다. 신뢰된 프로젝트에서는 .codex/config.toml로 프로젝트 범위 설정도 사용할 수 있습니다. 여러 프로젝트에 공통으로 필요한 서버와 특정 저장소에만 필요한 서버를 구분하세요.

STDIO 서버 설정 예시

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

[mcp_servers.context7.env]
MODE = "read-only"

command는 필수이며 args, env, env_vars와 cwd는 필요에 따라 사용합니다. env_vars는 현재 환경에 있는 변수 이름을 전달하는 용도이므로 실제 값이 파일에 들어가지 않게 관리할 수 있습니다.

원격 HTTP 서버 설정 예시

[mcp_servers.team_docs]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "TEAM_MCP_TOKEN"
default_tools_approval_mode = "prompt"
enabled_tools = ["search", "read"]
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

bearer_token_env_var에는 토큰 자체가 아니라 토큰이 저장된 환경 변수 이름을 적습니다. 정적 http_headers에도 비밀값을 직접 넣기보다 환경 변수에서 읽는 env_http_headers를 우선 검토하세요.

도구 승인과 최소 권한 설정

MCP 서버 하나가 검색, 파일 생성, 이슈 수정, 배포처럼 여러 도구를 제공할 수 있습니다. Codex 공식 문서는 enabled_tools와 disabled_tools, 서버 기본 승인 모드와 도구별 승인 모드를 지원한다고 설명합니다.

[mcp_servers.devtools]
url = "http://127.0.0.1:3000/mcp"
enabled_tools = ["open", "inspect", "screenshot"]
disabled_tools = ["screenshot"]
default_tools_approval_mode = "prompt"

[mcp_servers.devtools.tools.open]
approval_mode = "approve"

disabled_tools는 허용 목록 뒤에 적용됩니다. 처음에는 조회·검색처럼 되돌리기 쉬운 기능만 열고, 이슈 작성, 파일 변경, 메시지 전송과 배포처럼 외부 상태를 바꾸는 기능은 매번 확인하도록 설정하세요.

도구 유형	초기 권장 정책	이유
문서 검색·읽기	허용 목록에 추가 후 결과 검토	변경 위험이 비교적 낮음
브라우저 열기·검사	테스트 주소만 허용	세션과 내부 페이지 노출 방지
이슈·PR 작성	실행 전 승인	외부 협업 상태를 변경
파일 쓰기·디자인 수정	대상 범위 제한과 승인	원본 훼손과 과도한 수정 방지
배포·삭제·결제	기본 비활성화	복구가 어렵거나 비용 발생

데스크톱 앱과 IDE에서 연결하기

ChatGPT 데스크톱 앱에서는 Settings의 MCP servers에서 Add server를 선택하고, 이름과 STDIO 또는 Streamable HTTP 방식, 명령 또는 URL을 입력한 뒤 저장하고 재시작합니다. OAuth가 필요하면 서버 목록에서 Authenticate를 선택하고, 작성 화면의 /mcp로 연결 상태를 확인합니다.

Codex IDE 확장도 설정 메뉴의 MCP servers에서 같은 방식으로 서버를 추가한 뒤 확장을 다시 시작합니다. CLI·데스크톱·IDE가 설정을 공유하더라도 각 화면에서 활성 서버와 도구 목록을 다시 확인하는 것이 안전합니다.

연결 후 첫 테스트 방법

1. /mcp에서 예상한 서버와 도구만 노출되는지 확인합니다.
2. “사용 가능한 도구 이름과 각 도구가 변경할 수 있는 외부 상태를 설명해줘”라고 요청합니다.
3. 공개 테스트 문서 한 건을 검색하거나 읽는 작업부터 수행합니다.
4. 도구 호출 전에 입력 인수와 대상 URL이 표시되는지 확인합니다.
5. 일부러 허용하지 않은 쓰기 작업을 요청해 승인 또는 차단이 작동하는지 확인합니다.
6. 로그와 응답에 인증 토큰, 개인정보와 내부 경로가 나타나지 않는지 검사합니다.
7. 테스트가 끝나면 불필요한 도구를 비활성화하고 설정을 기록합니다.

자주 발생하는 MCP 연결 오류 해결

증상	가능한 원인	확인 방법
서버가 목록에 없음	설정 파일 위치·TOML 문법 오류	codex mcp list와 현재 프로젝트 신뢰 상태 확인
시작 시간 초과	패키지 설치 지연·잘못된 command	명령을 터미널에서 별도로 실행하고 timeout 조정
도구가 보이지 않음	enabled_tools·disabled_tools 충돌	허용·차단 목록과 서버 도구 이름 대조
OAuth 로그인 실패	콜백 URL·클라이언트 ID 불일치	등록 때 표시된 정확한 callback URL 확인
401 또는 403	토큰 누락·권한 범위 부족	환경 변수 존재와 토큰 scope 확인
연결은 되지만 호출 실패	도구 시간 초과·서버 내부 오류	서버 로그 확인 후 tool_timeout_sec 검토
IDE에 반영되지 않음	확장 재시작 누락·다른 호스트	Restart extension 후 동일 설정 경로 확인

보안 체크리스트

• 출처와 유지보수자를 확인하지 않은 MCP 패키지를 실행하지 않습니다.
• 패키지 버전을 고정하고 업데이트 전 변경 내역을 검토합니다.
• API 키와 토큰을 config.toml, Git 또는 프롬프트에 직접 넣지 않습니다.
• 읽기·쓰기 도구를 구분하고 최소한의 enabled_tools만 지정합니다.
• 외부 상태를 변경하는 도구는 승인 모드를 사용합니다.
• 로컬 서버가 불필요하게 외부 인터페이스에 바인딩되지 않았는지 확인합니다.
• 원격 서버의 TLS, 인증, 데이터 보존과 감사 정책을 확인합니다.
• 프롬프트 인젝션이 도구 호출로 이어질 수 있다는 전제로 입력과 결과를 검토합니다.
• 사용하지 않는 서버는 enabled = false로 끄거나 제거합니다.

어떤 외부 개발 도구를 연결할 수 있나

공식 문서는 개발 문서 검색, Figma 디자인 접근, Playwright와 Chrome 개발자 도구를 통한 브라우저 제어, Sentry 로그 조회, GitHub 이슈·PR 관리 등을 유용한 예로 소개합니다. 다만 목록에 언급됐다는 사실이 해당 서버의 보안이나 품질을 보증한다는 뜻은 아닙니다. 각 서버의 공식 문서와 요청 권한을 별도로 확인하세요.

• 문서: 라이브러리·API의 최신 사용법 검색
• 브라우저: 화면 상태, 콘솔 오류와 네트워크 요청 검사
• 디자인: 컴포넌트 사양과 디자인 컨텍스트 조회
• 관측: 오류 이벤트와 로그를 코드 변경과 연결
• 협업: 이슈, 풀 리퀘스트와 작업 상태 확인

편집부 결론

Codex MCP 연결의 핵심은 많은 서버를 등록하는 것이 아니라 필요한 컨텍스트와 도구를 안전하게 좁혀 제공하는 데 있습니다. 개인 환경에서는 STDIO로 작은 읽기 작업부터 시작하고, 팀 공용 원격 서버는 OAuth와 감사 정책을 갖춘 뒤 도입하는 것이 좋습니다.

이 글은 OpenAI Docs를 분석한 설정 가이드이며 특정 MCP 서버를 실제 운영 환경에서 장기간 검증한 후기가 아닙니다. Codex와 서버 버전이 바뀌면 명령과 옵션도 달라질 수 있으므로 codex mcp --help, 서버 공식 문서와 연결 화면을 함께 확인하세요.

공식 문서와 함께 읽을 글

OpenAI Codex MCP 공식 문서 확인하기

Codex CLI 공식 사용법 확인하기

AI 개발 에이전트 Codex와 Claude Code 비교하기

AI 에이전트 구축 기본 구조 알아보기

GitHub 코딩 에이전트 협업 흐름 살펴보기

자주 묻는 질문

Codex MCP 서버는 무엇을 연결하는 기능인가요?

Codex가 외부 문서, 브라우저, 디자인, 이슈와 관측 도구의 컨텍스트를 읽거나 허용된 작업을 호출하도록 연결하는 기능입니다.

Codex MCP 설정 파일은 어디에 있나요?

기본 위치는 ~/.codex/config.toml입니다. 신뢰된 프로젝트에서는 프로젝트 내부의 .codex/config.toml로 범위를 제한할 수도 있습니다.

CLI와 IDE에서 MCP를 따로 설정해야 하나요?

같은 Codex 호스트의 ChatGPT 데스크톱 앱, Codex CLI와 IDE 확장은 MCP 설정을 공유합니다. 설정 후 앱이나 확장을 재시작하고 각 화면에서 활성 상태를 확인하세요.

STDIO와 HTTP MCP의 차이는 무엇인가요?

STDIO는 Codex가 로컬 명령으로 서버 프로세스를 시작하고, Streamable HTTP는 URL에 배포된 원격 서버로 접속합니다. 전자는 로컬 실행 권한, 후자는 인증과 네트워크 보안을 특히 확인해야 합니다.

OAuth가 필요한 MCP 서버는 어떻게 로그인하나요?

서버를 등록한 뒤 codex mcp login 서버이름을 실행합니다. 공급자에는 등록 과정에서 Codex가 표시한 콜백 URL을 정확히 입력해야 합니다.

API 토큰을 config.toml에 넣어도 되나요?

토큰 값을 직접 적는 방식은 피하세요. bearer_token_env_var나 env_vars에 환경 변수 이름을 지정하고 실제 값은 안전한 실행 환경에서 주입하는 편이 좋습니다.

MCP 서버가 연결됐는데 도구가 보이지 않는 이유는 무엇인가요?

서버 초기화 실패, 허용·차단 목록 충돌, 인증 실패가 흔한 원인입니다. codex mcp list, TUI의 /mcp, 서버 로그와 설정의 도구 이름을 차례로 확인하세요.

모든 MCP 도구를 자동 승인해도 되나요?

권장하지 않습니다. 읽기 도구부터 시작하고 이슈 작성, 파일 변경, 배포처럼 외부 상태를 바꾸는 도구는 매번 승인하거나 기본적으로 비활성화하세요.