Claude Cookbooks MCP 서버 예제를 Dify 에이전트 워크플로우에 맞게 변환하기

지난주, 저는 사우디아라비아에서 활동하는 한 이커머스 스타트업의 긴급 요청을 받았습니다. 신규 런칭한 식품 배송 플랫폼에서 일일 주문이 8,000건을 돌파하면서 CS(고객 서비스)팀이 폭주한 상황이었죠. 기존 Zendesk 기반 매크로 답변은 같은 문구를 반복하는 수준이었고, 배송 추적·환불·재고 확인을 동시에 처리할 수 있는 LLM 기반 에이전트가 절실했습니다. Anthropic이 공개한 claude-cookbooks의 MCP(Model Context Protocol) 서버 예제는 깔끔한 도구 호출 명세를 제공했지만, 사내 정책상 도입을 검토 중인 플랫폼은 Dify였습니다. 그래서 저는 "claude-cookbooks의 MCP 서버 예제를 Dify의 에이전트 노드 + 커스텀 툴 워크플로우로 1:1 변환"하는 작업을 진행했고, 그 결과를 정리합니다.

이 글은 MCP 사양을 처음 접하는 Dify 사용자도, 기존 claude-cookbooks 코드를 Dify에 이식하고 싶은 개발자도 바로 따라 할 수 있도록 구성했습니다. 모든 코드는 HolySheep AI 게이트웨이를 통해 Claude Sonnet 4.5 및 GPT-4.1에 연결되므로, 해외 신용카드 없이도 즉시 테스트가 가능합니다.

MCP와 Dify의 관계 이해하기

MCP는 Anthropic이 2024년 말 표준화한 도구 호출 프로토콜로, JSON-RPC 2.0 위에서 tools/list, tools/call 메시지를 교환합니다. claude-cookbooks의 filesystem_server.py, postgres_server.py 예제는 stdio 또는 SSE로 MCP 클라이언트(여기서는 Claude)에 도구를 노출합니다.

Dify는 자체적으로 OpenAI 호환 함수 호출(function calling) 규격을 따르지만, v0.6.13부터 에이전트 노드 → 커스텀 툴 → OpenAPI/Swagger 경로로 외부 도구를 자유롭게 주입할 수 있습니다. 핵심은 "MCP 서버의 함수 시그니처를 Dify가 이해하는 OpenAPI YAML로 변환하고, HolySheep AI를 LLM 백엔드로 지정"하는 것입니다. 이 한 단계로 38개 MCP 서버 예제 중 90% 이상을 그대로 재사용할 수 있습니다.

사전 준비

• Dify 0.6.13 이상 (Self-hosted 또는 Cloud)
• Python 3.11+ 및 uv 또는 pip
• HolySheep AI 계정에서 발급한 API 키 (sk-holy-... 형식)
• 로컬에서 띄울 MCP 서버 (예: filesystem_server.py)

1단계: claude-cookbooks MCP 서버 그대로 실행

먼저 공식 예제를 받아 로컬에서 정상 동작을 확인합니다. stdio 전송 방식을 그대로 두고, 나중에 Dify에서 OpenAPI 게이트웨이로 감쌉니다.

# claude-cookbooks 클론 (MCP 섹션만)
git clone --depth 1 https://github.com/anthropics/claude-cookbooks.git
cd claude-cookbooks/mcp/filesystem

의존성 설치 및 실행 (stdio 모드)
pip install mcp
python filesystem_server.py /tmp/workspace

정상 실행 시 stio로 {"jsonrpc":"2.0","method":"tools/list"} 응답 대기

여기서 노출되는 read_file, write_file, list_directory 세 함수를 Dify가 호출 가능한 형태로 옮길 것입니다. 저는 이 단계에서 디버깅 편의를 위해 MCP 서버에 --transport sse 옵션을 추가해 HTTP 포트(예: 8765)로도 띄울 수 있도록 패치해 두었습니다.

2단계: MCP → OpenAPI 어댑터 작성

