KwaFlux MCP가 안 될 때: 도구 누락, app_not_running, 타임아웃 해결법

도구가 안 보이거나, 모든 호출이 app_not_running을 반환하거나, 대기가 타임아웃되거나, 작업이 거부될 때 KwaFlux MCP 증상별 의미와 해결 방법을 정리했습니다.

글 Alex Davis · KwaFlux 편집팀 검토2026년 10월 27일8분

핵심 요약

바깥쪽부터 차례로 확인하세요. 호스트가 서버를 실행했는지, 서버가 앱에 닿았는지, 앱이 작업을 받아들였는지 순서입니다.
KwaFlux 도구가 하나도 보이지 않는다면 원인은 거의 대부분 호스트 구성입니다. JSON이나 YAML이 유효하지 않거나, 파일을 잘못 골랐거나, Node.js를 찾지 못했거나, 다시 불러오지 않은 경우입니다.
app_not_running은 서버는 정상인데 KwaFlux가 열려 있지 않다(또는 같은 컴퓨터에 없다)는 뜻입니다.
1분쯤 지나 실패하는 긴 대기는 작업 실패가 아니라 호스트 타임아웃입니다. 작업은 KwaFlux에서 계속 실행됩니다.

KwaFlux의 MCP 연결이 동작하지 않을 때는 증상을 보면 어느 계층을 살펴야 할지 알 수 있습니다. 호스트가 서버를 실행하지 못했거나, 서버가 앱에 닿지 못했거나, 앱이 요청을 거부한 경우입니다. 각 경우마다 원인은 몇 가지로 좁혀지고, 원인마다 정확한 해결 방법이 있습니다.

이 글에서는 세 계층을 구분하는 방법, 계층별 해결 방법, KwaFlux가 반환하는 오류 메시지, 그리고 AI 호스트 없이 2분 만에 해 볼 수 있는 점검 방법을 알아봅니다.

계층별로 무엇이 잘못될 수 있나
1계층: 호스트에 KwaFlux 도구가 없음
2계층: 도구는 보이지만 호출이 app_not_running으로 실패함
3계층: 앱이 작업을 거부함
대기가 타임아웃될 때
작업이 실패하거나 결과물이 없을 때
AI 호스트 없이 점검하기
빠른 참고표
자주 묻는 질문

계층별로 무엇이 잘못될 수 있나

요청은 세 부분을 거칩니다.

호스트(Cursor, Claude, Codex, DeepSeek Harness, Hermes, OpenClaw)가 구성을 읽고 KwaFlux의 MCP 서버를 실행합니다.
MCP 서버(Windows에서는 Node.js 스크립트, Mac에서는 앱 안의 헬퍼)가 실행 중인 KwaFlux 앱에 연결합니다.
KwaFlux가 요청을 확인하고 작업을 대기열에 넣습니다.

보이는 증상	계층	참고할 곳
KwaFlux 도구가 하나도 없음	호스트 구성	1계층
도구는 보이지만 모든 호출이 `app_not_running`을 반환	서버와 앱 사이	2계층
일부 호출은 되지만 작업이 거부됨	앱의 확인 단계	3계층
1분쯤 지나면 대기가 실패함	호스트 타임아웃	대기 타임아웃
작업이 실행되지만 실패하거나 파일이 남지 않음	작업	작업 실패

1계층: 호스트에 KwaFlux 도구가 없음

1. 구성 파일이 유효하지 않습니다. 오류 하나 때문에 호스트가 그 파일의 서버를 모두 버릴 수 있습니다.

JSON(Cursor, Claude, OpenClaw): Windows 경로에는 백슬래시를 두 개씩 써야 합니다(C:\\Program Files\\...). 주석과 끝에 붙는 쉼표는 쓸 수 없습니다.
TOML(Codex): KwaFlux 코드 조각처럼 Windows 경로를 작은따옴표로 감싸거나, 백슬래시를 모두 두 개씩 쓰세요.
YAML(DeepSeek Harness, Hermes): 코드 조각의 들여쓰기를 그대로 지키세요. 작은따옴표 안의 백슬래시는 그대로 유지됩니다.

2. 파일이나 범위가 잘못되었습니다.

호스트	흔한 실수	올바른 위치
Cursor	한 프로젝트의 `.cursor/mcp.json`에 추가함	`~/.cursor/mcp.json`
Claude Code	다른 폴더에서 기본값인 local 범위로 추가함	`claude mcp add --scope user ...`
Codex	키를 `mcpServers`나 `mcp-servers`로 적음	`~/.codex/config.toml`의 `[mcp_servers.kwaflux]`
DeepSeek Harness	실행하지 않는 프로필에 행을 넣음	홈 패치 `~/.dsh/cordis.patch.yml`
Hermes	`mcp:` › `servers:`로 중첩함	`~/.hermes/config.yaml`의 맨 바깥쪽 키 `mcp_servers:`
OpenClaw	`mcpServers` 아래에 적음	`~/.openclaw/openclaw.json`의 `mcp.servers`

