MCP 연결 진단과 복구

Codex 학습 목차로 돌아가기

목표와 준비

이 단락의 학습 자료: 입문

1단계: 시간 제한보다 설정 먼저 확인

codex --version
codex mcp get codexLearningDocs
codex mcp list

이름·활성 상태·방식·URL과 로컬/원격, CLI/데스크톱, 마지막 재시작을 기록합니다. get에서 이름을 찾지 못하면 실제 파일, 철자, 사용자/프로젝트 계층, 사용자 지정 CODEX_HOME을 확인하세요. 같은 호스트에서만 설정을 공유하며 Windows와 WSL 홈도 같은 위치가 아닙니다.

구문 오류는 표시된 줄의 따옴표·중복 표·값 형식을 먼저 수정한 뒤 네트워크를 봅니다. 설정에 따라 사본을 보존하고 연습 구간만 편집하며 전체 설정은 공개하지 않습니다. 이름이 없으면 신뢰 프로젝트 로드, 현재 폴더, 백업이 아닌 실제 파일 저장을 확인하세요.

인증 없는 공개 서비스는 불필요로 적으며 로그인을 빠뜨린 것이 아닙니다.

2단계: 비활성 상태 재현

이전 글의 읽기 요청으로 정상 결과를 얻고 설정을 보존합니다. enabled가 이미 있으면 false로 수정하고, 없을 때만 enabled = false를 한 번 추가해 키나 표를 중복하지 마세요. 데스크톱 Restart, IDE 확장 재시작, CLI 새 세션을 사용합니다. 이전 대화에서 재질문하면 과거 내용을 쓸 수 있습니다. 의도적 로컬 비활성화이며 공식 서비스 장애가 아닙니다.

[mcp_servers.codexLearningDocs]
url = "https://developers.openai.com/mcp"
enabled = false

/mcp

/mcp는 데스크톱·CLI·IDE의 Codex 입력창에서 사용하며 셸 명령이 아닙니다. 재시작 후 새 작업 또는 세션에서 /mcp, MCP servers 설정, 실제 도구 활동으로 비활성화를 확인하세요. 클라이언트가 도구를 제공하지 않았다고 기록하고, 화면을 비교한다면 각각의 호스트와 설정 위치를 적으세요.

새 세션에는 비활성 서버 도구가 없어야 하며 get에 설정이 남는 것은 정상입니다. true로 바꾸거나 추가한 false를 제거하고 재시작·재조회·원문 확인을 하세요. 정상·비활성·복원 세 상태를 모두 남겨야 하며 마지막 성공 화면만으로 오류 실습이 됐다고 할 수 없습니다.

3단계: STDIO 시작과 HTTP 연결 구분

다른 STDIO 서버는 command·args·cwd부터 봅니다. Windows Get-Command와 macOS/Linux command -v는 현재 터미널의 경로 확인이며 데스크톱 프로세스 PATH 일치를 보장하지 않습니다. 상대 경로·파일 없음·필요한 Node 버전을 먼저 확인하고 파일명 오타 때문에 시작 제한을 늘리지 마세요.

Get-Command node
node --version

command -v node
node --version

STDIO는 표준 입출력을 프로토콜 통로로 쓰므로 환영 문구나 디버그 출력이 방해할 수 있습니다. 관리자는 공식 구현에 따라 일반 로그를 stderr로 보내고 사용자는 외부 패키지 내부를 임의 수정하지 말고 증거를 보고하세요. 조용한 입력 대기는 멈춤이 아닐 수 있고 프로세스 생존도 초기화 성공을 증명하지 않습니다.

HTTP는 스킴·호스트·전체 경로를 확인하며 이번에는 공식 /mcp입니다. 첫 페이지가 열려도 MCP 요청·프록시·인증 성공을 증명하지 않습니다. TLS는 시간·조직 프록시·인증서 신뢰를 관리자와 확인하고 검증 해제를 기본 해결로 쓰지 않습니다. 일시 실패는 시각과 가린 오류를 남긴 후 재시도하세요.

4단계: 인증·도구 필터·시간 제한

OAuth 서비스는 Authenticate 또는 login help를 확인한 뒤 대상 이름으로 인증합니다. 계정·범위·콜백은 제공자 요건을 따르세요. 사전 client ID 등록이 필요하면 Codex가 표시한 전체 URL을 쓰고 포트를 추측하거나 localhost와 127.0.0.1을 바꾸지 않습니다. 공개 Docs MCP에는 필요 없는 절차입니다.

인증 후 도구가 없으면 enabled_tools·disabled_tools·플러그인 정책을 확인합니다. 허용 목록은 서버에 없는 기능을 만들지 않으며 거부 목록이 나중에 적용됩니다. search나 read를 추측하지 말고 실제 도구 이름을 확인하세요. 플러그인 서버의 실행 명령은 사용자 설정으로 대체하지 않습니다. Plugins 문제 해결을 참고하세요.

startup_timeout_sec는 초기화, tool_timeout_sec는 한 호출입니다. 프로그램·URL·인증을 확인하고 작은 읽기로 요청이 큰지 구분한 뒤 정상 작업에 더 필요할 때 해당 서버 값만 바꿔 재시험하세요. grace와 required도 시작에 영향을 주지만 모두 필수로 만들 필요는 없습니다. 필수 서비스가 없으면 오류를 보존하고 의존 작업을 멈춥니다.

마무리: 인계 가능한 오류 기록

# MCP recovery record
Surface / OS / client version:
Host and effective config location (redacted):
Server name / transport:
Failure layer:
Original error (without secrets):
Single change:
New-session tool visibility:
Read-only request and verified source:
Normal / disabled / restored results:
Unrelated settings preserved:
Remaining limitation and next action:

설정을 망가뜨리면 연습 구간을 복구해 확인하고 다른 작업 중 전체 파일을 되돌리지 않습니다. 끝나면 이전 글처럼 추가 항목만 제거하세요. OAuth logout은 저장 인증, remove는 설정을 지우며 남은 외부 승인은 제공자 계정에서 확인합니다. 이미 외부에 쓴 데이터는 둘 다 되돌리지 못하므로 서비스 복구 절차를 사용합니다.

실패 계층 설명·비활성화와 복원 재현·새 읽기 도구 증거가 완료 기준입니다. 프로세스·파일·정답만으로는 부족하며 미연결이면 도구 미검증으로 남깁니다. 공식 문서와 로컬 설정·직접 프로토콜 시험을 구분하고 다른 OS·IDE·OAuth·휴대폰 실측으로 보지 않습니다. 다음은 Worktree 분리입니다.

Codex 학습 목차로 돌아가기

자세한 설명 보기

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI 도구
• 튜토리얼
• Codex