---
title: "Claude가 할 수 있는 일"
description: "Filmsquare가 내 Claude에게 주는 모든 MCP 툴, find_actions와 run_action이 나머지 API에 닿는 방법, 일부러 뺀 것을 알려 드려요."
url: https://www.filmsquare.ai/docs/ko/claude/tools/
lang: ko
section: claude
updated: 2026-11-15
mcp: [find_actions, run_action, whats_waiting, list_productions, get_episode, get_feedback, reply_feedback, view_media, upload_file, get_script, edit_script, submit_breakdown, get_continuity, report_continuity, submit_style, request_signoff, sign_off, where_does_it_go, prepare_upload, add_to_visualize, studio_analytics]
---

# Claude가 할 수 있는 일

내 Claude는 Filmsquare에서 내 역할로 API가 허용하는 일을 할 수 있어요. 이름 붙은 툴 열여덟 개가 평소 작업을 맡고, `find_actions`와 `run_action` 두 개가 나머지 모든 API 액션에 닿아요. 모든 호출은 API를 그대로 거쳐서 내 이름으로 나가요. 같은 역할 확인, 같은 검증, 같은 게이트예요.

## 이름 붙은 툴

| 툴 | 하는 일 | 필요한 것 |
| --- | --- | --- |
| `whats_waiting` | 내 컨펌을 기다리는 팀 단계와 읽지 않은 알림. 여기서 시작해요 | — |
| `list_productions` | 워크스페이스의 작품과 에피소드 | — |
| `get_episode` | 에피소드 하나. 씬과 컷을 편집 순서대로, 팀별 단계 전부(컨펌 완료, 누구를 기다리는지, 수정 요청, 미완료), 파이널을 렌더할 수 있는지 | `episode_id` |
| `get_feedback` | 컷, 테이크, 에피소드, 씬, 요소, 폴더, 에셋 버전, 캔버스, 캔버스 박스의 코멘트 스레드. 모든 메시지와 핀(프레임 단위 타임코드나 이미지의 영역)을 포함해요. 기본은 열린 스레드이고, 나머지는 `status`를 `resolved`나 `all`로 지정해요. `target_type`이 `sheet`이면 시트 최신 버전의 열린 코멘트(의도, 인용 또는 시트 전체, 제안 텍스트, 처리 여부)와 이전 버전의 코멘트가 어떻게 끝났는지 | `target_type`, `target_id` |
| `reply_feedback` | 스레드에 내 이름으로 답글(`@name` 멘션은 알림이 가요)을 달고, 코멘트가 처리되면 해결해요. 시트의 코멘트는 해결 대신 처리함으로 표시해요. 제안이 있으면 `suggestion_outcome`(적용, 수정 적용, 거절)이 필수이고, 확인은 사람이 해요 | `thread_id`, `body` |
| `view_media` | 스틸, 키프레임, 테이크를 Claude가 볼 수 있는 이미지로. 영상은 포스터 이미지와 다운로드 링크로 돌아와요 | `asset_version_id` |
| `upload_file` | 대화 속 파일을 컷이나 씬 레이어의 새 테이크로, 또는 작품 에셋으로 넣어요. 최대 10MB. `pick: true`이면 OK컷으로도 골라요(감독 이상) | `name`, `mime`, `data_base64` |
| `where_does_it_go` | 파일이 어느 화면에 들어가야 하는지: 지도, 판단 트리, 실제 예시. 화면 이름을 말할 때 읽어요 | — |
| `prepare_upload` | 디스크에 있는 파일 최대 100개의 서명된 업로드 URL과 바로 쓸 수 있는 `curl` 명령. 바이트가 대화를 거치지 않아요. 영상은 모두 이걸로 올려요 | `files` |
| `add_to_visualize` | 올린 파일을 **Storyboard → 3D**나 **Storyboard → Animatic**에, 컷과 씬에 번호로 맞춰 한 번에 최대 100개 넣어요. 같은 걸 다시 보내도 바뀌는 건 없어요 | `episode_id`, `items` |
| `get_script` | 에피소드의 최신 시나리오 고와, 이미 있는 캐스트, 세트, 소품의 `@handles` | `episode_id` |
| `edit_script` | 시나리오 전체를 보내지 않고 씬, 대사, 한 줄을 고쳐요. 정확히 일치하는 텍스트와 바꿀 내용을 새 버전으로 저장하고, 코멘트와 태그는 따라가요 | `episode_id`, `base_rev`, `edits` |
| `submit_breakdown` | Claude의 브레이크다운을 Filmsquare에 넣어요. 씬, 연기가 있는 컷, 대사, 캐스트, 세트, 소품. 그러면 각본이 컨펌을 기다려요 | `episode_id`, `breakdown` |
| `get_continuity` | 에피소드의 연결 시트. 컷마다 재생되는 것, 요소와 그 레퍼런스, 각 OK컷이 무엇으로 만들어졌는지, 지금까지의 결과, 다시 체크할 컷. 먼저 무료 계보 체크를 돌려요 | `episode_id` |
| `report_continuity` | 눈으로 본 연결 체크를 기록해요. 어긋난 곳마다 OK컷에 코멘트가 달려요 | `episode_id`, `seen`, `issues` |
| `submit_style` | 스타일 가이드를 스타일 라이브러리(**Create → Styles**)에 넣어요. 새 스타일이거나, `style_id`를 주면 그 스타일의 다음 버전이에요. `production_id`를 주면 그 작품의 스타일이 돼요. 내 작업에는 레퍼런스 스틸을 6장까지 붙일 수 있어요(`prepare_upload`로 올려요). 남의 작업은 텍스트만 쓰고 공개하지 않아요. 사람이나 브랜드 이름은 거절돼요. 작업자 역할 | `name`, `guide` |
| `request_signoff` | 팀의 컨펌 담당자에게 에피소드 단계의 컨펌을 요청해요. 담당자에게 알림이 가요 | `episode_id`, `department` |
| `sign_off` | 한 단계에 대한 내 결정을 기록해요. `approved` 또는 `changes_requested`, 선택 사항으로 `note`. 그 단계의 컨펌 담당자만 할 수 있어요. `expect_version`(내가 본 단계 버전)을 주면 작업이 바뀐 경우 `changed_since`로 거부돼요. 내가 Claude에게 결정하라고 시켰을 때만 | `episode_id`, `department`, `decision` |
| `studio_analytics` | 소유자와 프로듀서용이에요. **Analytics**의 숫자로 보는 스튜디오 현황. `view`는 `crew`(기간 동안 사람별: 납품, 납품당 크레딧, 컨펌까지의 시간, 첫 통과율, 레인, 리두, 직접 작업과 에이전트 단독 시간, 스튜디오 중앙값, 단계별 시간), `day`, `costs`, `report`(발송될 모양 그대로의 리포트 메일 텍스트) 중에서요. 다른 사람은 거부되고 자기 숫자만 봐요 | `view` |