3. Node.js를 찾지 못했습니다. Windows에서는 호스트가 Node.js 18 이상으로 서버를 실행합니다. KwaFlux 설정 카드는 Node.js를 찾아서 그 전체 경로를 구성에 적어 줍니다. 카드에 "Node.js를 찾을 수 없습니다. 호스트는 Node.js 18 이상으로 이 서버를 실행합니다. 먼저 설치하세요."라고 나오거나 버전이 "너무 오래되었습니다"라고 나오면, 현재 LTS 릴리스를 설치하고 Node.js 다시 확인을 클릭한 뒤 구성을 다시 복사하세요. 구성을 직접 쓰면서 그냥 "node"라고 적었다면 C:\Program Files\nodejs\node.exe처럼 전체 경로로 바꾸거나, 호스트를 다시 시작해 새 PATH를 읽게 하세요.

4. 서버 경로가 틀렸습니다. 스크립트는 KwaFlux 설치 폴더 안 Tools\kwaflux-mcp에 있는 kwaflux_mcp.mjs입니다. KwaFlux를 C:\Program Files\KwaFlux가 아닌 다른 곳에 설치했다면, 실제 경로를 채워 주는 KwaFlux 설정 › Agent(MCP) 카드에서 코드 조각을 복사하세요. 카드에 "함께 배포된 MCP 서버를 찾지 못했습니다. 아래 경로는 자리표시자입니다."라는 경고가 나오면 KwaFlux를 다시 설치하세요.

5. 호스트를 다시 불러오지 않았습니다. 호스트마다 방법이 다릅니다.

호스트	다시 불러오는 방법
Cursor	Customize에서 서버를 껐다 켜거나 Cursor를 다시 시작
Claude Code	새 세션을 시작하고 `/mcp`로 확인
Claude Desktop	트레이 아이콘까지 포함해 끝까지 종료한 뒤 다시 열기
Codex	다시 시작하거나 `/mcp` 실행
DeepSeek Harness	저장하면 핫 리로드됨. 안 되면 세션을 다시 시작
Hermes	`/reload-mcp`
OpenClaw	MCP 서버를 다시 불러오거나 게이트웨이를 다시 시작

호스트별 안내: Cursor, Claude Code와 Claude Desktop, Codex, DeepSeek Harness, Hermes와 OpenClaw.

2계층: 도구는 보이지만 호출이 app_not_running으로 실패함

가장 쉽게 해결되는 경우입니다. Windows에서 전체 메시지는 다음과 같습니다.

app_not_running: Error: app_not_running: no control file of a running KwaFlux in C:\Users\<you>\AppData\Local\KwaFlux\agent

서버는 제대로 시작했지만 통신할 실행 중인 KwaFlux를 찾지 못했다는 뜻입니다. 해결 방법은 다음과 같습니다.

KwaFlux를 여세요. 창이 뜰 때까지 기다린 뒤 다시 요청하면 됩니다. 호스트를 다시 불러올 필요는 없습니다.
같은 컴퓨터, 같은 사용자여야 합니다. 서버는 같은 컴퓨터에서 같은 Windows 또는 macOS 계정으로 실행 중인 KwaFlux에만 닿을 수 있습니다. VPS에 있는 에이전트, Cursor Cloud Agent, 다른 사용자 계정의 세션은 닿지 못합니다.

3계층: 앱이 작업을 거부함

KwaFlux가 요청을 거부하면 도구 결과에 그 이유가 나옵니다. 자주 보이는 것은 다음과 같습니다.

사유	의미	해결
`not_signed_in`	파일을 쓰는 작업인데 로그인하지 않음	KwaFlux에 로그인한 뒤 어시스턴트에게 다시 시도해 달라고 요청
`entitlement_denied`	계정의 플랜이 이 작업을 포함하지 않음	이 글 끝의 플랜 안내 참고
`agent_download_disabled`	에이전트 다운로드가 꺼져 있음	에이전트 권한의 에이전트의 다운로드 허용을 매번 확인으로 바꾸거나, 앱에서 직접 다운로드
`user_declined` / `approval_expired`	거부를 클릭했거나 승인 팝업을 닫았거나, 2분 안에 아무도 응답하지 않음	고칠 것은 없음. 정말 다운로드하려면 다시 요청
`agent_control_disabled`	전체 스위치가 꺼져 있음	에이전트 권한에서 AI 에이전트의 KwaFlux 제어 허용을 켜기
경로 거부	네트워크/UNC 경로, 상대 경로, 오타	`D:\Videos\clip.mp4`처럼 로컬 전체 경로를 입력
속도 제한(`app_busy`)	짧은 시간에 새 작업이 너무 많음	어시스턴트에게 하나씩 대기열에 넣어 달라고 요청