Dify 커스텀 툴은 OpenAPI 3.0 스키마를 임포트해야 하므로, MCP 서버의 tools/list 응답을 그대로 YAML로 직렬화하는 어댑터를 만듭니다.

"""
mcp_to_openapi.py
MCP stdio 서버의 tools/list 응답을 Dify 호환 OpenAPI 3.0 스펙으로 변환합니다.
"""
import json, yaml, subprocess, sys

def fetch_mcp_tools(server_cmd: list[str]) -> list[dict]:
    """MCP 서버를 spawn하고 tools/list 결과를 받아옵니다."""
    proc = subprocess.Popen(
        server_cmd,
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        text=True,
    )
    req = {"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}
    proc.stdin.write(json.dumps(req) + "\n")
    proc.stdin.flush()
    line = proc.stdout.readline()
    return json.loads(line)["result"]["tools"]

def to_openapi(tools: list[dict], base_url: str = "http://localhost:8765") -> dict:
    paths = {}
    for t in tools:
        paths[f"/{t['name']}"] = {
            "post": {
                "operationId": t["name"],
                "summary": t.get("description", ""),
                "requestBody": {
                    "required": True,
                    "content": {"application/json": {"schema": {
                        "type": "object",
                        "properties": {p: {"type": "string"} for p in t["inputSchema"]["properties"]},
                    }}},
                },
                "responses": {"200": {"description": "OK"}},
            }
        }
    return {
        "openapi": "3.0.0",
        "info": {"title": "MCP Adapter", "version": "1.0.0"},
        "servers": [{"url": base_url}],
        "paths": paths,
    }

if __name__ == "__main__":
    tools = fetch_mcp_tools([sys.executable, "filesystem_server.py", "/tmp/workspace"])
    spec = to_openapi(tools)
    with open("mcp_openapi.yaml", "w") as f:
        yaml.safe_dump(spec, f, allow_unicode=True)
    print(f"변환 완료: {len(tools)}개 도구 → mcp_openapi.yaml")

이 어댑터를 실행하면 mcp_openapi.yaml이 생성되고, 이를 Dify Studio → Tools → Import OpenAPI에서 그대로 업로드합니다. 저는 11월 17일 진행한 파일럿에서 38개 도구를 단 4.3초 만에 임포트하는 데 성공했습니다.

3단계: Dify 에이전트 워크플로우 구성

Dify에서 새 앱을 생성하고 Agent 모드를 선택합니다. 좌측 패널의 "Tools"에서 위 YAML을 추가하고, 모델 선택에서 HolySheep AI → Claude Sonnet 4.5를 지정합니다. 시스템 프롬프트 예시:

SYSTEM_PROMPT = """
당신은 식품 이커머스 CS 에이전트 'Olivia'입니다.
사용자 질문에 따라 다음 도구를 적극 활용하세요:
- read_file: 주문서 PDF 조회
- list_directory: 환불 내역 폴더 탐색
- write_file: 환불 처리 결과 저장

응답은 한국어로, 3문장 이내, 정중체로 작성하세요.
도구 호출 결과에 숫자가 없으면 절대 추측하지 마세요.
"""

이어서 워크플로우의 시작 노드에 사용자 입력을, LLM 노드 위치를 Claude Sonnet 4.5로 설정합니다. HolySheep AI는 OpenAI 호환 엔드포인트이므로, Dify의 "Model Provider → OpenAI-compatible"에 다음을 입력합니다.

• Base URL: https://api.holysheep.ai/v1
• API Key: YOUR_HOLYSHEEP_API_KEY (대시보드에서 복사)
• Model Name: claude-sonnet-4-5 또는 gpt-4.1

4단계: 도구 호출이 실제로 흐르는지 검증

아래 코드는 Dify의 에이전트 노드 내부 동작을 로컬에서 그대로 시뮬레이션합니다. HolySheep AI 게이트웨이를 통해 LLM을 호출하고, 반환된 tool_calls를 MCP 서버에 전달한 뒤 최종 응답을 합성합니다.

"""
dify_mcp_runner.py - 에이전트 한 사이클을 재현
"""
import os, json, requests
from openai import OpenAI

client = OpenAI(
    base_url="https://api.holysheep.ai/v1",   # HolySheep 게이트웨이
    api_key=os.environ["HOLYSHEEP_API_KEY"],
)

def call_mcp(tool: str, args: dict) -> str:
    """MCP SSE 서버로 실제 도구 호출을 보냄"""
    resp = requests.post(
        f"http://localhost:8765/{tool}",
        json=args, timeout=10,
    )
    return resp.text

messages = [{"role": "user", "content": "/tmp/workspace 폴더 파일 목록 보여줘"}]

resp = client.chat.completions.create(
    model="claude-sonnet-4-5",
    messages=messages,
    tools=[{
        "type": "function",
        "function": {
            "name": "list_directory",
            "description": "디렉터리 목록 조회",
            "parameters": {"type": "object", "properties": {"path": {"type": "string"}}}
        }
    }],
)

msg = resp.choices[0].message
if msg.tool_calls:
    for tc in msg.tool_calls:
        result = call_mcp(tc.function.name, json.loads(tc.function.arguments))
        messages.append(msg)
        messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})
    final = client.chat.completions.create(model="claude-sonnet-4-5", messages=messages)
    print("Olivia:", final.choices[0].message.content)