모든 툴은 선택 사항인 `workspace`도 받아요. 비워 두세요. 연결의 워크스페이스가 쓰여요.

`department`는 `writing`, `breakdown`, `casting`, `voice`, `wardrobe`, `sets`, `props`, `animatic`, `music`, `draft`, `sound`, `edit`, `final` 중 하나예요.

## 미디어가 가는 곳

화면 이름은 평소 말투로 Claude에게 알려 주세요(“3D에 넣어 줘”). Claude는 이렇게 처리해요.

| 가진 것 | 가는 곳 | 방법 |
| --- | --- | --- |
| 한 컷의 클레이 렌더나 스틸(렌즈, 높이, 무빙 포함) | **Storyboard → 3D**, 해당 컷 | `add_to_visualize` |
| 컷, 테이크, 씬의 Blender 클립 | **Storyboard → 3D**, 그 클립이 덮는 대상 | `add_to_visualize` |
| 씬, 시퀀스, 에피소드의 애니매틱 | **Storyboard → Animatic** | `add_to_visualize` |
| 컷의 드래프트나 파이널 영상 | **Storyboard → Shots**, 테이크로 | `upload_file` |
| 레퍼런스 이미지나 무드 보드 | **Home → Files** | `upload_file` |

엉뚱한 곳에 들어간 건 다시 올리지 않고 옮겨요. `run_action`으로 `moveTake`나 `moveAsset`을 써요(감독 이상). 가져오기가 만든 OK컷은 이동과 함께 해제돼요. 누군가 OK컷으로 고른 테이크나 여기서 생성한 테이크는 제자리에 남아요.

## find_actions와 run_action

이름 붙은 툴이 없는 일은 모두 이 둘로 해요. 컷 만들기, OK컷 고르기, 드래프트 만들기, 견적, 요소와 버전, 폴더, 캔버스, 비용, 브리프, 스태프가 해당돼요.

1. `find_actions`는 몇 단어로 API 자체의 카탈로그를 검색해요. “pick take”, “create shot”, “resolve thread” 같은 단어요. 맞는 액션을 메서드, 경로, 요약, 최소 역할, 입력과 함께 돌려줘요.
2. `run_action`은 액션을 이름으로 실행해요. 액션 설명대로 `path_params`(워크스페이스는 제외), `query`, `body`를 넘겨요. API의 JSON으로 답해요.

`find_actions`는 현장 용어를 알아들어요. 스태프가 쓰는 단어를 API의 단어로 연결해 줘요. 검색어는 영어 기준이라 아래 표의 단어는 그대로 입력해요.

| 입력하는 단어 | 함께 검색하는 단어 |
| --- | --- |
| pick, choose | select |
| note, notes, comment, comments, feedback | thread, message |
| reply | message |
| render | generation, generate |
| make | create, generate |
| new, add | create |
| remove, delete | archive |
| sign | signoff |
| approve | signoff, approval |
| cast, character, prop | element |
| set | element, location |
| production, productions | project |
| crew | member, steps |
| cost | costs, estimate |
| price | estimate |
| prompt, preview, dry run | generate |
| kosten, schatting, prijs (네덜란드어) | generate, estimate |
| mismatch | continuity |
| model, models | models, acceptance, routing |