\\server\share\clip.mp4 같은 네트워크 경로는 파일을 열기도 전에 일부러 거부합니다. 먼저 파일을 로컬 드라이브로 복사하세요. 이유는 경로와 개인정보 규칙을 참고하세요.

대기가 타임아웃될 때

KwaFlux의 대기 도구는 호출 한 번에 최대 300초, 기본 60초까지 기다립니다. 일부 호스트는 MCP 호출 하나에 그보다 짧은 시간을 줍니다.

호스트	설정	권장값
Codex	`tool_timeout_sec`(기본값 60)	330
DeepSeek Harness	`toolCallTimeoutMs`(제3자 가이드 기준 60,000)	330000
Claude Code	`.mcp.json` 항목의 `timeout`, 밀리초 단위	330000
Hermes	서버 항목의 `timeout`	300초보다 크게

대기가 타임아웃되어도 작업은 멈추지 않습니다. KwaFlux 작업 목록에서 계속 실행되며, 어시스턴트는 다시 기다리거나 상태를 확인할 수 있습니다.

작업이 실패하거나 결과물이 없을 때

작업의 오류 사유를 확인하세요. 어시스턴트에게 "KwaFlux 작업을 가져와서 오류 내용을 알려 주세요."라고 요청하세요. 작업 세부 정보에 사유가 들어 있습니다.
결과물이 어디에 저장됐는지 확인하세요. 결과는 어시스턴트가 지정한 폴더가 아니라 입력 파일 옆에 저장되고, 같은 이름의 파일이 이미 있으면 기존 파일은 그대로 두고 새 파일 이름을 name(1).ext로 바꿉니다. 변환한 파일 이름은 _kwaflux_<format>-<tier>로, 복구한 파일 이름은 _repair로 끝납니다.
복구에는 참조 파일이 필요할 수 있습니다. 진단 결과 참조 파일이 필요하다고 나오면 같은 카메라로 찍은 정상 클립을 주세요. 파일 복구를 참고하세요.
채팅으로는 쓸 수 없는 기능. 프레임 보간과 매팅, 교체 도구는 MCP로 제공되지 않습니다. 앱에서 직접 하세요.
그래도 실패한다면? KwaFlux 창에서 직접 한 번 다시 시도해 보세요. 거기서도 실패한다면 MCP 문제가 아니므로, 작업의 오류 사유를 지원팀에 보내 주세요.

AI 호스트 없이 점검하기

서버가 아예 시작될 수 있는지 모르겠다면 터미널에서 직접 실행해 보세요.

node "C:\Program Files\KwaFlux\Tools\kwaflux-mcp\kwaflux_mcp.mjs"

정상인 서버는 아무것도 출력하지 않고 입력을 기다립니다. 호스트가 말을 걸어 오기를 기다리는 상태이기 때문입니다. Ctrl+C로 멈추세요. 대신 "not recognized"(한국어 Windows 명령 프롬프트에서는 "내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다", Node.js가 PATH에 없음)나 "Cannot find module"(경로가 틀림) 같은 오류가 나온다면 그것부터 고치세요. 그대로는 어떤 호스트에서도 결과가 나아지지 않습니다.

빠른 참고표

증상	가능성이 큰 해결 방법
도구 없음, JSON 호스트	백슬래시를 두 개씩 쓰고 파일 유효성 검사
도구 없음, Claude Code	`--scope user`로 다시 추가
도구 없음, DeepSeek Harness	행을 `~/.dsh/cordis.patch.yml`에 넣기
서버가 시작되지 않음	현재 Node.js LTS를 설치하고 호스트를 다시 시작
`app_not_running`	같은 컴퓨터에서 KwaFlux 열기
`not_signed_in`	KwaFlux에 로그인
`agent_download_disabled`	에이전트 다운로드를 매번 확인으로 바꾸거나, 앱에서 직접 다운로드
`agent_control_disabled`	전체 스위치를 다시 켜기
1분쯤 지나면 대기가 실패함	호스트의 도구 타임아웃 늘리기
파일이 예상한 곳에 없음	원본 파일 옆을 확인

마치며

