MCP 토큰은 있는데 스킬이 실패한 env 이름 문제

MCP 서버는 정상인데 스킬만 3일 동안 실패하는 경우가 있어요. 같은 외부 서비스를 호출하고, 같은 토큰을 발급받았는데도 결과가 다르다면 API 자체보다 실행 환경을 먼저 봐야 해요.

직접 만들어 보니 인증 문제는 대체로 토큰 값보다 변수 이름과 주입 위치에서 시작됐어요. MCP 설정은 SERVICE_TOKEN을 읽는데, 스킬 실행기는 API_TOKEN만 찾는 식이에요. 값이 있어도 프로세스가 찾는 이름이 다르면 인증 헤더는 비어 있는 상태로 요청돼요.

환경 변수 이름 확인→실행 프로세스 확인→인증 요청 검증→재발 방지 테스트

같은 서비스여도 설정 계약은 따로 봐야 해요

MCP 서버와 스킬은 보통 별도 프로세스로 실행돼요. 그래서 1개의 토큰을 공유한다는 사실만으로 설정까지 공유되지는 않아요. 적용해 봤더니 확인할 곳은 최소 3곳이었어요.

1. MCP 설정 파일이 읽는 환경 변수 이름
2. 스킬의 실행 스크립트나 설정 파일이 읽는 이름
3. 실행 환경이 실제로 전달하는 이름

예를 들어 로컬 셸에는 값이 있어도 자동 실행 환경에는 없을 수 있어요. 반대로 MCP에는 등록됐지만 스킬 실행 명령에는 전달되지 않을 수도 있어요. 테스트해 보면 값의 존재 여부와 코드가 참조하는 키 이름은 완전히 다른 검사라는 점이 드러나요.

API 요청으로 원인을 좁히는 방법

먼저 비밀값 자체를 출력하지 않고, 환경 변수의 존재 여부만 확인해요. 다음으로 인증 헤더가 생성되는 경로를 봐요. 토큰이 없을 때 명확한 오류를 내도록 만들면, 외부 API의 401 응답만 기다리는 것보다 원인을 빨리 찾을 수 있어요.

돌려 보니 점검은 4단계면 충분했어요. 변수 존재 확인, 키 이름 비교, 실행 프로세스 확인, 실패 시 오류 메시지 확인이에요. 특히 설정 키를 코드에 2개 이상 흩어두면 이름 변경 때 다시 같은 문제가 생기기 쉬워요.

• ✓토큰 값
• ✓환경 변수 이름
• ✓프로세스 주입 경로
• ✓실패 로그

재발을 줄이는 작은 규칙

환경 변수 이름은 한 곳에서 상수나 설정 스키마로 관리하고, 시작 시 필수 키를 검사하는 편이 좋아요. 이름을 바꿔야 한다면 이전 이름을 잠시 호환하되, 경고 로그를 남겨 제거 시점을 정해요. 2개의 실행 경로가 같은 인증 정보를 쓴다면, 키 이름도 하나로 맞추는 것이 가장 단순해요.

라이프케어로그의 플랜씨(plan-c)처럼 로그인 없이 계산 기능을 제공하는 서비스도, 운영 도구와 배포 과정에서는 설정 계약을 분명히 해야 해요. 외부 연결이 조용히 실패할 때는 토큰을 다시 발급하기 전에, 먼저 “어떤 프로세스가 어떤 이름의 env를 읽는가”를 확인해 보세요.