# 문제 해결

> 잘못된 서버 URL, 실패한 로그인, 보이지 않는 도구부터 실패한 작업, 업로드, client_not_allowed 같은 오류 코드까지 Nodaro MCP의 흔한 문제를 해결하세요.

Source: https://nodaro.ai/ko/docs/mcp/troubleshooting

이 페이지에는 **Nodaro MCP 서버**에서 가장 흔히 겪는 문제와 해결 방법이 나와 있습니다. 연결과 로그인 오류, 나타나지 않는 도구, 실패하거나 멈춘 것처럼 보이는 작업, 업로드, 도구가 반환하는 오류 코드를 다룹니다. 지금 보이는 증상에 맞는 섹션부터 확인하세요.

## 연결과 로그인
### 커넥터를 추가할 때 클라이언트에 OAuth 오류 표시
1. URL이 끝에 슬래시 없이 정확히 `https://mcp.nodaro.ai/mcp`인지 확인하세요.
2. 내 네트워크에서 `mcp.nodaro.ai`의 주소가 정상적으로 조회되는지 확인하세요.
3. 디스커버리 문서를 확인하세요. 다음 명령은 JSON과 함께 `200`을 반환해야 합니다.

```bash
curl https://mcp.nodaro.ai/.well-known/oauth-protected-resource
```

같은 호스트는 `/.well-known/oauth-authorization-server`도 제공하며, 이 주소도 JSON과 함께 `200`을 반환해야 합니다.

### 로그인이 끝나지 않거나 URL이 잘못됨
서버는 `https://mcp.nodaro.ai/mcp`에서만 응답합니다. 흔한 실수 두 가지는 로그인이 Nodaro에 닿기도 전에 실패합니다.

- **`https://api.nodaro.ai/mcp`**: 이 도메인은 존재하지 않으므로, 연결이 이름을 조회하는 단계에서 실패합니다.
- **`https://app.nodaro.ai/mcp`**: 서버가 아니라 MCP 웹 페이지입니다. 이곳으로 `POST`하면 오류 코드 `wrong_mcp_host`와 함께 `405`가 반환되며, 이 오류에 올바른 URL이 나와 있습니다.

Claude에서는 커넥터의 URL을 편집할 수 없습니다. 문제가 있는 커넥터를 삭제하고 `https://mcp.nodaro.ai/mcp`로 다시 추가하세요.

### 동의 화면에 클라이언트 이름에 관한 주황색 경고 표시
정상입니다. 스스로 등록하는 클라이언트는 “Claude”처럼 자기 이름을 직접 정하며, Nodaro는 그 이름을 확인하지 않습니다. 이 경고는 **허용**을 클릭하기 전에, 액세스를 요청하는 앱이 지금 설정 중인 앱이 맞는지 확인하라고 알려 줍니다.

### 등록이 “Client not allowed” 오류로 실패
클라이언트가 허용된 클라이언트 목록에 없는 이름으로 등록했습니다. 다음 방법이 있습니다.

