MCP·CLI·API 연동 문제 해결하기

개발자 도구에서 오류가 발생하면 먼저 어떤 작업에서 어떤 응답을 받았는지 확인하세요. 로그인, 대상 사이트, 작업 권한, 플랜, 발행 상태는 각각 별도로 확인해야 합니다.

세션이 만료되었거나 401 오류가 나요

401 UNAUTHORIZED는 관리 API가 인증 토큰을 받아들이지 못했다는 뜻입니다. CLI에서는 다시 로그인한 뒤 사이트 조회를 확인합니다.

neopress login
neopress whoami
neopress --site 123 sites get

123은 실제 사이트 ID로 바꾸세요. NEOPRESS_ACCESS_TOKEN이 설정되어 있으면 저장된 CLI 세션보다 해당 토큰을 먼저 사용합니다. 새 로그인으로 해결하려면 실행 환경의 토큰을 갱신하거나 이 설정을 해제해야 합니다. whoami는 저장된 CLI 세션을 확인하므로 외부에서 전달한 토큰까지 검증하는 명령은 아닙니다.

원격 MCP에서는 AI 도구의 연결 인증을 다시 시작하고 로그인하는 계정이 맞는지 확인하세요. 사용자 정의 OAuth 스코프를 추가하거나 다른 종류의 키를 붙여넣는 방법으로 만료된 세션을 해결할 수는 없습니다.

다른 사이트가 선택돼요

neopress --site 123 sites current
neopress --site 123 sites get

첫 명령은 적용될 대상 사이트를 보여주고, 두 번째 명령은 서버에서 실제 접근 가능 여부를 확인합니다. 사이트를 명시하지 않으면 환경 변수, 프로젝트 설정, 저장된 전역 사이트 때문에 다른 사이트가 선택될 수 있습니다. MCP에서는 사이트 목록을 조회하고 올바른 숫자 ID를 선택한 뒤 다시 읽도록 요청하세요. 페이지나 콘텐츠 ID도 같은 사이트에 속해야 합니다.

403 오류가 나요

FORBIDDEN: 사이트 참여 상태와 해당 작업의 역할 조건을 확인하세요. 개발자 도구를 통한 사이트 발행에는 소유자 또는 관리자 역할이 필요합니다.
INSUFFICIENT_SCOPE: 팀 설정에서 계정의 작업 권한을 확인하세요. 콘텐츠 수정 권한이 있다고 페이지 수정이나 발행까지 자동으로 허용되지는 않습니다.
PLAN_REQUIRED: 대상 사이트의 현재 이용 권한을 확인하세요. 개발자 도구는 Launch부터, 추가 언어와 저장된 이벤트·퍼널 기능은 Growth부터 사용할 수 있습니다.

접근 가능한 모든 사이트에 활성 개발자 이용 권한이 없다면 API를 통한 사이트 목록 조회나 생성도 제한될 수 있습니다. 같은 계정을 다시 연결해도 플랜이나 권한은 바뀌지 않습니다.

파일 업로드나 컴파일이 실패해요

원격 MCP는 ./photo.png 같은 내 컴퓨터의 경로를 읽을 수 없습니다. 공개된 파일 URL을 가져오거나 임시 업로드 주소를 사용하도록 AI에게 요청하세요. 로컬 stdio MCP에서는 로컬 파일을 업로드할 수 있습니다. 외부 에셋 URL을 등록만 하는 작업은 파일을 Neopress 저장소로 복사하지 않습니다.

422 COMPILE_ERROR가 발생하면 오류 메시지와 현재 런타임 규칙을 함께 확인하세요. import한 모듈, 컴포넌트 문법, 컬렉션 조회 label, 관리형 폼 연결을 살펴봅니다. 수정한 페이지를 다시 컴파일한 뒤 발행하세요.

작업 중이거나 요청이 제한·중단돼요

409 ONBOARDING_GENERATION_IN_PROGRESS는 사이트의 초기 생성이 진행 중이라는 뜻입니다. 생성이 끝난 뒤 수정하세요. 429 RATE_LIMITED 응답을 받았다면 동시 요청 수를 줄이고 재시도 간격을 늘립니다. 제한은 작업마다 다르며 관련 요청끼리 한도를 공유할 수 있습니다.

수정 요청 중 시간 초과나 연결 오류가 발생했다면 같은 요청을 반복하기 전에 리소스를 조회하세요. 도구가 응답을 받지 못했어도 서버에서는 처리가 끝났을 수 있습니다.

공개 페이지에 변경이 보이지 않아요

초안을 저장하거나 컴파일하는 데 그치지 않고 프로덕션에 발행했는지 확인하세요. neopress --site 123 publish preview로 대기 중인 변경을 확인합니다. 수정한 CMS 콘텐츠는 별도로 발행하고, 변경한 레이아웃과 전역 스타일은 사이트 발행에 포함하며, 페이지의 공개 언어도 확인하세요. 그다음 실제 방문자 주소를 엽니다.

문제가 계속되면 실행한 명령이나 도구 이름, 사이트 ID, 발생 시각, 오류 코드를 지원팀에 전달하세요. 액세스 토큰과 비공개 내용은 제외합니다.