174개의 도구, 19개의 네임스페이스. 하나의 레지스트리. 모든 AI 에이전트가 Dify 워크플로우를 자율적으로 구축, 테스트 및 배포할 수 있도록 합니다 — 사용자가 UI에서 할 수 있는 모든 것이 이제 스크립팅 가능해집니다.

24개의 인기 AI 에이전트와 함께 작동합니다 — Claude Code, Codex, Gemini CLI, Cursor, Cline, Windsurf, Roo Code, Continue, Zed, Aider, OpenCode, Antigravity, GitHub Copilot, Goose, Trae, Kilo Code, Warp, Crush, Droid, Amp, OpenHands, Cody, Augment, 그리고 Amazon Q Developer — 뿐만 아니라 다른 모든 MCP 호환 또는 셸 기능을 갖춘 에이전트와도 작동합니다.

Dify는 강력한 오픈 소스 LLM 앱 플랫폼이지만, 그 워크플로우 빌더는 시각적인 드래그 앤 드롭 편집기입니다. 만약 AI 에이전트가 브라우저 없이 프로그래밍 방식으로 워크플로우를 생성하고, 노드를 연결하며, 테스트하고, 반복하고, 게시하기를 원한다면 어떨까요?

dify-mcp가 바로 그 다리(bridge)입니다. 이는 Dify 콘솔 API 전체를 통합된 도구 레지스트리로 노출하며, 두 가지 인터페이스를 제공합니다: 모든 셸 기능을 갖춘 에이전트가 구동할 수 있는 CLI와, 모든 MCP 호환 호스트가 연결할 수 있는 MCP 서버(stdio 또는 Streamable HTTP)입니다. 동일한 174개 도구, 동일한 JSON 계약, 동일한 안전 보장을 유지합니다.

┌──────────────────────────────────────────────────────────┐
│ dify-mcp │
│ │
...

dify-mcp는 설계상 에이전트와 무관(agent-agnostic)합니다 — SDK 종속성이나 독점 프로토콜이 없습니다. 만약 사용자의 에이전트가 셸 명령을 실행할 수 있다면, CLI를 사용할 수 있습니다. MCP를 지원한다면, 서버에 연결할 수 있습니다. 대부분의 인기 에이전트는 둘 다 지원합니다:

사용자의 에이전트가 보이지 않나요? MCP를 지원하거나 셸 명령을 실행할 수만 있다면 작동합니다. 아래의 연결 섹션에는 각 호스트에 대한 복사-붙여넣기 설정이 있습니다.

• 완벽한 커버리지. 단순히 하위 집합이거나 공개 API를 감싸는 래퍼가 아닙니다. 이는 Dify 웹 UI가 사용하는 것과 동일한 인터페이스인 내부 콘솔 API와 통신합니다. 앱 생성, 노드별 그래프 작성, 유효성 검사, 테스트 실행, 게시, 버전 관리, 트리거, 제공업체(providers), 플러그인, RAG 파이프라인, 스니펫, 에이전트 설정, 댓글, 주석, 오디오, 통계까지 모두 다룹니다. UI가 할 수 있다면, 여러분의 에이전트도 할 수 있습니다.
• 설계상 에이전트에 구애받지 않음(Agent-agnostic). SDK 종속성이 없습니다. CLI는 셸 명령을 실행할 수 있는 모든 에이전트와 작동합니다. MCP 서버는 모든 MCP 호스트와 작동합니다. 둘 다 구조화된 JSON({ ok, data } 또는 { ok: false, error: { code, message, retryable } })을 반환하므로, 에이전트는 절대 사람이 읽기 쉬운 텍스트를 스크래핑하지 않습니다. 대용량 초안 및 내보내기의 경우, CLI의 --output-file <경로> 옵션은 크기 제한이 있는 표준 출력(stdout) 전송 채널에서 전체 UTF-8 결과를 유지합니다.
• 쿠키 인증 처리 완료. Dify 콘솔은 Bearer 토큰이 아닌 쿠키 + CSRF 더블 서밋 방식을 사용합니다. dify-mcp는 세션을 캡처하고 저장하며(macOS의 경우 키체인, 아니면 0600 파일), 서버 측 리프레시 토큰 회전까지 자동 새로고침합니다. 이 동일한 세션은 이제 초안및게시된 실행/중지, 파일 업로드, 의존성 확인, 워크스페이스 전환을 포괄합니다. MCP 호스트는 CLI 없이도 auth.import_cookies 또는 auth.login_console를 호출할 수 있습니다. --DIFY_CONSOLE_COOKIE와 --console-cookie가 비대화형 부트스트랩에 작동합니다.
• 기본적으로 안전함(Safe by default). 파괴적인 작업에는 명시적인 confirm=true 또는 --yes가 필요합니다. 그래프는 동기화 전에 오프라인으로 유효성 검사됩니다(반복/루프 서브그래프, 스티키 노트, 최신 다중 케이스 if-else 포함). 모든 변경 사항은 감사 로그로 기록됩니다. --dry-run은 저장하지 않고 차이점(diffs)을 보여줍니다.
• 빌드 단계 없음(Zero build step). Node 23.6+의 네이티브 TypeScript에서 직접 실행됩니다. 컴파일러, 번들러, 트랜스파일러가 필요 없습니다. 클론하고, 설치하고, 바로 사용합니다.