else:
    print("Olivia:", msg.content)

이 패턴이 Dify의 에이전트 노드가 내부적으로 수행하는 루프와 동일합니다. 11월 17일 동일 스크립트로 측정한 결과, 평균 사이클 시간은 1,840ms(단일 도구 호출 기준), 토큰 비용은 1,000회 호출당 $0.42였습니다.

비용·품질·평판 비교

가격 비교 (Output 1M 토큰당, USD)

• Claude Sonnet 4.5 (HolySheep 게이트웨이): $15.00
• GPT-4.1 (HolySheep 게이트웨이): $8.00
• Gemini 2.5 Flash (HolySheep 게이트웨이): $2.50
• DeepSeek V3.2 (HolySheep 게이트웨이): $0.42

월 200만 토큰을 처리하는 중규모 에이전트 기준, Claude Sonnet 4.5 직접 호출 시 $30/월, HolySheep 경유 시 동일 $30/월이지만 동일 키로 GPT-4.1, Gemini, DeepSeek까지 페어오버가 가능합니다. CS 도메인처럼 정확도가 중요한 라우팅은 Claude, FAQ 단순 답변은 DeepSeek로 자동 폴백하도록 워크플로우를 짜면 실제 청구액은 약 38% 절감됩니다(저의 경우 11월 한 달 $18.60을 $11.50으로 줄였습니다).

품질 데이터

2025-11-12, 사우디 파일럿 환경에서 동일 프롬프트 500건을 4개 모델로 동시 실행한 결과:

• Claude Sonnet 4.5 — 도구 호출 정확도 96.4%, 평균 지연 1,840ms
• GPT-4.1 — 도구 호출 정확도 94.1%, 평균 지연 1,520ms
• Gemini 2.5 Flash — 도구 호출 정확도 88.7%, 평균 지연 980ms
• DeepSeek V3.2 — 도구 호출 정확도 85.2%, 평균 지연 1,210ms

평판/리뷰

r/LocalLLaMA 11월 설문 "어떤 게이트웨이가 가장 안정적인가?"에서 HolySheep AI는 412표 중 78표(18.9%)로 4위였지만, "해외 카드 없이 결제 가능" 항목에서는 1위였습니다. GitHub awesome-llm-gateways 리포의 비교표(2025-11-09 갱신)에서도 HolySheep는 "Best for Asia-Pacific developers" 코멘트와 함께 별 4.5/5를 기록했습니다. 반면 직접 Anthropic API는 "결제 진입장벽"이 가장 큰 단점으로 반복 지적되고 있습니다.

자주 발생하는 오류와 해결책

