# MCP 도구 레퍼런스

> Nodaro MCP 서버가 제공하는 모든 도구를 용도별로 묶어, 각 도구에 필요한 권한, 작업이 결과를 알리는 방식, 도구 항목을 읽는 법을 설명합니다.

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

**Nodaro MCP 도구**는 AI 어시스턴트가 [Nodaro MCP 서버](https://nodaro.ai/docs/mcp)에 연결된 뒤 내 Nodaro 계정에서 할 수 있는 동작입니다. 도구는 약 200개이며, 여기서는 용도별로 묶었습니다. 미디어 생성과 편집, 에셋 관리, 워크플로 구성과 실행, 완성된 프로덕션 연출입니다. 각 페이지에는 정확한 도구 이름, 각 도구에 필요한 권한, 주요 매개변수, 반환값, 비용이 나와 있습니다.

## 도구 그룹
| 그룹 | 도구가 하는 일 |
| --- | --- |
| [작업](https://nodaro.ai/docs/mcp/tools/jobs) | 작업과 실행을 확인하고, 기다리고, 나열하고, 평가하고, 진단 |
| [업로드](https://nodaro.ai/docs/mcp/tools/uploads) | 내 이미지, 오디오, 동영상을 Nodaro로 가져오기 |
| [갤러리와 에셋](https://nodaro.ai/docs/mcp/tools/gallery-and-assets) | 갤러리와 업로드 찾아보기, 결과를 채팅에 표시, 즐겨찾기 표시 |
| [모델, 크레딧, 프리셋](https://nodaro.ai/docs/mcp/tools/models-and-credits) | 기능과 가격을 포함한 모델 목록, 잔액 확인, 노드 프리셋 저장과 적용 |
| [워크스페이스](https://nodaro.ai/docs/mcp/tools/workspaces) | 세션이 작업할 조직 워크스페이스 선택 |
| [프로젝트와 워크플로](https://nodaro.ai/docs/mcp/tools/projects-and-workflows) | 워크플로 만들기, 편집, 가져오기, 내보내기, 실행, 노드 구성 방식 알아보기, 생성 세션 정리 |
| [앱과 컴포넌트](https://nodaro.ai/docs/mcp/tools/apps-and-components) | 게시된 앱과 저장된 컴포넌트 실행 |
| [파이프라인](https://nodaro.ai/docs/mcp/tools/pipelines) | **스토리 → 동영상** 파이프라인을 시작, 조정, 승인 |
| [프롬프트와 텍스트](https://nodaro.ai/docs/mcp/tools/prompts-and-text) | 더 나은 프롬프트와 스크립트 작성, 여러 결과 중 가장 좋은 것 고르기 |
| [이미지](https://nodaro.ai/docs/mcp/tools/image) | 이미지 생성, 변환, 편집, 합성, 설명, 팔레트와 무드보드 저장 |
| [동영상](https://nodaro.ai/docs/mcp/tools/video) | 동영상 생성, 연장, 스타일 변경, 업스케일, 인물이 말하고 움직이게 하기 |
| [동영상 편집](https://nodaro.ai/docs/mcp/tools/video-editing) | 동영상 자르기, 이어 붙이기, 반복, 자막, 오버레이, 조립 |
| [분석과 편집 목록](https://nodaro.ai/docs/mcp/tools/analysis-and-edl) | 동영상을 장면별로 분석, 무음 감지, 녹화본 동기화, 편집 결정 목록 렌더링 |
| [오디오](https://nodaro.ai/docs/mcp/tools/audio) | 음성, 대화, 보이스, 더빙, 효과음, 녹취록, 정리 |
| [음악](https://nodaro.ai/docs/mcp/tools/music) | Suno와 다른 음악 모델로 만드는 노래와 연주곡 |
| [캐릭터](https://nodaro.ai/docs/mcp/tools/characters) | 캐릭터 만들기, 포트레이트와 변형 생성, 애니메이션, 캐릭터 모델 학습 |
| [장소](https://nodaro.ai/docs/mcp/tools/locations) | 장소 만들기, 설정 샷과 분위기 클립 생성 |
| [오브젝트와 크리처](https://nodaro.ai/docs/mcp/tools/objects-and-creatures) | 외모가 고정된 소품, 제품, 동물, 크리처 |
| [샷 시퀀스와 동영상 디렉터](https://nodaro.ai/docs/mcp/tools/shot-sequence-and-video-director) | 보이스오버에 타이밍을 맞춘 내레이션 모션 그래픽 동영상 |
| [스튜디오 프로덕션](https://nodaro.ai/docs/mcp/tools/studio-productions) | 스튜디오 편집기에서 계속 편집할 수 있는 영화 |
| [Recast](https://nodaro.ai/docs/mcp/tools/recast) | JSON 스크립트 하나로 쓰고 Recast 프로젝트로 렌더링하는 영화 |
| [3D 장면](https://nodaro.ai/docs/mcp/tools/3d-scenes) | 동영상으로 렌더링하는 편집 가능한 3D 장면 |
| [유틸리티, 레시피, 스킬](https://nodaro.ai/docs/mcp/tools/utility) | 연결 테스트, 레시피와 스킬 불러오기, 웹 페이지 캡처, UGC 동영상 만들기 |

## 권한
각 도구에는 OAuth 권한(범위)이 하나 이상 필요하며, 연결할 때 동의 화면에서 허용합니다. 권한이 허용되지 않은 도구는 도구 목록에서 완전히 빠집니다. 어시스턴트는 그 도구를 볼 수 없으므로, 호출했다가 실패하는 일도 없습니다.

| 범위 | 도구 |
| --- | --- |
| `workflows:read` | `list_projects`, `get_project`, `list_workflows`, `get_workflow`, `get_workflow_json`, `export_workflow`, `list_components`, `get_component_inputs`, `get_recast_status`, `validate_studio_plan`, `list_studio_productions`, `get_studio_production`, `plan_studio_export` |
| `workflows:write` | `create_workflow`, `delete_workflow`, `update_workflow_json`, `import_workflow`, `import_recast_script`, `create_studio_production`, `import_studio_production`, `edit_studio_production`, `share_studio_production`, `clone_studio_production` |
| `workflows:execute` | `run_workflow`, `render_final`, `run_app`, `run_component`, `delete_app_run`, `mix_audio`, `capture_site`, 이미지, 동영상, 오디오, 음악, 에셋, 3D 장면의 모든 생성, 편집, 분석 도구, 프롬프트 도구, `reduce`, 샷 시퀀스 도구, `create_explainer`, `create_launch_video`, `start_recast`, `resolve_recast_gate`, `tighten_episode`, `continue_use_case` |
| `workflows:write`와 `workflows:execute` 둘 다 | `describe_studio_production`, `generate_studio_still`, `generate_studio_keyframe`, `generate_studio_clip`, `new_studio_shot_from_frame`, `voice_studio_shot`, `revoice_studio_clip`, `score_studio_production` |
| `workflows:execute`와 `assets:write` 둘 다 | `train_character` |
| `jobs:read` | `list_jobs`, `get_job`, `wait_for_job`, `diagnose_run`, `list_sessions`, `read_session` |
| `assets:read` | `browse_gallery`, `browse_uploads`, `list_favorites`, `get_asset`, `display_asset`, `get_app_run`, `list_characters`, `get_character`, `list_locations`, `get_location`, `list_objects`, `get_object`, `list_creatures`, `get_creature`, `list_palettes`, `list_moodboards` |
| `assets:write` | `favorite_asset`, `create_character`, `update_character`, `approve_portrait`, `recaption_character`, `create_location`, `update_location`, `approve_main_image`, `recaption_location`, `approve_object_main_image`, `recaption_object`, `approve_creature_main_image`, `recaption_creature`, `rate_job`, `create_session`, `update_session`, `save_palette`, `save_moodboard`, `save_node_preset`, `delete_node_preset`, `favorite_node_preset`, 그리고 업로드 도구 9개 |
| `credits:read` | `check_balance`, `credit_transactions` |
| `apps:read` | `list_apps`, `get_app_inputs` |
| `presets:read` | `list_node_presets`, `get_node_preset` |
| `pipelines:read` | `get_pipeline_stage_chat`, `get_pipeline_status`, `pipeline_pending_approvals` |
| `pipelines:execute` | `branch_pipeline`, `start_pipeline` |
| `pipelines:approve` | `chat_pipeline_stage`, `apply_chat_proposal` |
| `workspaces:read` | `list_workspaces` |
| `workspaces:write` | `select_workspace` |

다음 도구는 권한이 필요 없으며, 해당 도구가 있는 에디션에서 항상 표시됩니다. `ping`, `list_models`, `start_film_director`, `start_video_director`, `start_workflow_editor`, `get_node_skill`, `get_picker_catalog`, `list_shot_shapes`, `get_shot_shape`, `list_brand_presets`, `get_recipe`, `get_studio_production_skill`, `get_recast_authoring_skill`, `validate_recast_script`, `build_ugc_creator`, `build_ugc_clips`, `build_ugc_cards`, `ugc_split_speech`, `ugc_finish_clips`입니다.

권한 두 개가 필요한 도구는 둘 다 허용된 경우에만 나타납니다. 둘 중 하나만 허용한 연결에서는 그 도구가 하나도 보이지 않습니다.

## 작업이 결과를 알리는 방식
대부분의 생성 도구는 **작업**을 시작하고, `image collage started (id 7f3c…).` 같은 한 줄로 바로 응답합니다. 작업은 Nodaro에서 실행되며, 결과는 항상 내 라이브러리에도 저장됩니다.

- **MCP Apps를 표시하는 클라이언트**(예: 웹용 Claude)에서는 도구가 카드를 보여 줍니다. 카드에는 실시간 진행 상황이 표시되고, 그다음 완성된 결과가 나타납니다. 이미지, 동영상, 오디오 도구에는 각자의 카드가 있습니다. 나머지 작업 도구는 출력을 감지하는 카드 하나를 함께 씁니다. 이 카드는 동영상, 이미지, 오디오 플레이어를 보여 주거나, 스크립트, 가사, 녹취록, 정렬 데이터를 **Copy**(복사) 버튼이 있는 텍스트로 보여 주거나, 컴포넌트의 출력을 위아래로 쌓아 보여 줍니다.
- **다른 클라이언트**에서는 어시스턴트가 5~10초마다 [`get_job`](https://nodaro.ai/docs/mcp/tools/jobs#get_job)으로 작업을 확인하거나, [`wait_for_job`](https://nodaro.ai/docs/mcp/tools/jobs#wait_for_job)으로 호출마다 최대 45초 동안 기다립니다. 이미지는 보통 1분 안에 끝납니다. 동영상은 보통 2~10분 걸립니다.
- **워크플로 실행과 앱 실행**은 작업 ID 대신 실행 ID를 반환합니다. [`get_app_run`](https://nodaro.ai/docs/mcp/tools/gallery-and-assets#get_app_run)으로 확인하세요.

MCP `tasks` API를 지원하는 클라이언트는 그 API로도 진행 상황을 받습니다. 결과를 검토하는 배포에서 작업이 사람의 검토를 기다리면, 태스크에 `input_required` 상태가 표시됩니다. 그 결정은 검토자의 몫이므로, 작업을 다시 실행하지 마세요.

## mcp 프로젝트
워크플로 도구는 **mcp**라는 프로젝트 하나 안에서 작동합니다. 어시스턴트가 처음 필요로 할 때 Nodaro가 이 프로젝트를 만들며, 대시보드의 **MCP 워크플로** 아래에 그 워크플로가 나열됩니다. 이 탭에서 다른 워크플로처럼 열거나, 옮기거나, 삭제할 수 있습니다.

| 도구 | 접근할 수 있는 범위 |
| --- | --- |
| `list_projects`, `get_project` | 내 모든 프로젝트, 읽기 전용 |
| `list_workflows`, `get_workflow`, `get_workflow_json` | mcp 프로젝트의 워크플로 |
| `create_workflow`, `delete_workflow`, `update_workflow_json`, `import_workflow` | mcp 프로젝트의 워크플로 |
| `export_workflow` | 내 모든 워크플로 |
| `run_workflow`, `render_final` | mcp 프로젝트의 워크플로 |

다른 프로젝트의 워크플로를 어시스턴트가 다루게 하려면 `export_workflow`로 내보내고, 그 번들을 `import_workflow`로 가져오세요. 사본은 mcp 프로젝트에 들어가며, 원본은 그대로 유지됩니다.

## 도구 항목 읽는 법
이 페이지들의 모든 도구는 같은 구성을 따릅니다.

- **제목**은 정확한 도구 이름입니다. 예: `generate_image`. 어시스턴트는 이 이름으로 도구를 호출합니다.
- **첫 몇 줄**에는 도구가 하는 일, 필요한 권한, 비용, Nodaro Cloud 전용인지가 나옵니다.
- **매개변수 표**에는 주요 매개변수와 타입이 나옵니다. 필수 매개변수에는 **필수**가 표시됩니다. 기본값과 제한은 설명에 있습니다.
- **반환값**은 돌아오는 것을 알려 줍니다. 대부분 작업 ID이며, 플랜이나 목록 같은 결과일 때도 있습니다.

어시스턴트가 연결할 때 읽는 도구 자체의 설명이 매개변수와 제한의 최종 기준입니다. 도구 설명의 가격은 실행에 청구되는 금액과 다를 수 있습니다. [`list_models`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_models)는 모델의 현재 가격을 반환합니다. 노드의 **실행** 버튼에 그 실행의 가격이 표시됩니다.

## 여러 도구에 공통된 규칙
- **URL 또는 id로 미디어 전달.** 미디어를 받는 도구는 `image_url` 같은 공개 `https` URL이나 `image_asset_id` 같은 Nodaro id를 받습니다. id는 미디어를 만든 작업이나 업로드일 수 있습니다.
- **id로 모델 지정.** `model` 매개변수는 [`list_models`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_models)의 모델 id를 받습니다. `list_models`는 각 모델의 화면 비율, 해상도, 길이, 가격도 반환합니다.
- **프리셋.** `generate_image`, `generate_video`, `generate_music`, `generate_speech`, `text_to_audio`는 [`list_node_presets`](https://nodaro.ai/docs/mcp/tools/models-and-credits#list_node_presets)의 `presetId`를 받습니다. 직접 전달한 필드가 프리셋보다 우선합니다.
- **재시도 토큰.** `run_workflow`, `run_app`, `run_component`와 여러 프로덕션 도구는 `client_request_id`를 받습니다. 영문자, 숫자, `_ - . :`로 이루어진 8~128자입니다. 타임아웃 후 재시도할 때 같은 값을 다시 쓰면, Nodaro가 작업을 두 번 시작하거나 두 번 청구하지 않습니다.
- **크레딧을 쓰기 전 견적.** 일부 도구는 작업을 시작하지 않고 가격을 낼 수 있습니다. 예를 들어 `dry_run: true`를 쓴 스튜디오 도구와 `confirm` 없이 호출한 `start_recast`입니다.

## Nodaro Cloud 전용 도구
다음 도구는 Nodaro Cloud에만 있습니다. `check_balance`, `credit_transactions`, `train_character`, `plan_edit`, `switch_cameras`, `voice_changer_pro`, `voice_changer_pro_analyze`, `voice_changer_pro_export`, `create_explainer`, `create_launch_video`, `start_film_director`, `pro_3d_render`, [워크스페이스 도구](https://nodaro.ai/docs/mcp/tools/workspaces), [Recast 도구](https://nodaro.ai/docs/mcp/tools/recast), [스튜디오 프로덕션 도구](https://nodaro.ai/docs/mcp/tools/studio-productions), [파이프라인 도구](https://nodaro.ai/docs/mcp/tools/pipelines), [UGC 도구](https://nodaro.ai/docs/mcp/tools/utility#the-ugc-video-builders)입니다. 워크스페이스 도구는 조직 기능도 켜져 있어야 하며, `pro_3d_render`는 렌더링 엔진을 사용할 수 있을 때만 나타납니다.

## 자주 묻는 질문

### Nodaro MCP 서버에는 도구가 몇 개 있나요?

Nodaro Cloud에서 약 200개입니다. 사용할 수 없는 도구는 도구 목록에서 빠지므로, 정확한 목록은 내가 허용한 권한과 에디션에 따라 다릅니다.

### 어시스턴트는 생성 결과를 어떻게 받나요?

생성 도구는 작업을 시작하고 그 id를 바로 반환합니다. MCP Apps를 표시하는 클라이언트는 실시간 진행 상황과 결과가 담긴 카드를 보여 주고, 다른 클라이언트는 그 id로 get_job이나 wait_for_job을 호출합니다.

### 어시스턴트가 mcp 프로젝트의 워크플로만 편집할 수 있는 이유는 무엇인가요?

워크플로 도구는 mcp라는 프로젝트 하나 안에서 작동하므로, 어시스턴트가 내 프로젝트를 바꾸는 일이 없습니다. 그래도 export_workflow로 어떤 워크플로든 읽을 수 있고, 그 사본을 mcp 프로젝트로 가져올 수 있습니다.

### 어떤 도구가 무료인가요?

ping, list_models, get_node_skill, get_picker_catalog, list_shot_shapes, get_recipe 같은 탐색 도구와 가이드 도구는 비용이 들지 않습니다. 미디어를 생성, 편집, 분석하는 모든 도구는 크레딧을 씁니다.