- Claude, ChatGPT, Cursor, Cline, Continue, Goose 같은 지원되는 클라이언트를 사용하세요.
- [app.nodaro.ai/settings/developer-apps](https://app.nodaro.ai/settings/developer-apps)에서 개발자 앱을 등록하고 그 클라이언트 ID와 시크릿을 사용하세요. [내 클라이언트](https://nodaro.ai/docs/mcp/connect/custom-client)를 참고하세요.
- 내 인스턴스라면 운영자에게 클라이언트 이름을 `MCP_DCR_ALLOWLIST`에 추가하거나 `MCP_DYNAMIC_REGISTRATION=open`을 설정해 달라고 요청하세요. [셀프 호스팅 설치의 MCP](https://nodaro.ai/docs/self-hosting/mcp)를 참고하세요.

### 어시스턴트가 얼마 후 작동을 멈춤
액세스는 90일 동안 유지되며, 갱신 토큰은 없습니다. 만료되면 호출이 `401`을 반환합니다. 클라이언트에서 다시 로그인하거나, 커넥터를 제거하고 다시 추가하세요.

### 시작하지 않은 실행에 “MCP 경유” 표시
연결된 MCP 클라이언트가 나를 대신해 시작한 실행입니다. [app.nodaro.ai/settings/connected-apps](https://app.nodaro.ai/settings/connected-apps)에서 **설정 › 연결된 앱**을 여세요. 내 계정에 액세스할 수 있는 모든 앱과 AI 어시스턴트가, 각각 연결된 날짜와 마지막으로 사용된 날짜와 함께 나열됩니다.

- 스스로 등록한 어시스턴트는 “AI 어시스턴트(MCP) — 이름은 어시스턴트가 정했습니다”로 표시됩니다. Nodaro는 그 이름을 확인하지 않았습니다.
- 예상하지 못한 앱을 제거하려면 **접근 취소**를 클릭하고 확인하세요. 그 앱의 액세스가 즉시 끝나고, 토큰도 더 이상 작동하지 않습니다.

## 보이지 않는 도구
### 클라이언트는 연결되었지만 도구가 없거나 일부만 표시됨
허용하지 않은 권한이 필요한 도구는 도구 목록에서 아예 빠집니다. 커넥터를 제거하고 다시 추가한 다음, 동의 화면에서 모든 권한을 허용하세요. 일부 도구에는 권한이 두 개 이상 필요합니다.

- **스튜디오 생성 도구**에는 `workflows:write`와 `workflows:execute`가 모두 필요합니다. 둘 중 하나만 있으면 이 도구가 하나도 나타나지 않습니다.
- **워크스페이스 도구**에는 `workspaces:read`와 `workspaces:write`가 필요한데, 워크스페이스가 생기기 전에 승인한 연결에는 이 권한이 없습니다. 다시 연결해 권한을 받으세요.

어떤 도구에 어떤 권한이 필요한지는 [권한](https://nodaro.ai/docs/mcp/tools#permissions)에 나와 있습니다.

### 문서에 있는 도구가 목록에 전혀 없음
일부 도구는 Nodaro Cloud에만 있습니다. 파이프라인, 스튜디오 프로덕션, Recast, 워크스페이스 도구와 `start_film_director`, `create_explainer`, `plan_edit`, `voice_changer_pro`, `pro_3d_render`, 크레딧 도구가 그렇습니다. 워크스페이스 도구는 조직이 켜져 있어야 하며, `pro_3d_render`는 렌더 엔진을 쓸 수 있을 때만 나타납니다. [Nodaro Cloud 전용 도구](https://nodaro.ai/docs/mcp/tools#tools-only-on-nodaro-cloud)를 참고하세요.

## 작업과 결과
### 생성 실패
작업 ID로 `get_job`이나 `diagnose_run`을 호출해 달라고 어시스턴트에게 요청하세요. 그리고 `retryable`과 `guidance`를 읽으세요. `retryable`이 `false`면 같은 요청은 그대로 다시 실패하므로, 설정이나 입력을 바꾸세요. `suggestedProvider`가 있으면 같은 프롬프트와 레퍼런스로 그 모델을 실행하세요. 자세한 내용은 [작업이 실패할 때](https://nodaro.ai/docs/mcp/tools/jobs#when-a-job-fails)에 있습니다. 실패한 작업에 예약된 크레딧은 환불됩니다. 단, 후처리 단계에서 실패한 경우는 예외입니다.

### 작업에 `pending_review` 표시
배포가 사람이 검토하도록 결과를 보류하고 있습니다. 작업은 실패한 것이 아니라 아직 진행 중입니다. 계속 확인하되, 다시 실행하지는 마세요. 중복 실행도 보류됩니다.

### `wait_for_job`이 `timeout` 반환
오류가 아닙니다. 대기가 끝났을 때(최대 120초 후) 작업이 아직 실행 중이었다는 뜻입니다. `wait_for_job`을 다시 호출하거나, 5~10초마다 `get_job`을 폴링하세요. 동영상은 보통 2~10분이 걸립니다.

### 결과 카드가 표시되지 않음
카드를 보려면 웹용 Claude처럼 MCP Apps를 표시하는 클라이언트가 필요합니다. 다른 클라이언트에서는 `get_job`으로 작업을 확인해 달라고 어시스턴트에게 요청하세요. 결과는 항상 내 라이브러리에 저장됩니다.

### 시간 초과 후 실행이 두 번 청구됨
`run_workflow`, `run_app`, `run_component`와 프로덕션 도구에 `client_request_id`를 보내고, 재시도할 때 같은 값을 다시 쓰세요. 그러면 Nodaro가 두 번째 실행을 시작해 청구하는 대신 첫 번째 실행을 반환합니다.

## 업로드
### 웹용 Claude에서 `prepare_image_upload` 실패
미리 서명된 업로드에는 Cursor, Cline, Claude Desktop, Claude Code처럼 셸에서 저장소 호스트에 접근할 수 있는 클라이언트가 필요합니다. 웹용 Claude와 Android의 Claude에서는 `upload_image_widget`을 사용하거나, 브라우저에서 열 링크를 주는 `request_image_upload`를 사용하세요. [업로드 도구](https://nodaro.ai/docs/mcp/tools/uploads)를 참고하세요.

## 워크플로
### `update_workflow_json`이 워크플로가 수정되었다고 응답
내가 워크플로를 읽은 뒤 누군가 워크플로를 변경했습니다. `get_workflow_json`으로 다시 읽은 다음, 새 버전으로 변경 내용을 다시 보내세요.

### 보낸 설정과 저장된 설정이 다름
모든 모델이 모든 화면 비율, 해상도, 품질을 받는 것은 아닙니다. Nodaro는 지원되지 않는 값을 지원되는 값으로 바꾸거나 제거하고, 각 변경을 `adjustments`에 나열합니다. 원래 값을 다시 보내지 말고, `list_models`로 그 값을 지원하는 모델을 고르세요.

### 영화 디렉터의 캔버스가 비어 있음
스킬은 단계를 승인한 뒤 그 단계의 노드를 한 번에 추가합니다. Claude가 노드를 추가했다고 말할 때까지 기다린 다음 새로고침하세요. 더 많은 해결 방법은 [영화 디렉터](https://nodaro.ai/docs/mcp/film-director#if-something-goes-wrong)에 있습니다.

## 오류 코드
| 코드 | 도구 | 의미 | 해결 방법 |
| --- | --- | --- | --- |
| `wrong_mcp_host` | 서버 | 클라이언트가 `app.nodaro.ai/mcp`의 웹 페이지를 호출했습니다 | `https://mcp.nodaro.ai/mcp`를 사용하세요 |
| `client_not_allowed` | 등록 | 클라이언트 이름이 허용되지 않습니다 | 지원되는 클라이언트나 개발자 앱을 사용하세요 |
| `too_many_open_registrations` | 등록 | `open` 모드에서 한 클라이언트의 사용하지 않은 등록이 너무 많습니다 | 기존 등록을 사용하거나 기다리세요 |
| `dcr_disabled` | 등록 | 인스턴스에서 자체 등록을 껐습니다 | 운영자에게 받은 클라이언트 ID와 시크릿을 사용하세요 |
| `voice_not_found` | 음성 도구 | 보이스 ID가 존재하지 않습니다 | 기본 제공 보이스 이름이나 내가 복제한 보이스를 사용하세요 |
| `advanced_mode_unsupported` | 프롬프트와 텍스트 도구 | Gemini나 Claude가 아닌 모델에서 `advanced_mode`를 사용했습니다 | Gemini나 Claude 모델을 고르거나 고급 모드를 끄세요 |
| `locked_field` | `run_app` | `inputOverrides`가 출력이 저장되는 위치를 바꾸려 했습니다 | 저장 위치는 앱이 정한 대로 두세요 |
| `portrait_required` | `generate_character` | 캐릭터에 승인된 인물 사진이 없습니다 | 먼저 `approve_portrait`로 인물 사진을 승인하세요 |
| `main_image_required` | 장소, 오브젝트, 크리처 도구 | 승인된 메인 이미지가 없습니다 | 먼저 메인 이미지를 승인하세요 |
| `candidate_object_mismatch`, `candidate_creature_mismatch` | 승인 도구 | 후보가 이 오브젝트나 크리처용으로 생성되지 않았습니다 | 해당 대상용으로 만든 후보를 승인하세요 |
| `scene_overlap` | `resolve_shot_sequence` | 두 장면의 리빌이 같은 시간대에 있습니다 | 각 장면의 큐를 다음 장면의 큐보다 앞에 두세요 |
| `not_available` | 스튜디오 프로덕션 도구 | 배포가 스튜디오 프로덕션을 제공하지 않습니다 | 다시 시도하지 마세요. 그 배포에서는 이 기능을 쓸 수 없습니다 |
| `studio_preview_unavailable` | `edit_studio_production` | 배포가 일괄 처리를 미리 볼 수 없습니다 | 아무것도 전송되지 않았습니다. 미리 보기 없이 일괄 처리를 적용할지 사용자와 함께 정하세요 |
| `not_finished` | `import_studio_production` | 플랜 작업이 아직 실행 중입니다 | 작업이 끝날 때까지 기다린 다음 가져오세요 |
| `cloud_only_feature` | `combine_videos` | 셀프 호스팅 설치에서 `smart_cut`을 사용했습니다 | `smart_cut` 없이 클립을 이으세요 |
| `payer_balance_jwt_only` | `check_balance`, `credit_transactions` | 연결된 클라이언트는 배포의 공유 결제 계정을 읽을 수 없습니다 | 앱에서 잔액을 확인하세요 |

## 자주 묻는 질문

### 클라이언트에 Nodaro가 연결됨으로 표시되는데 도구가 하나도 없는 이유는 무엇인가요?

동의 화면에서 허용한 권한에 도구가 포함되지 않기 때문입니다. 커넥터를 제거하고 다시 추가한 다음 모든 권한을 허용하세요.

### Nodaro MCP 서버에는 어떤 URL을 써야 하나요?

끝에 슬래시 없이 정확히 https://mcp.nodaro.ai/mcp를 쓰세요. api.nodaro.ai는 존재하지 않으며, app.nodaro.ai/mcp는 서버가 아니라 웹 페이지입니다.

### client_not_allowed는 무슨 뜻인가요?

클라이언트가 허용된 클라이언트 목록에 없는 이름으로 등록했다는 뜻입니다. 지원되는 클라이언트를 사용하거나, Nodaro 설정에서 개발자 앱을 등록하고 그 클라이언트 ID와 시크릿을 사용하세요.

### 몇 달 뒤 어시스턴트가 작동을 멈췄습니다. 왜 그런가요?

MCP 클라이언트의 액세스는 90일 동안 유지되며, 갱신 토큰은 없습니다. 클라이언트에서 다시 로그인하거나, 커넥터를 제거하고 다시 추가하세요.

### 내가 시작하지 않은 실행에 MCP 경유 표시가 보입니다. 어떻게 해야 하나요?

연결된 클라이언트가 나를 대신해 시작한 실행입니다. app.nodaro.ai/settings/connected-apps에서 설정 › 연결된 앱을 열고, 내 계정에 액세스할 수 있는 모든 앱과 어시스턴트를 검토한 다음 예상하지 못한 것은 취소하세요. 취소하면 그 액세스가 즉시 끝납니다.