> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 문제 해결

> Octoparse MCP 서버의 일반적인 설정, 인증, 작업 실행 및 내보내기 문제를 진단하고 해결하세요.

Octoparse MCP 서버를 설정하거나 사용할 때 발생하는 일반적인 문제를 진단하려면 이 페이지를 참고하세요.

## 인증 문제

### API 키가 없거나 유효하지 않음

MCP 서버가 유효한 Octoparse API 키를 찾지 못하면 인증 오류가 표시될 수 있습니다.

일반적인 증상:

```text theme={null}
Unauthorized
Invalid API key
Authentication failed
401 Unauthorized
Missing API key
```

API 키가 유효하며 삭제되거나 재발급되지 않았는지 확인하세요.

환경 변수를 사용한다면 MCP 서버를 시작하는 동일한 셸 또는 런타임에서 사용할 수 있는지 확인하세요.

```bash theme={null}
echo $OCTOPARSE_API_KEY
```

출력이 비어 있으면 서버를 시작하기 전에 API 키를 다시 설정하세요.

```bash theme={null}
export OCTOPARSE_API_KEY="your-api-key"
```

<Warning>
  API 키를 Git, 스크립트, 스크린샷, 공유 로그 또는 공개 이슈 보고서에 커밋하지 마세요.
</Warning>

### 한 터미널에서는 API 키가 작동하지만 MCP 클라이언트에서는 작동하지 않음

일부 MCP 클라이언트는 대화형 터미널의 환경 변수를 상속하지 않습니다.

MCP 서버를 수동으로 시작하면 작동하지만 MCP 클라이언트에서는 실패한다면 클라이언트 구성을 확인하고 API 키가 서버 프로세스에 전달되는지 확인하세요.

환경 변수를 업데이트한 뒤 MCP 클라이언트를 다시 시작하세요.

## 서버 시작 문제

### MCP 서버가 시작되지 않음

MCP 서버 시작에 실패하면 명령어, 작업 디렉터리, Node.js 버전 및 환경 변수를 확인하세요.

먼저 터미널에서 서버 명령어를 직접 실행하세요. 이를 통해 MCP 클라이언트 구성 문제와 서버 런타임 문제를 구분할 수 있습니다.

```bash theme={null}
node --version
npm --version
```

MCP 클라이언트가 사용하는 명령어가 터미널에서 작동하는 명령어와 일치하는지 확인하세요.

### 명령어를 찾을 수 없음

MCP 클라이언트에서 서버 명령어를 찾을 수 없다고 보고하면 절대 경로를 사용하거나 패키지가 설치되어 있는지 확인하세요.

클라이언트가 동일한 `PATH`를 사용하지 않으면 셸에서 작동하는 명령어가 MCP 클라이언트에서 실패할 수 있습니다.

## 작업 접근 문제

### 작업을 찾을 수 없음

작업 ID가 잘못되었거나 인증된 계정에 작업 접근 권한이 없으면 작업을 찾을 수 없다는 오류가 표시될 수 있습니다.

다음을 확인하세요.

* 작업 ID를 정확히 복사했습니다.
* 작업이 인증된 Octoparse 계정에 속합니다.
* 작업이 삭제되지 않았습니다.
* API 키가 올바른 워크스페이스 또는 계정에 속합니다.

### 접근 가능한 작업이 반환되지 않음

작업 검색 결과가 없으면 먼저 API 키와 계정 접근 권한을 확인하세요. 그런 다음 검색 범위를 넓히거나 키워드 필터 없이 작업 목록을 조회하세요.

## 작업 실행 문제

### 작업 시작 실패

작업 정의가 지원되지 않거나 작업이 이미 실행 중이거나 계정에 실행 권한이 없으면 작업 시작에 실패할 수 있습니다.

먼저 Octoparse에서 작업을 확인한 뒤 MCP 클라이언트에서 재시도하세요.

이전 워크플로로 작업을 만들었다면 자동화로 실행하기 전에 최신 Octoparse 앱에서 작업을 다시 만들거나 업데이트하세요.

### 실행은 시작되지만 데이터가 반환되지 않음

실행은 성공했지만 내보내기에서 데이터가 반환되지 않으면 작업이 완료되었는지, 선택한 실행 또는 로트에 데이터가 있는지 확인하세요.

일반적인 원인:

* 작업이 아직 실행 중입니다.
* 선택한 로트 ID에 데이터가 없습니다.
* 작업은 완료되었지만 일치하는 레코드가 없습니다.
* 실행이 끝나기 전에 내보내기를 요청했습니다.

## 내보내기 문제

### 내보내기 실패

내보내기에 실패하면 작업이 완료되었는지, 사용 중인 도구가 내보내기 형식을 지원하는지 확인하세요.

내보내기 명령어나 도구가 로트 ID를 받는다면 해당 ID가 같은 작업과 실행 기록에 속하는지 확인하세요.

### 내보낸 파일이 비어 있음

내보낸 파일이 비어 있다면 일반적으로 선택한 실행에 추출된 레코드가 없거나 추출이 끝나기 전에 내보내기를 요청한 것입니다.

먼저 작업 기록을 확인한 뒤 올바른 실행 또는 로트를 사용해 다시 내보내세요.

## 요청 한도 및 일시적 실패

요청이 간헐적으로 실패하면 잠시 기다린 뒤 재시도하세요. 네트워크 문제, 작업 대기열 지연 또는 일시적인 백엔드 오류가 원인일 수 있습니다.

실패가 반복되면 다음 정보를 수집하세요.

* MCP 클라이언트 이름 및 버전
* MCP 서버 버전
* 정확한 도구 호출 또는 프롬프트
* 작업 ID
* 오류 메시지
* 동일한 작업이 Octoparse에서 직접 작동하는지 여부

<Warning>
  로그를 공유하기 전에 API 키, 액세스 토큰, 쿠키 및 개인 데이터를 삭제하세요.
</Warning>

## 문제를 보고할 때 제공할 정보

다음 정보를 포함하세요.

* MCP 클라이언트 이름
* MCP 서버 버전
* 운영 체제
* Node.js 버전
* 실패한 도구 이름
* 정확한 오류 메시지
* 작업 ID 또는 민감 정보를 제거한 예시
* MCP 외부의 Octoparse에서 작업이 작동하는지 여부