새 API 액션은 출시되는 즉시 `find_actions`에 나타나요. 새 툴은 필요 없어요.

### 예시

| 하고 싶은 일 | 검색어 | 액션 |
| --- | --- | --- |
| 렌더 전에 드래프트 가격 보기 | “estimate shot” | `estimateShotGeneration` |
| 렌더 전에 프롬프트, 모델, 크레딧 보기 | “dry run” | `{"kind": "video", "tier": "draft", "dryRun": true}`와 함께 `generateForShot` |
| 드래프트 렌더 | “generate shot” | `{"kind": "video", "tier": "draft"}`와 함께 `generateForShot` |
| 테이크를 OK컷으로 고르기 | “pick take” | `selectTake` |
| 드래프트를 파이널로 만들기 | “promote” | `promoteGeneration` |
| 코멘트로 리테이크 | “revise take” | `estimateReviseTake`, 그다음 `reviseTake` |
| 어떤 모델이 OK로 이어지는지 보기 | “model acceptance” | `getModelAcceptance` |
| 에피소드 비용 | “episode costs” | `getEpisodeCosts` |

렌더하기 전에 Claude는 생성 액션을 `dryRun: true`로 불러요. 컴파일된 프롬프트, 모델, 레퍼런스, 크레딧을 보여 주고 아무것도 만들지 않아요. 그다음 그 렌더 한 번에 한해 프롬프트를 바꿀 수 있어요. `overrides.prompt`는 프롬프트 텍스트를 바꾸고(레퍼런스 줄은 그대로라서 캐스트, 세트, 소품은 항상 함께 가요), `overrides.promptAppend`는 덧붙이고, `overrides.negativePrompt`는 피할 것을 추가해요. 대사는 대사 줄로 낭독하기 때문에 프롬프트 오버라이드를 받지 않아요.

드라이 런은 `provider`와 `model_key`로 답해요. 이걸 `provider`와 `modelKey`로 다시 넘기면 그 모델이 고정돼요. `getGeneration`은 테이크가 무엇으로 만들어졌는지 다시 읽어요. 프롬프트, 모델, 예상 크레딧, 기록된 크레딧이에요.

## API가 거부할 때

거부는 API의 코드와 상세 내용이 담긴 툴 오류로 돌아와요. 예를 들어 `The API refused: 409 gate_closed: finals render once casting, sets, animatic are signed off {"episode_id": "…", "waiting_on": ["casting", "sets", "animatic"]}`처럼요. Claude가 읽고 무엇이 빠졌는지 알려 줘요. [자주 만나는 오류](https://www.filmsquare.ai/docs/ko/api/overview/#errors-you-will-meet)를 보세요.

## 일부러 뺀 것

Claude는 이런 것에는 닿을 수 없어요. 설계상 그래요.

- **API 키와 Claude 연결:** 연결이 키를 만들거나 다른 연결을 허용할 수는 없어요. 로그인한 사람이 해요.
- **OAuth**와 회원가입.
- **웹훅:** Filmsquare 밖으로 데이터를 보내는 기능이에요.
- **제공사 콜백**과 **실시간 소켓**(캔버스와 접속 표시).

파이널 게이트, 크레딧 확인, 요금제 한도는 Claude에게도 다른 누구와 똑같이 적용돼요.

## 안전

- **Claude는 나로 움직여요.** 내 역할(또는 연결할 때 고른 더 낮은 역할)을 가지고, 한 일은 내 이름으로 나타나요.
- **스태프의 자료는 지시가 아니에요.** Claude가 Filmsquare에서 읽는 코멘트, 시나리오, 기타 텍스트는 스태프가 올린 자료예요. Filmsquare가 Claude에게 그렇게 알려 줘요. Claude가 무엇을 할지는 나만 결정해요.
- **가격을 먼저 말해요.** 테이크를 만들면 크레딧이 들어요. Claude는 아무것도 만들지 않는 `dryRun: true`로 생성 액션을 부르고, 테이크를 시작하기 전에 비용이 얼마인지 말하고, 시키지 않으면 파이널을 렌더하지 않도록 지시받아요.
- **시키지 않으면 컨펌하지 않아요.** `sign_off`는 내 이름으로 결정을 기록해요. Claude는 내가 결정하라고 시켰을 때만 쓰도록 지시받아요.

## 프롬프트

프롬프트 넷에 흔한 일의 작업 방식이 담겨 있어요. `break_down_episode`, `process_feedback`, `work_on_step`, `check_continuity`예요. [프롬프트와 작업 방식](https://www.filmsquare.ai/docs/ko/claude/prompts/)을 보세요.