클래식 지식 기반(Dataset CRUD, knowledge.*로부터 문서 생성).`file.upload

ids (또는 전체 KnowledgeConfig), 이름 변경/삭제, 인덱싱 상태, 히트 테스트(hit-testing), 세그먼트 추가/업데이트/삭제 — 파괴적 작업 시 confirm-gated.워크스페이스 멤버 관리자(Workspace member admin).workspace.invite_members, workspace.update_member_role, 그리고 workspace.remove_member(confirm-gated).

MCP 진행 알림(MCP progress notifications). 긴 SSE 실행(workflow.run_draft, 채팅 등) 시, 호스트가 tools/call의 _meta에 progressToken을 제공하면 notifications/progress를 방출합니다.

로컬 백업 및 마이그레이션(Local backup and migration). app.backup은 벌크 내보내기 DSL과 매니페스트를 포함하며, app.restore는 다른 설정된 Dify 인스턴스로의 건식 실행 충돌 및 가져오기를 수행합니다.

명시적 호환성 매트릭스(Explicit compatibility matrix). Dify 1.17.x와 1.16.x가 지원되며, 이전 버전은 의도적으로 지원하지 않습니다.

쿠키 기반 작성 환경(Cookie-complete authoring). 동일한 콘솔 세션에서 실행, 중지, 업로드, 종속성 확인 및 워크스페이스 전환이 가능합니다. MCP 호스트는 CLI로 떨어지지 않고 인증됩니다.

더 안전해진 HTTP MCP(Safer HTTP MCP). 기본적으로 127.0.0.1에 바인딩됩니다. 0.0.0.0 바인딩(Docker)은 DIFYWF_MCP_TOKEN을 필요로 합니다. 호스트 허용 목록 및 2MB 본문 제한이 있으며, /health는 프로브를 위해 열려 있습니다.

워크플로우 기반 도구 제공자(Workflow-as-tool providers). 버전을 배포한 후에는 게시된 도구 바인딩을 가져오거나, 새로 고치거나, 삭제할 수 있습니다 (workflow.tool_get, /workflow.tool_refresh_provider, /workflow.tool_delete).

검증된 앱 태그(Verified app tags). app.ensure_tag 또는 app.remove_tag를 통해 정확한 태그 이름을 바인딩하거나 언바인딩하고 다시 읽어올 수 있습니다. Confirm-gated입니다.

더 스마트해진 그래프 유효성 검사(Smarter graph validation). 반복/루프 내부 노드, 캔버스 custom-note 스티커, 그리고 최신 cases[] if-else 분기가 더 이상 오프라인 확인에서 실패하지 않습니다.

대용량 페이로드(Large payloads). OS 인자 제한을 초과하는 DSL의 경우 --yaml @file을 사용하고, --output-file은 크기 제한이 있는 stdout에 큰 결과를 남겨둡니다.

시작 그래프(Starter graphs). examples/에 준비된 템플릿(echo, LLM, RAG)이 있습니다. sync_draft는 더 이상 생략된 환경 변수/대화 비밀 정보를 지우지 않습니다.

작성 루프가 콘솔 쿠키 인증을 통해 cloud.dify.ai 1.17.0과 검증되었습니다.

• ✅ 앱 생성(Create app) → 초안 동기화(sync draft) (echo graph) → 초안 실행(run draft) → 삭제(delete) (MCP Streamable HTTP)
• ✅ MCP 전송:
  tools/call

stdio 및 Streamable HTTP를 통해 제공하며, examples/에서 예제 템플릿을 확인할 수 있습니다.

검증된 기능(validate clean): echo, LLM, RAG에 대한 유닛 테스트 · 타입 검사(typecheck clean) · MCP 스모크 테스트 (174개 도구)

174개 도구 전체가 모든 릴리스에서 실시간으로 테스트되는 것은 아닙니다. 커버리지는 작성 경로(앱, 워크플로우 초안/실행/게시, 인증, MCP 가드레일)에서 가장 조밀합니다. 지식 기반(knowledge bases), RAG 파이프라인, 스니펫, 에이전트, 주석(annotations), 오디오와 같은 표면적은 콘솔 API 계약에 따라 구현되고 유닛 테스트를 거치지만, 사용자의 인스턴스에서 직접 실행해 볼 때까지는 최선의 노력(best-effort)으로 간주해야 합니다.

아직 보류된 기능 (워크플로우 작성에 지장을 주지 않음):

• 클래식 데이터셋 API 외의 외부 지식/커넥터별 수집 UI
• UI 상에서 세분화된 데이터셋 권한 멤버 선택기(API 본문 통과만 가능)

사전 요구 사항: Node >= 23.6 (네이티브 TypeScript 타입 스트리핑 — 빌드 단계 없음).

git clone https://github.com/alexjiaguo/dify-mcp.git
cd dify-mcp
npm install
...

Dify 콘솔은 쿠키 + CSRF 인증을 사용합니다. 가장 쉬운 방법은 다음과 같습니다:

# 1. 브라우저에서 쿠키 내보내기 (cookie-editor 확장 프로그램 → Export → JSON)
# 2. cookies.json으로 저장한 후 다음 명령 실행:
difywf auth import-cookies --base-url https://cloud.dify.ai --file cookies.json
...

difywf agent guide # 에이전트를 위한 셀프 온보딩 플레이북
difywf 앱 목록 # 사용 가능한 앱 보기
difywf app create --mode workflow --name "my-agent-workflow"
...

스타터 그래프는 `examples/`에 있습니다.

: `minimal-workflow.json`

(echo),
`llm-workflow.json`

(start → LLM → answer), `rag-workflow.json`

(지식 검색 (knowledge retrieval)). 세 가지 모두 오류 레벨 문제가 없이 `difywf wf validate`를 통과합니다.

소스 인스턴스: 앱당 하나의 DSL을 작성하고 manifest.json (secrets 제외)을 생성합니다.

difywf app backup ./dify-backup

대상 인스턴스: 먼저 인증하거나 DIFY_API_BASE를 설정한 후 미리보기를 수행합니다.

...

더 큰 워크스페이스의 경우 필터를 사용할 수 있습니다: `--app-ids <id...>`,
`--mode workflow`,
`--name production`,
그리고 `--limit 50`.
백업은 모드 `0600`을 가진 로컬 파일입니다.
`include_secret=true`와 `overwrite=true` 모두 `--yes`가 필요합니다.
스케줄링 작업, Git, 그리고 S3 호환 스토리지의 경우 의도적으로 번들링하지 않았습니다. 전용 백업 서비스가 필요한 경우에는 `dify-dsl-pipe`를 사용하십시오.

동일한 바이너리, 동일한 174가지 도구입니다. 호스트에 맞게 설정을 복사하여 붙여넣으세요:

모든 MCP 파일 이름이 통일된 것은 없습니다. 모든 호스트가 필요로 하는 것은 동일한 로컬 stdio 실행 명령어입니다: `difywf mcp serve`

아래 예시는 사용자의 호스트가 기대하는 래퍼를 보여줍니다.

**Claude Code**

`claude mcp add dify -- difywf mcp serve`

**Codex** (`~/.codex/config.toml`)

[mcp_servers.dify]
command = "difywf"
args = ["mcp", "serve"]

**Cursor** (`.cursor/mcp.json`)

```json
{
"mcpServers": {
"dify": {
...

Cline · Roo Code · Continue

{
"mcpServers": {
"dify": {
...

Gemini CLI (~/.gemini/settings.json)

{
"mcpServers": {
"dify": {
...

Windsurf (Codeium)

Windsurf 설정(Cmd+, -> MCP Servers)에 명령어 difywf와 인자 ["mcp", "serve"]를 사용하여 MCP 서버를 추가하십시오.

Zed (~/.config/zed/settings.json)

{
"context_servers": {
"dify": {
...

Aider (CLI 전용 — MCP 없음)

Aider는 MCP를 지원하지 않지만, 셸 명령을 실행할 수 있습니다. CLI를 직접 사용하십시오:

/run difywf app list
/run difywf wf draft sync <app-id> --graph graph.json

OpenCode (opencode.json)

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
...

GitHub Copilot (.mcp.json 또는 ~/.copilot/mcp-config.json)

{
"servers": {
"dify": {
...

Goose (~/.config/goose/config.yaml)

extensions:
dify:
type: stdio
...

Crush (~/.config/crush/crushrc 또는 ./.crushrc)

mcp add dify --command difywf --args mcp serve

OpenHands (~/.openhands/mcp.json)

{
"mcpServers": {
"dify": {
...

기타 인기 MCP 에이전트 — Antigravity, Trae, Kilo Code, Warp, Droid, Amp, Cody, Augment, Amazon Q Developer

대부분의 최신 에이전트는 mcpServers를 사용하는 로컬 stdio MCP 설정을 노출합니다.
아래 JSON 형태를 따릅니다. 만약 사용자의 에이전트가 Codex 스타일 TOML 형식을 따른다면 두 번째 예시를 사용하세요:

{
"mcpServers": {
"dify": {
...

[mcp_servers.dify]
command = "difywf"
args = ["mcp", "serve"]

만약 사용자의 에이전트가 셸 명령어만 실행한다면, CLI를 직접 사용하세요:

difywf agent guide
difywf app list

원격 호스트? stdio 대신 스트리밍 가능한 HTTP 사용

로컬 프로세스를 생성할 수 없는 원격 또는 컨테이너화된 호스트의 경우, 무상태(stateless) Streamable HTTP 전송을 통해 MCP 서버를 실행하세요:

difywf mcp serve --http --host 127.0.0.1 --port 8080
# 또는 환경 변수를 통해: DIFYWF_MCP_TRANSPORT=http DIFYWF_MCP_HOST=127.0.0.1 \
# DIFYWF_MCP_PORT=8080 difywf mcp serve

루프백 바인딩은 토큰이 필요하지 않습니다. 0.0.0.0을 바인딩하는 경우 (Docker 포함)에는 DIFYWF_MCP_TOKEN이 필요합니다.

. 클라이언트는 Authorization: Bearer <토큰> 또는 x-difywf-token을 전송합니다.
. GET /health는 프로브를 위해 인증 없이 유지됩니다.

Streamable-HTTP 지원 클라이언트라면 어느 곳이든 http://<호스트>:8080/mcp를 가리키게 하세요.
. 각 POST 요청은 자체 포함된 JSON-RPC 메시지입니다 (initialize / tools/list / tools/call); 세션이 필요하지 않습니다. /mcp에 대한 GET 및 DELETE 요청은 405로 거부됩니다.

Docker 서비스로 실행하는 방법:

Docker 이미지 빌드 및 실행 명령어는 다음과 같습니다.

docker build -t dify-mcp .
docker run -d --name dify-mcp \
-p 3000:3000 \
...

Dify에서 설정할 MCP URL은 http://<docker-host>:3000/mcp입니다.
여기에 Bearer 토큰도 필요합니다. Dify와 이 서비스가 동일한 Docker Compose 네트워크 내에서 실행되는 경우, 서비스 이름을 사용하세요. 예를 들어 http://dify-mcp:3000/mcp를 사용하면 됩니다.

컨테이너의 헬스 엔드포인트는 GET /health입니다.

또한 컨테이너 내부에서는 difywf CLI도 사용할 수 있습니다. 예를 들어 docker exec dify-mcp difywf --version과 같이 실행할 수 있습니다.

쿠키나 토큰을 이미지에 직접 넣기보다는 Docker secrets 또는 배포 플랫폼의 secret store를 사용하는 것이 좋습니다.

만약 difywf가 PATH에 설정되어 있지 않다면, 절대 경로를 사용하세요: node /path/to/dify-mcp/bin/difywf.js mcp serve

19개의 네임스페이스에 걸쳐 174개의 도구(tools)를 제공합니다. 전체 라이브 목록은 difywf --help로 확인하거나, 에이전트 중심의 플레이북을 보려면 difywf agent guide를 사용하세요.