DeepSeek에서 KwaFlux 쓰는 법: MCP로 DeepSeek Harness(DSH) 연결하기

핵심 요약

• DeepSeek Harness(DSH)는 cordis.patch.yml 파일에 넣는 insert 행 하나로 KwaFlux에 연결됩니다. 이 행은 KwaFlux가 만들어 줍니다.
• 실제로 실행하는 DSH가 읽는 위치에 넣으세요. 홈 패치 ~/.dsh/cordis.patch.yml은 모든 프로필에 적용되고, 프로필 자체 파일은 그 프로필에만 적용됩니다.
• DSH는 패치 파일을 핫 리로드하므로 보통은 다시 시작하지 않아도 도구가 나타납니다.
• DeepSeek가 긴 영상 작업을 기다리다 중간에 끊기지 않도록 호출별 도구 타임아웃을 늘리세요.

DeepSeek의 에이전트는 KwaFlux와 함께 설치되는 로컬 MCP 서버를 통해 KwaFlux를 움직일 수 있습니다. DeepSeek Harness(DSH)는 cordis.patch.yml이라는 계층형 구성 파일에서 MCP 서버를 플러그인 행으로 불러옵니다. KwaFlux에서 MCP 호스트로 DeepSeek를 고르고 행을 복사한 뒤, 사용하는 DSH 프로필이 읽는 패치 파일 끝에 붙여 넣으면 됩니다.

이 글에서는 행을 어디에 넣는지, 프로필이 왜 중요한지, 어떤 타임아웃을 늘려야 하는지, 그리고 DeepSeek에게 처음에 무엇을 요청할지 알아봅니다.

목차

1. DSH가 MCP 서버를 불러오는 방식
2. 시작하기 전에
3. 1단계. KwaFlux에서 행 복사하기
4. 2단계. 알맞은 패치 파일 고르기
5. 3단계. 행 추가하기
6. 4단계. 불러왔는지 확인하기
7. 첫 요청 해 보기
8. 문제 해결
9. 자주 묻는 질문

DSH가 MCP 서버를 불러오는 방식

DeepSeek Harness는 여러 겹의 패치 파일로 구성을 만듭니다. 프로필마다 자체 cordis.patch.yml이 있고, 홈 수준의 $DSH_HOME/cordis.patch.yml은 CLI 레퍼런스의 표현으로 "모든 프로필이 공유하는 머신 로컬 설정이므로 프로필별 계층보다 우선"합니다.

MCP 서버는 DSH의 MCP 클라이언트 플러그인 @deepseek-ai/dsh-mcp-client를 쓰는 행입니다. DSH는 기본으로 켜 둔 서버가 하나도 없습니다. 레퍼런스는 그 이유를 "각 서버 명령은 에이전트 샌드박스 밖에서 실행되는 신뢰된 실행 코드"이기 때문이라고 설명합니다. KwaFlux를 추가한다는 것은 KwaFlux 서버를 신뢰하겠다고 직접 선택하는 일입니다.

시작하기 전에

• KwaFlux 1.0.14 이상, 실행 중.
• PATH에 있는 Node.js 18 이상. node --version으로 확인하세요. KwaFlux 설정 카드도 Node.js를 찾아서 아래 예시처럼 그 전체 경로를 구성에 적어 줍니다. Node.js를 찾지 못하면 그렇다고 알려 주고 대신 node라고 적습니다.
• DeepSeek Harness 설치. DSH 문서에는 Preview 표시가 붙어 있으므로 릴리스마다 경로와 명령이 바뀔 수 있습니다.

1단계. KwaFlux에서 행 복사하기

KwaFlux에서 설정 › Agent(MCP)를 열고 MCP 호스트에서 DeepSeek를 고른 다음 구성 복사를 클릭합니다. Windows 기본 설치라면 행은 다음과 같습니다.

- insert:
    - id: mcp-kwaflux
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: kwaflux
        transport: stdio
        command: 'C:\Program Files\nodejs\node.exe'
        args: ['C:\Program Files\KwaFlux\Tools\kwaflux-mcp\kwaflux_mcp.mjs']