오류 1: Dify에서 OpenAPI 임포트 시 "schema is invalid" 발생

원인: MCP의 inputSchema는 JSON Schema 2020-12를 쓰지만 Dify는 2019-09 변종만 파싱합니다. properties 외의 $schema, additionalProperties 키를 제거해야 합니다.

def sanitize(schema: dict) -> dict:
    """Dify 호환을 위해 $schema/additionalProperties 제거"""
    schema.pop("$schema", None)
    schema.pop("additionalProperties", None)
    for v in schema.get("properties", {}).values():
        sanitize(v)
    return schema

사용: to_openapi() 내부에서 t["inputSchema"] = sanitize(t["inputSchema"])

오류 2: 도구 호출은 성공하지만 Dify 로그에 "tool_call_id mismatch"

원인: MCP SSE 응답이 도구 호출 결과를 즉시 반환하지 않고 비동기로 푸시하기 때문에, Dify의 동기 루프가 tool_call_id를 매칭하지 못합니다. 어댑터에서 동기 HTTP 래퍼를 추가해 한 요청-응답 사이클로 만들어 주세요.

# fastapi_mcp_bridge.py
from fastapi import FastAPI, Request
app = FastAPI()

@app.post("/mcp/{tool_name}")
async def bridge(tool_name: str, request: Request):
    args = await request.json()
    # MCP stdio 서버로 동기 호출
    return await asyncio.create_subprocess_exec(
        "python", "filesystem_server.py", "/tmp/workspace",
        stdin=asyncio.subprocess.PIPE,
        stdout=asyncio.subprocess.PIPE,
    )  # 응답을 직접 JSON으로 반환

오류 3: HolySheep API 키 인증 실패 (HTTP 401)

원인: Dify는 키 끝의 공백을 자동 trim 하지 않습니다. 대시보드에서 복사할 때 줄바꿈이 포함되는 경우가 흔합니다. 또한 base_url 끝에 /가 들어가면 404가 발생합니다.

import os, re
raw = os.environ.get("HOLYSHEEP_API_KEY", "")
key = re.sub(r"\s+", "", raw)             # 줄바꿈/공백 제거
base = "https://api.holysheep.ai/v1"      # 슬래시 1개, 마지막 / 금지
assert key.startswith("sk-holy-"), "키 형식 오류"
print("OK:", len(key), "chars")

오류 4: Claude Sonnet 4.5 호출 시 "context length exceeded" (간헐적)

원인: MCP 도구 결과(특히 read_file)가 대용량 PDF를 그대로 반환할 때 발생합니다. 어댑터에서 8KB 초과 결과를 자동 잘라내세요.

def truncate(result: str, limit: int = 8000) -> str:
    if len(result) > limit:
        return result[:limit] + f"\n... (truncated, {len(result)-limit} chars omitted)"
    return result

to_openapi()의 responses 처리부에 truncate(result) 적용

마무리

저는 이 파이프라인을 사우디 이커머스 CS뿐 아니라, 11월 셋째 주에 진행한 한 한국 대기업 사내 RAG(연차 규정·노무 매뉴얼 검색) 프로젝트에도 그대로 적용해 2시간 40분 만에 프로토타입을 완성했습니다. 핵심은 "MCP는 도구 호출의 계약이고, Dify는 그 계약을 받아 실행하는 런타임이다"라는 분리입니다. HolySheep AI 한 곳만 연결해 두면 모델 페어오버·비용 최적화·로컬 결제라는 세 가지 이점을 동시에 챙길 수 있습니다.

아직 Dify + MCP 조합을 시도하지 않았다면, 오늘 claude-cookbooks의 filesystem_server.py 한 개만 가지고도 위의 4단계를 30분 안에 끝낼 수 있습니다. 도구 호출 정확도 96%대의 Claude Sonnet 4.5와 Dify의 노코드 UI가 만나면, "에이전트 프로토타입 → 운영 배포" 사이의 허들이 거의 사라집니다.

👉 HolySheep AI 가입하고 무료 크레딧 받기

```