> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 도구 사용하기
> 도구가 무엇인지, 왜 직접 호출하지 않는지, 거절할 때 무엇을 할지. 엔지니어가 아니라 사람을 위해 썼습니다.
[도구 레퍼런스](/docs/docs/tools/image-generation)는 이 프로젝트가 할 수 있는 모든 것을, AI가 읽는 형태로 나열합니다. 이 페이지는 당신을 위한 버전입니다.
여기 있는 것은 코드를 쓰거나, JSON을 치거나, API를 배울 것을 요구하지 않습니다. 누군가에게
"내 초상 워크플로우를 열고 steps를 30으로 올려"라고 부탁해 본 적이
있다면, 이미 인터페이스를 아는 것입니다.
## 도구는 에이전트가 할 수 있는 일이지, 직접 입력하는 것이 아닙니다
혼자서는 채팅 모델이 텍스트만 만들 수 있습니다. 워크플로우를 설명할 수는 있고, 열 수는 없습니다.
**도구**는 모델이 실제로 ComfyUI에 닿을 수 있도록 건네는 구체적이고 이름 있는 동작입니다 — 파일을 불러오고, 렌더를 대기열에 넣고, 노드 팩을 설치하고, 나온 그림을 봅니다. 모델은 이것을 발명할 수 없습니다. 고정된 메뉴를 받으며, 메뉴의 각 항목은 무엇이 필요한지 정확히 말합니다.
**그 메뉴에서 고르는 일은 없습니다.** 자연스럽게 나오는 말로 원하는 것을 말하면, 에이전트가 고릅니다.
| 당신이 말하는 것 | 조용히 실행하는 것 |
| --------------------- | -------------------------------------------------------------- |
| "뭐가 저장되어 있어?" | `get_workflow` with `action: "list"` |
| "초상 그거 열고 뭐 하는지 말해 줘" | `get_workflow` with `action: "list"`, then `action: "analyze"` |
| "눈 속의 빨간 여우 만들어 줘" | `generate_image` (the `image` job) |
| "아직 안 끝났나?" | `queue` (the `list` job) |
| "실패했는데 왜인지 모르겠어" | `get_history` (the `diagnose` job) |
| "노드 절반이 빨개" | `list_packs` (the `install_deps` job) |
| "디스크가 부족해, 뭐가 커?" | `list_local_models` |
두 번째 행을 보세요: 문장 하나, 도구 둘, 알 필요 없었던 순서. 그것이 이 전체 배치의 요점입니다. 파일을 찾는 것과 읽는 것이 별개 작업이라는 것을 알 것으로 기대하지 않습니다.
원하는 만큼 모호해도 됩니다. "뭔가 깨졌어"는 완벽한
시작입니다 — 에이전트가 `get_system_stats (action:"health")`로 시작해 좁혀 갑니다. 구체적으로
말하면 더 빠르지만, 필수는 아닙니다.
### 레퍼런스 페이지의 JSON은 무엇인가?
모든 도구 페이지는 이런 블록을 보여 줍니다:
```json theme={null}
{
"tool": "generate_image",
"arguments": {
"prompt": "a red fox in deep snow, golden hour, sharp focus",
"steps": 30
}
}
```
그것은 에이전트가 보낸 트랜스크립트이지, 당신을 향한 지시가 아닙니다. "눈 속의 빨간 여우 만들어 줘, 디테일을 조금 더"라고 말했고, 반대편에서 나온 것이 그것입니다.
읽을 수 있는 것은 두 가지 이유로 가치가 있습니다: 에이전트가 이해했는지 확인하고 싶을 때, 그리고 무언가 잘못되어 다른 사람에게 설명할 때. 외울 가치는 없습니다.
## 도구가 오는 두 곳
표면이 둘입니다. 다른 질문에 답하기 때문에 존재합니다.
ComfyUI **안**, 에이전트 탭에 있습니다. 도구(`panel_*`)는 지금
보고 있는 그래프에 작용합니다 — 저장하지 않은 변경이 있는
실제 캔버스.
Claude Desktop, Claude Code, 에디터, 휴대폰. 도구는
**서버**에 작용합니다: 디스크의 파일, 작업 대기열, 모델, 노드 팩,
ComfyUI 프로세스 자체.
갈라짐은 사실 "이것"이라는 단어에 관한 것입니다. "**이것**에 LoRA를 추가해"라고 말하면, 패널은 "이것"이 무엇인지 압니다. 화면을 볼 수 있기 때문입니다. 바깥 클라이언트는 할 수 없습니다 — 파일명을 들어야 합니다.
그래서 패널이 다루는 것은:
* 앞에 있는 그래프 읽기 (`panel_graph_outline`)
* 직접 Queue Prompt를 누른 것과 똑같이 실행하기 (`panel_run`)
* 노드를 연결하고, 위젯을 바꾸고, 노드가 빨개진 이유를 말하기 (`panel_add_node`, `panel_set_widget`, `panel_get_errors`)
* 캔버스에 워크플로우 전체를 불러오거나, 있는 것을 저장하기 (`panel_load_workflow`, `panel_save_workflow`)
그리고 바깥 클라이언트는 처음부터 이미지를 생성하고, 모델과 노드 팩을 관리하고, 저장된 파일을 다루고, ComfyUI를 재시작하는 일을 합니다.
**처음이라면 패널을 쓰세요.** 설치 한 번이고, 그래프 바로 옆에
있으며, 별도 앱이 필요 없습니다.
[패널 가이드](/docs/docs/ko/panel)에서 설정하세요. 캔버스가 아닌 일에
에이전트가 관여하기를 원할 때 바깥 클라이언트를 더하세요.
라이벌이 아닙니다 — 패널은 아래에서 같은 서버와 대화하고, 세션은 둘 다 쓸 수 있습니다. 데스크톱에서 그래프를 편집하는 동안 휴대폰이 같은 세션을 구동하는 것은 해킹이 아니라 지원되는 일입니다.
## 도구 하나, 작업 여러 개
어떤 도구는 `action`을 받는다는 것을 알게 됩니다:
```json theme={null}
{ "tool": "workspace", "arguments": { "action": "get" } }
```
암호처럼 보이지만 아닙니다. `workspace`는 주제입니다 — *어느 ComfyUI 설치를 말하는가* — 그리고 `action`은 그 주제에 대해 묻는 질문입니다: 읽고, 기본값을 바꾸고, 무엇이 있는지 나열하기.
동사와 목적어가 별개 단어인 평범한 말과 정확히 같이 읽힙니다:
| 당신이 말하는 것 | 액션 |
| ----------------------- | ------------- |
| "지금 어느 ComfyUI를 쓰고 있어?" | `get` |
| "항상 D 드라이브의 것을 써" | `set_default` |
| "어떤 설치가 보여?" | `list` |
### 사라진 것은 없습니다
이 형태는 비교적 새롭고, 능력이 잘린 것으로 읽기 쉽습니다. 아닙니다. 이미 나온 혼동이므로 바로 막는 것이 가치가 있습니다.
예전에는 질문마다 도구가 하나였습니다 — 워크스페이스를 읽는 이름, 설정하는 이름, 나열하는 이름. 그 이름은 사라졌고, 도구 수를 보면 급격히 떨어지는 것이 보입니다.
실제로 일어난 일은 관련 도구가 삭제된 것이 아니라 **병합**된 것입니다:
| 예전 이름 | 오늘 같은 것 |
| ------------------------------- | ------------------------------------------- |
| `get_workspace` | `workspace` with `action: "get"` |
| `get_queue` | `queue` with `action: "list"` |
| `apps_run_status` | `apps` with `action: "run_status"` |
| `install_workflow_dependencies` | `list_packs` with `action: "install_deps"` |
| `list_workflows` | `get_workflow` with `action: "list"` |
| `analyze_workflow` | `get_workflow` with `action: "analyze"` |
| `validate_workflow` | `create_workflow` with `action: "validate"` |
아래의 같은 코드, 같은 동작, 같은 답. 앞의 라벨만 바뀌었습니다.
이유는 메뉴가 아플 만큼 길어졌기 때문입니다. 모든 도구의 전체 설명이 고르기 전에 모델에 건네져야 하고, 어느 크기를 넘으면 고르기 자체가 나빠집니다 — 특히 작은 모델이 맞는 것 대신 그럴듯한 이웃을 고르기 시작합니다. 더 적고 넓은 도구에 분명한 `action`이 측정 가능하게 그것을 고칩니다. 또한 모델이 카탈로그를 읽는 대신 요청에 주의를 쓰게 합니다.
이 중 어느 것도 알아채지 않아야 합니다. 예전 이름도 친 적이 없습니다. "어느 ComfyUI에 있어?"라고 말했고, 그것은 여전히 동작합니다.
오래된 가이드나 모델 자신의 기억이 더 이상 없는 이름을
찾으면, 빈 "unknown tool"이 아니라 대체물을 이름 붙인 구체적
오류를 받습니다 — 예를 들어: *removed in 0.49.0. Call workspace (action:"get")
instead.* 에이전트는 보통 스스로 고치고 재시도하며, 당신이
할 일은 없습니다.
## 다른 것을 요청하기
모든 도구 페이지는 매개변수를 나열합니다 — `max_chars`, `limit`, `depth`, `fields`. 어디에 치라는 것인지 타당한 질문이고, 정직한 답은: 어디에도 아닙니다. `max_chars`를 위한 설정 상자가 없습니다. 설정이 아니기 때문입니다. **에이전트**가 도구를 호출할 때마다 새로 채우는 인자입니다.
그것이 당신을 빼지는 않습니다. 제어가 어떻게 보이는지만 바꿉니다:
매개변수를 설정하지 않습니다. 요청합니다 — 어차피 쓰려던
같은 문장 안에서.
### 요청하는 두 가지 방법
둘 다 동작합니다. 실패하는 방식이 다르므로, 둘 다 아는 유일한 이유입니다.
| | 이렇게 들림 | 이럴 때 손을 뻗음 |
| ------- | ---------------------------------------------------------- | ---------------------------------------- |
| **평범한** | "노드 42를 자세히 읽어 — 그 노드만, 그래프 전체가 아니라." | 항상 여기서 시작하세요. 사람들이 실제로 치는 것이고, 보통 동작합니다. |
| **명시적** | "`panel_query_graph`를 `ids` \[42]와 `max_chars` 20000으로 써." | 모델이 이미 한 번 틀렸고 여지를 남기고 싶지 않을 때. |
도구와 인자를 이름 부르는 것은 *올바른* 형태가 아니라 — *강제하는* 형태입니다. 재시도에 남겨 두세요.
### 답이 잘렸을 때
긴 읽기는 거대한 그래프 하나가 대화 전체를 삼키지 못하도록 상한이 있습니다. 같은 읽기를 멈출 수 있는 천장이 둘입니다 — 나열된 노드 수 (`limit`)와 문자 예산 (`max_chars`) — 문제가 아닌 쪽을 올려도 아무것도 바뀌지 않으며, 그것은 재시도가 실패한 것과 정확히 같이 읽힙니다.
어느 쪽인지 알아낼 것으로 기대하지 않습니다. 저장된 파일에서, 노트는 **발동한 레버를 이름 붙이고 다른 쪽을 배제**합니다, 말 그대로:
> … truncated at 40 of 300 by `limit`=40 — raise `limit` up to 200, or narrow with `types`/`where`/`ids`/`depth`. `max_chars` is not the constraint here.
그리고 레버가 이미 천장에 있으면 다시 올리라고 보내지 않고 그렇게 말합니다. 올릴 것이 남아 있지 않기 때문입니다.
라이브 캔버스(`panel_query_graph`)에서 같은 읽기는 패널 자신의
이 엔진 사본이 실행하며, 그 문구를 아직 따라잡지 못했습니다. 노트가
인자를 이름 붙이고 올려도 아무것도 바뀌지 않으면, 도구가 깨졌다고
결론 내기 전에 다른 쪽을 시도하세요.
에이전트는 자신의 노트를 읽고 스스로 재시도해야 합니다. 하지 않을 때, 당신이 폴백이며, 이 문장입니다:
> 잘렸어 — 노트를 읽고 이름 붙인 한도를 올려 같은 쿼리를 다시 해.
### 한계가 있는 곳
예산으로 그래프를 읽는 두 도구의 숫자입니다 — `panel_query_graph` (라이브 캔버스)와 `action: "query"`의 `get_workflow` (저장된 파일):
| 인자 | 기본값 | 요청할 수 있는 최대 |
| ---------------- | ----- | ----------- |
| `max_chars` | 12000 | 60000 |
| `limit` (나열된 노드) | 40 | 200 |
이 두 도구에서, 천장을 넘는 요청은 조용히 내림하지 않고 잘못된 인자로 거부되므로, 에이전트가 즉시 알고 스스로 고칠 수 있습니다. 숫자도 보편적이지 않습니다: 다른 여러 도구가 `max_chars`를 받고 자체 천장을 두며, 그 도구의 설명에 적혀 있습니다.
### 범위가 예산보다 낫다
천장을 올리는 것은 두 번째로 시도할 일이지, 첫 번째가 아닙니다. 600노드 워크플로우에서, 더 큰 예산은 대체로 잘못된 노드를 더 사며, 수백 개의 무관한 것 속에 답을 묻으면 기술적으로 들어가더라도 답변이 나빠집니다.
먼저 좁히세요, 자연스러운 말로:
| 당신이 말하는 것 | 좁히는 대상 |
| ------------------ | ------------ |
| "노드 42와 43만 봐." | 그 id만 |
| "샘플러로 무엇이 들어가?" | 한 노드의 업스트림 쪽 |
| "…두 홉만 뒤로." | 거기에서 묶인 거리 |
| "여기 노드 타입별로 몇 개야?" | 목록 대신 개수 |
그다음, 여전히 잘리면, 넓히세요.
## 거절할 때
도구가 거절하는 것은 보통 버그가 아닙니다. 대부분의 거절은 요청하지 않은 일을 했을 가드가 발동한 것입니다.
### "거절했는데 이유를 모르겠어요"
스택 트레이스가 아니라 평범한 언어의 텍스트를 보게 됩니다 — 하지 않을 일과 대신 할 일을 이름 붙입니다. 에이전트가 막힌 것이 아니라 조심하는 것으로 읽으세요. 흔한 정직한 거절:
* **어느 워크플로우인지 알 수 없습니다.** 탭이 둘 이상 열려 있거나, 그래프에 아직 저장된 신원이 없습니다. 저장하거나, 어느 것인지 말하세요.
* **무언가를 덮어쓸 것입니다.** 새 파일명을 요청하면 진행합니다.
* **그 물건이 정말로 없습니다.** 모델 파일, 노드 팩, 실행 중인 서버.
거절이 주의가 아니라 말도 안 되게 읽히면, 보고할 가치가 있습니다 — 에이전트에게 접수하라고 하면, 설정 세부 사항을 대신 붙입니다.
### "이 패널이 너무 오래되었습니다"
실제 수정이 있는 가장 흔한 거절입니다. 대략 이렇게 읽힙니다:
> This ComfyUI-MCP panel is too old for *"…"* — update the ComfyUI-MCP panel, then reconnect.
사이드바 패널과 이 서버는 따로 출시되는 별개 조각이므로, 하나가 다른 하나를 뒤처질 수 있습니다. 서버가 설치된 패널이 안전하게 할 수 없는 것을 요청하면, 추측하는 대신 거절합니다 — 명령이 어느 워크플로우에 착지하는지 확인할 수 없는 오래된 패널은 잘못된 탭에 편집을 적용할 수 있으므로, 업데이트될 때까지 읽기에 묶입니다.
수정은 세 단계이고, **세 번째를 사람들이 건너뜁니다**:
에이전트에게 업데이트하라고 하거나 (`install_comfyui(action:'panel', panel_action:'update')`),
ComfyUI-Manager에서 하세요. 거기서는 `comfyui-agent-panel`로 올라 있습니다.
업데이트는 스스로 아무것도 재시작하지 않습니다. 에이전트에게 요청하거나,
직접 재시작하세요.
**Ctrl+Shift+R** (Mac에서는 **Cmd+Shift+R**). 브라우저가 오래된 패널
코드를 캐시하고 있으며, 재시작만으로는 떨어지지 않습니다. 이것을 건너뛰면
같은 메시지가 바로 돌아오므로, 업데이트가 실패한 것처럼 보이지만
그렇지 않습니다.
### "연결된 패널이 없습니다"
다른 문제, 비슷하게 보이는 메시지. 바깥 에이전트가 ComfyUI 브라우저 탭을 찾지 못한다는 뜻입니다. 거의 항상 다음 중 하나입니다:
* ComfyUI가 브라우저에 아예 열려 있지 않습니다 — 열고 사이드바의 에이전트 탭을 보세요.
* ComfyUI를 방금 재시작했거나, 탭을 다시 불러왔습니다. 그것이 연결을 떨어뜨립니다. **ComfyUI 탭을 다시 불러오면** 바로 돌아옵니다.
* 에이전트 탭은 열려 있지만 한 번도 연결되지 않았습니다. 패널은 제공자를 고르고 **연결**을 클릭할 때 붙으며, 로드 때는 절대 아니므로, 아무것도 안 보이는 갓 연 탭은 고장이 아니라 평범한 상태입니다.
* 패널이 아직 설치되지 않았습니다. [패널 가이드](/docs/docs/ko/panel)를 참고하세요.
메시지가 이것을 두 그룹으로 갈라 줍니다 — "이전에 연결되었다가 떨어짐"과 "아직 아무것도 연결되지 않음"을 구분합니다. 그 이상은 가지 않으며, 관찰할 방법이 없는 원인을 고르는 대신 그렇게 말합니다. 이전에 연결된 탭은 패널이 설치되어 동작했음을 증명하므로, ComfyUI 탭을 다시 불러오는 것이 먼저 시도할 일이고 보통 유일한 일입니다. 다시 불러와도 돌아오지 않으면, 두 번째 그룹으로 다루고 위의 점검을 내려가세요.
## 아무 말도 하지 않을 때
더 어려운 실패는 오류가 전혀 없는 것입니다. 에이전트가 도구를 호출하지 않고, 거절하지 않고, 불평하지 않습니다. 그냥 말합니다: 워크플로우에 무엇이 들어 있을 것 같은지 설명하거나, 스크립트를 써 주겠다고 제안합니다. 도움이 되는 것처럼 들리고, 아무것도 본 적이 없습니다.
완전히 다른 세 상황이 같은 동작을 만들고, 앉아 있는 곳에서는 구별할 수 없습니다:
클라이언트가 도구를 받지 못했습니다. 모델에 건네는 목록에 없으므로,
호출할 것이 없습니다.
클라이언트에 도구가 있고 모델이 실행하게 두지 않습니다. 호출이
클라이언트 안에서 멈춥니다.
모든 것이 동작합니다. 원하던 것이 한 번도 나오지 않은 이름 아래 있어,
아무도 손을 뻗지 않았습니다.
처방은 세 방향으로 가리키고, 둘은 잘못 추측하면 적극적으로 해롭습니다: 이미 설치된 것을 다시 설치하거나, 문제가 아니었던 권한을 푸는 것. 그래서 첫 수는 아무것도 고치지 않는 것입니다. 어느 것인지 알아내는 것입니다.
### 둘을 가르는 두 가지 질문
에이전트에게, 평범한 말로 물어보세요:
> comfyui-mcp에서 어떤 도구가 있어? 이름만 나열해.
이름 몇십 개의 목록이 정상이고 건강합니다 — 그것이 직접
표면이며, 0.50.0부터 기본값입니다.
**이름 세 개** — `list_tools`, `describe_tool`, `call_tool` — 도
정상이고 건강합니다. 그것이 [컴팩트 모드](#작은-로컬-모델을-쓰는-경우)이며,
`--compact`를 넘겨 얻고, 작은 로컬 모델은 여전히
자동으로 고릅니다. 카탈로그의 나머지는 `list_tools` 호출
하나 거리이므로, 그것을 실행하라고 하면 진짜 목록이 보입니다. 어느 답도
무언가가 숨겨져 있다는 뜻이 아닙니다.
**이름이 전혀 없거나**, "ComfyUI용 도구가 없어"는 세 번째
경우를 배제하고 그 이상은 아닙니다. 없음이 **아닙니다**. 권한 정책이
모델에 보여 주는 목록에서 도구를 거둘 수 있으므로, 설치되고 연결되고
동작하는 서버가 정확히 이 답을 만듭니다. 없음과 차단됨은
이 단계에서 구별할 수 없고, 이것이 사용자에게 며칠을 쓰게 한
가지입니다 — 배선이라고 확신하는 것.
한 점검이 좁히고, 그것은 에이전트가 볼 수 있는 것이 아닙니다: **클라이언트의
자체 MCP 서버 목록을 여세요** — 어느 서버에 연결했는지 보여 주는 곳이며,
모델에 건네는 도구와는 다른 목록입니다.
* **comfyui-mcp가 없거나, 실패로 표시됨** → **없음**. 클라이언트 측
배선 문제이지, 패널이나 서버 고장이 아닙니다. 다시 둘로 갈라집니다 —
한 번도 연결되지 않았거나, 아예 붙잡을 수 없는 호스트 — 그리고
[아래](#각-답이-보통-어디서-오는지) 목록이 그것을 가릅니다.
* **거기 있고 연결되었으며, 모델이 여전히 아무것도 나열하지 않음** → 도구가
클라이언트에 닿았습니다. 그 다음 어디서 멈췄는지는 아직 열려 있습니다: 권한
규칙이 모델에서 거뒀거나, 모델이 나열에 실패했거나 거절했을 수 있으며,
여기서는 똑같아 보입니다. 이것만으로 권한을
**풀기 시작하지 마세요**.
그 서버 목록이 **comfyui-mcp에서 가져온 도구**도 보여 주면,
정리됩니다: 거기에는 나열되고 모델에는 없으면 권한이 아니라 모델이
문제입니다. 거기에 하나도 없으면 모델이 보기 전에 필터되고 있는
것입니다. 클라이언트가 그것을 보여 주지 않으면 — 많은
클라이언트가 그렇지 않습니다 — 여기서 둘을 가를 수 있는 것이 없고, 2단계가
더 나은 기회입니다. 거부가 말로 돌아오기 때문입니다.
> 이제 동작하지 않는 것에 쓸 것을 호출하고, 돌아오는 것을
> 그대로 붙여넣어 — 오류도 포함해서. 우회하지 마.
그 문장의 두 세부가 일을 합니다.
**동작하지 않는 것에 쓸 도구**, 구체적으로. 권한
규칙은 보통 도구별로 쓰이므로, 다른 도구가 성공해도 신경 쓰는
것에 대해 아무것도 증명하지 않습니다 — 그것이 정확히 차단이 숨는 방법입니다. 캔버스가
읽히지 않는 것이라면, 시험은 캔버스 읽기여야 합니다.
**우회하지 마.** 전체 실패 모드는 에이전트가 장애물을 이름 부르는 대신
조용히 돌아가는 것이고, 혼자 두면 또 그렇게 합니다.
* **실제 결과** — 그 도구가 동작합니다. 세 번째 경우입니다.
* **"거부됐어" / "허용되지 않아" / "권한이 필요해"** — **차단됨**,
클라이언트 안에서. 이것은 결정적입니다: 에이전트가 요청했고 거절당했습니다.
* **"그 도구가 없어"** — 없음 *또는* 차단됨, 여전히. 거둔 도구와
빠진 도구는 모델의 자리에서는 똑같으므로, 이것만으로 행동하지
마세요: 1단계의 서버 목록으로 돌아가고, 그 목록도 서버별
도구를 보여 주지 않으면, 닿을 수 있는 것이 둘을 가르지 않으며 정직한
다음 수는 설정을 바꾸기 시작하는 것이 아니라 이슈 트래커에서
묻는 것입니다.
* **산문만 더, 여전히 호출 없음** — 단호히 물어보세요: *"도구를 호출했어? 안 했다면,
왜?"* 두 번 피하는 에이전트는 보통 말하지 않은 무언가를
우회하고 있습니다.
### 여기서 볼 수 있는 것과 볼 수 없는 것
클라이언트가 도구 호출을 거절하면, 그 호출은 클라이언트를 떠나지 않습니다. 아무것도
이 서버에 닿지 않으므로, 로그에 아무것도 나타나지 않고 우리가 닿을 수 있는
어디에도 오류가 생기지 않습니다. 차단을 감지할 수 없고, 하는 척하지 않습니다: "클라이언트가
이것을 차단했다"고 말하는 어떤 페이지나 메시지도 추측일 것입니다.
같은 사실이 반대 방향으로 자르며, 그것이 사람을 오도하는 부분입니다: 조용한 로그는 아무것도 시도되지 않았다는 증거가 아닙니다. 없음, 차단됨, 요청되지 않음은 모두 여기서 침묵처럼 보입니다.
그래서 위의 두 질문이 진짜 진단입니다. 동작하는 이유는 *방에 있었던* 한 참가자 — 당신의 에이전트 — 에게 무엇을 시도했는지 말하고, 답을 돌아갈 선택지를 주지 않기 때문입니다.
### 각 답이 보통 어디서 오는지
**차단됨 — 클라이언트 자체의 권한 규칙.** Claude Code에서는 `settings.json`의 `permissions` 블록입니다 (`~/.claude/settings.json`, 또는 프로젝트의 `.claude/settings.json`). MCP 도구는 네임스페이스된 이름 `mcp__comfyui__`로 나타납니다. 그것들을 한 번도 언급하지 않는 엄격한 `allow` 목록이 보내기 전에 모든 호출을 막습니다. 이것이 한 사용자에게 며칠을 쓰게 한 경우입니다: 도구가 동작하는 것처럼 보였습니다. 그가 찾던 오류가 나타날 수 없었기 때문입니다.
**없음, 고칠 수 있음 — 한 번도 연결되지 않음.** 클라이언트는 MCP를 말하지만 이 서버에 대해 들은 적이 없거나, 들었는데 항목이 틀렸습니다. 이것이 흔한 것이고 설정 편집입니다. 클라이언트가 기대하는 항목은 [빠른 시작](/docs/docs/ko/quickstart)을 참고하세요.
**없음, 고칠 수 없음 — MCP 클라이언트가 전혀 없는 호스트.** 어떤 에이전트는 MCP를 말하지 않으며, 설정을 아무리 해도 바뀌지 않습니다. `pi`가 하나입니다: 자체 내장 셸-과-에디터 도구가 있고 MCP 클라이언트가 없으므로, 무엇이 설치되어 있든 우리의 것을 건넬 수 없습니다. 패널은 고를 때 분명히 말합니다 — *"pi에는 ComfyUI 도구가 없습니다(MCP 없음)"*. 그 줄이 답이지, 디버그할 증상이 아닙니다. 수정은 다른 백엔드를 고르는 것입니다.
**어느 쪽이든 — 사이에 앉은 무언가.** MCP 트래픽을 나르는 게이트웨이, 프록시, 또는 라우터가 표면의 일부만 전달할 수 있습니다. 카탈로그와 실제로 실행되는 것이 서로 어긋나면, 중간을 의심하세요.
### 세 번째 경우로 밝혀졌다면
그러면 아무것도 깨지지 않았고 아무도 잘못 설정하지 않았습니다: 능력이 있었고 알아낼 방법이 없었습니다. 그것은 당신의 실패가 아니라 우리의 실패이며, 말해 줄 가치가 있습니다 — 에이전트에게 접수하라고 하면 설정을 대신 붙입니다. 아무도 찾을 수 없는 기능은, 앉아 있는 곳에서는, 출시하지 않은 기능입니다.
## 작은 로컬 모델을 쓰는 경우
메뉴 전체를 모델에 건네는 것은 한 마디 하기 전에 많은 읽기를 듭니다. 큰 호스팅 모델에서는 괜찮습니다. 자신의 머신에서 도는 작은 모델에서는 종종 동작과 미동작의 차이입니다.
그래서 기본적으로 에이전트는 전체 집합 대신 **세** 도구를 받습니다: 카탈로그를 둘러보는 것, 도구 하나를 자세히 조회하는 것, 실행하는 것. 필요할 때 필요한 것을 가져오며, 앞에서 모든 것을 읽지 않습니다.
이것을 얻기 위해 아무것도 할 필요가 없습니다 — 기본값입니다. 원하면 제어가 있습니다:
```bash theme={null}
# force the small three-tool mode
npx -y comfyui-mcp --compact
# or hand the model everything at once
npx -y comfyui-mcp --full
```
어느 쪽이든 `COMFYUI_MCP_TOOL_MODE=compact` 또는 `COMFYUI_MCP_TOOL_MODE=full`로도 설정할 수 있습니다.
거래는 첫 실제 동작 전에 왕복 몇 번 더, 생각할 자리가 남은 모델입니다. 큰 모델은 보통 `--full`에 더 행복합니다. 어느 모델이 어느 것을 견디는지는 [로컬 LLM](/docs/docs/ko/local-llms)을 참고하세요.
## 다음으로 갈 곳
설치하고 첫 이미지를 생성하세요.
ComfyUI 속 에이전트, 그리고 캔버스에 할 수 있는 일.
모든 도구, 실제 호출이 어떻게 보이는지의 작업 예제와 함께.
거절이 아니고 무언가가 실제로 깨졌을 때.