먼저 계층을 찾으세요. 도구가 없으면 호스트 구성 문제, app_not_running은 이 컴퓨터에서 앱이 열려 있지 않다는 뜻, 거부는 이유가 함께 나오고, 1분 만의 실패는 호스트 타임아웃입니다. 확신이 서지 않으면 서버를 직접 실행해 보세요. 조용히 입력을 기다린다면 문제는 서버가 아니라 호스트나 앱에 있습니다.

내 어시스턴트와 KwaFlux를 연결해 보세요

KwaFlux에는 Cursor, Claude, Codex, DeepSeek Harness, Hermes, OpenClaw를 비롯한 MCP 앱에서 쓸 수 있는 로컬 MCP 서버가 들어 있습니다. AI 처리는 사용자 GPU에서 실행되며 미디어 파일이 처리를 위해 업로드되지 않습니다. Windows 10(64비트, 버전 1809 이상), Windows 11, Apple Silicon 탑재 macOS 12 이상에서 실행됩니다. 파일 가져오기와 앱 둘러보기에는 계정이 필요 없습니다. 내보내기, 변환, 파일 복구, 링크에서 파일 다운로드에만 로그인과 유료 플랜이 필요합니다.

KwaFlux 받기 · 플랜 보기

내 실제 영상으로 효과를 확인하세요

KwaFlux를 받고 결제 전에 내 영상으로 효과를 무료로 미리 보세요. 계정이 필요 없고, 내 GPU에서 처리하며 처리를 위해 미디어를 업로드하지 않습니다. 영상 미리보기는 1, 3 또는 5초, 흔들림 보정 미리보기는 5, 15 또는 30초 중에서 고를 수 있습니다.

KwaFlux 무료 미리보기 기능 둘러보기

자주 묻는 질문

MCP 도구가 안 보이는 이유는 뭔가요?

대개는 호스트가 구성을 읽지 못했거나 서버를 실행하지 못했기 때문입니다. JSON, YAML, TOML이 유효한지, 파일과 범위가 맞는지, Node.js가 PATH에 있는지, 다시 불러왔는지 확인하세요. 문법 오류 하나 때문에 그 파일의 서버가 모두 안 보일 수 있습니다.

MCP 서버가 "node is not recognized"("내부 또는 외부 명령… 배치 파일이 아닙니다") 오류로 실패하는 이유는 뭔가요?

Node.js가 설치되어 있지 않거나, 호스트가 보는 PATH에 없기 때문입니다. 설치한 다음 호스트를 종료했다가 다시 시작하세요. 그래도 안 되면 서버의 command에 node.exe의 전체 경로를 넣으세요.

app_not_running은 무슨 뜻인가요?

MCP 서버는 시작했지만 연결할 실행 중인 앱을 찾지 못했다는 뜻입니다. 같은 컴퓨터에서 같은 사용자 계정으로 앱을 연 뒤 다시 시도하세요. 호스트를 다시 불러올 필요는 없습니다. 설정 방법은 Cursor 가이드를 참고하세요.

MCP 도구 호출이 오래 걸리면 타임아웃되는 이유는 뭔가요?

많은 호스트가 도구 호출 한 번을 기본 60초 안팎으로 제한하는데, 일부 도구는 그보다 오래 기다리도록 설계되어 있기 때문입니다. 호스트의 서버별 도구 타임아웃을 늘리세요. 실제 작업은 대개 계속 실행됩니다.

MCP 서버로 네트워크 드라이브의 파일을 쓸 수 있나요?

서버에 따라 다릅니다. 네트워크 경로를 일부러 거부하는 서버도 있습니다. 그런 경로를 열면 Windows가 그 서버에 자동으로 로그인을 시도할 수 있기 때문입니다. 먼저 파일을 로컬 드라이브로 복사하세요.

참고 자료

Model Context Protocol, "Transports" (2026-07-28; stdio over the standard streams of a client-launched subprocess) (2026-10-26 확인)
OpenAI, Codex documentation, MCP page (tool_timeout_sec default 60) (2026-10-26 확인)
Claude Code Docs, MCP page (scopes; per-server timeout) (2026-10-26 확인)
ZensInk, "DeepSeek Harness (DSH): A Hands-On Setup Guide with MCP Integration" (toolCallTimeoutMs default) (2026-10-26 확인)
Microsoft Security Response Center, "Microsoft Mitigates Outlook Elevation of Privilege Vulnerability" (UNC paths and automatic NTLM sign-in) (2026-10-25 확인)

튜토리얼
MCP

Alex Davis

KwaFlux 작성자 겸 편집자. 글은 KwaFlux 편집팀이 검토하며, 제품 조사 노트와 공개된 사양을 바탕으로 합니다.