참고: 경로는 작은따옴표로 감싸져 있습니다. YAML에서 작은따옴표 문자열은 백슬래시를 그대로 유지하므로 Windows 경로를 이스케이프할 필요가 없습니다.

2단계. 알맞은 패치 파일 고르기

KwaFlux 안내 문구는 파일 하나를 지목합니다. "~/.dsh/profiles/web/cordis.patch.yml에 이 insert 플러그인 행을 추가한 뒤 DSH 세션을 다시 시작하세요." DSH의 web 프로필, 즉 dsh web을 쓴다면 이대로 하면 됩니다. 다른 방식으로 실행한다면 그에 맞게 고르세요.

Windows에서 ~는 C:\Users\<you>입니다. DSH_HOME을 설정해 두었다면 ~/.dsh 대신 그 폴더를 쓰세요.

DSH에서 KwaFlux가 "안 보이는" 가장 흔한 이유는 실행하지 않는 프로필에 행을 넣었기 때문입니다.

3단계. 행 추가하기

1. 먼저 파일을 백업합니다.
2. 패치 파일은 YAML 목록입니다. 다른 맨 바깥쪽 - insert:나 - replace: 항목과 같은 들여쓰기로 맨 끝에 KwaFlux 행을 추가합니다.
3. 파일이 아직 없다면 KwaFlux 행 하나만 넣어 새로 만듭니다.
4. 필요하면 config: 안에서 도구 타임아웃을 늘립니다.

- insert:
    - id: mcp-kwaflux
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: kwaflux
        transport: stdio
        command: 'C:\Program Files\nodejs\node.exe'
        args: ['C:\Program Files\KwaFlux\Tools\kwaflux-mcp\kwaflux_mcp.mjs']
        toolCallTimeoutMs: 330000

제3자 설정 가이드에 따르면 DSH의 호출별 기본 타임아웃은 60초입니다. KwaFlux의 대기 도구는 호출 한 번에 최대 300초까지 기다릴 수 있으므로 330,000밀리초로 잡으면 여유가 있습니다. 사용하는 DSH 버전이 이 필드를 받아들이지 않으면 지우세요. 대기가 중간에 끊겨도 DeepSeek는 다시 기다리면 됩니다.

4단계. 불러왔는지 확인하기

DSH는 패치 파일을 감시하다가 유효한 편집을 핫 리로드로 적용하므로, 보통은 저장하고 몇 초 안에 서버가 시작됩니다. 아무 변화가 없다면 KwaFlux 안내 문구대로 DSH 세션을 다시 시작하세요.

그다음 이렇게 요청해 봅니다.

KwaFlux 도구로 KwaFlux가 실행 중인지 확인해 주세요.

DSH에서 KwaFlux 도구는 mcp__kwaflux__kwaflux_get_app_status처럼 mcp__kwaflux__<tool> 형태의 이름으로 표시됩니다. KwaFlux가 닫혀 있으면 도구가 app_not_running으로 시작하는 오류를 반환합니다.

첫 요청 해 보기

프레임 보간과 매팅, 교체 도구는 앱에 남아 있으며, 이런 요청이 오면 어시스턴트는 사용자를 앱으로 안내하라는 응답을 받습니다. 에이전트 다운로드는 에이전트 권한의 에이전트의 다운로드 허용을 매번 확인으로 바꾸지 않는 한 꺼져 있습니다. 이렇게 설정하면 KwaFlux가 다운로드마다 팝업을 띄우고, 어시스턴트도 그 콘텐츠를 내려받을 권리가 있는지 채팅에서 확인을 요청합니다.

문제 해결

모든 호스트에 공통된 문제는 KwaFlux MCP 문제 해결 가이드를 참고하세요.

마치며

KwaFlux에서 행을 복사하고, 실제로 실행하는 DSH가 읽는 패치 파일에 넣은 다음, 영상 작업에 맞게 도구 타임아웃을 늘리세요. 저장하면 DSH가 다시 불러옵니다. 그런 다음 KwaFlux를 열어 두고, 첫 실제 작업 전에 DeepSeek에게 앱 상태부터 확인해 달라고 요청하세요.

DeepSeek로 KwaFlux를 움직여 보세요

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

KwaFlux 받기 · 플랜 보기