11. AI 비서로 만들기 (MCP)¶

Claude나 ChatGPT 같은 AI 비서를 이음새에 연결하면, 말로 자동화를 만들 수 있습니다.

"매일 아침 9시에 주문 API에서 어제 주문을 가져와서, 요약해서 슬랙 #운영 채널로 보내줘"

AI가 이 말을 듣고 워크플로우 YAML을 작성하고, 검증하고, 저장하고, 실행해서 결과까지 확인합니다. 연결 방식은 MCP(Model Context Protocol) 라는 표준입니다.

1단계 — API 키 발급¶

사이드바 API Keys로 들어갑니다.
새 키를 만듭니다.
화면에 딱 한 번 보이는 키를 복사해서 안전한 곳에 보관하세요. 창을 닫으면 다시 볼 수 없습니다.

이 키는 워크스페이스 전체에 접근할 수 있습니다. 유출되면 즉시 API Keys 화면에서 삭제하고 새로 발급하세요.

2단계 — AI 비서에 연결¶

같은 API Keys 화면 아래에 연결 방법이 안내되어 있습니다. 서버 주소는 이것입니다.

https://api.eeumsae.com/mcp

인증은 X-API-Key 헤더로 합니다.

Claude Code (CLI)¶

터미널에서 한 번 실행하면 등록됩니다.

claude mcp add --transport http weaver https://api.eeumsae.com/mcp \
  --header "X-API-Key: <발급받은키>"

프로젝트 단위 설정 (`.mcp.json`)¶

프로젝트 루트의 .mcp.json에 추가합니다.

{
  "mcpServers": {
    "weaver": {
      "type": "http",
      "url": "https://api.eeumsae.com/mcp",
      "headers": {
        "X-API-Key": "<발급받은키>"
      }
    }
  }
}

이 파일을 git에 커밋한다면 키를 넣지 마세요. 환경변수나 개인 설정으로 분리하세요.

Claude Desktop¶

Claude Desktop은 HTTP 헤더 인증을 직접 지원하지 않아 mcp-remote 브리지를 씁니다. claude_desktop_config.json에 추가합니다.

{
  "mcpServers": {
    "weaver": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.eeumsae.com/mcp",
        "--header",
        "X-API-Key:<발급받은키>"
      ]
    }
  }
}

그 외 MCP 지원 도구¶

API Keys 화면에 주요 도구의 1클릭 추가 버튼이 있습니다. 버튼이 없는 도구라면 서버 URL과 X-API-Key 헤더를 직접 등록하면 됩니다.

3단계 — 연결 확인¶

AI 비서에게 물어보세요.

"이음새 워크스페이스 확인해줘"

워크스페이스 이름이 나오면 성공입니다.

AI가 할 수 있는 일¶

연결되면 AI는 아래 도구들을 쓸 수 있습니다.

둘러보기

도구	하는 일
`get_workspace`	워크스페이스 확인
`list_integrations` / `get_integration`	쓸 수 있는 통합과 입력 항목 조회
`list_connections` / `list_connection_resources`	연결된 서비스와 채널 목록 조회

만들기

도구	하는 일
`validate_workflow`	저장 없이 YAML 검증만
`create_workflow`	새 워크플로우 생성
`update_workflow`	기존 워크플로우 수정 (전체 교체)
`list_workflows` / `get_workflow`	목록·상세 조회

돌려보기

도구	하는 일
`execute_workflow`	즉시 실행
`get_execution`	실행 결과를 노드별로 확인
`list_executions`	실행 이력
`cancel_execution`	실행 취소

AI는 보통 이 순서로 움직입니다. 통합 확인 → YAML 작성 → 검증 → 저장 → 실행 → 결과 확인 → (실패하면) 고쳐서 다시.

⚠️ 발송·결제는 승인을 한 번 묻습니다¶

Slack 발송처럼 바깥 세상에 실제 영향을 주는 노드가 들어 있으면, execute_workflow가 첫 호출에서 바로 실행하지 않습니다.

대신 "이런 게 실행됩니다"라는 목록을 돌려주고 사용자에게 확인을 요청합니다.

이 워크플로우는 다음을 실행합니다:
  · notify (slack_post_message) → 채널 C0123ABCDEF 에 메시지 발송

진행할까요?

사람이 승인해야만 실제로 돕니다. AI가 실수로 고객에게 메시지를 뿌리는 일을 막는 장치입니다. 목록을 보고 이상한 게 있으면 승인하지 마세요.

잘 시키는 법¶

✅ 구체적으로¶

"매일 오전 9시(한국시간)에 https://api.myshop.com/orders에서 어제 주문을 가져와서, 총 매출과 건수를 계산하고, GPT로 3줄 요약해서 Slack #운영 채널로 보내줘. API 토큰은 시크릿 SHOP_API_TOKEN에 있어."

유용한 요청들¶

하고 싶은 것	이렇게 말하면 됩니다
목록 보기	"내 워크플로우 목록 보여줘"
실패 원인 찾기	"`revenue-report` 최근 실행 왜 실패했는지 봐줘"
수정	"그 워크플로우에 재시도 3번 추가해줘"
테스트	"지금 한 번 실행해보고 결과 알려줘"
통합 확인	"지금 쓸 수 있는 통합 뭐가 있어?"

알아두면 좋은 것¶

검증은 무료입니다. validate_workflow는 저장하지 않으니, AI에게 "검증만 해봐"라고 시켜도 됩니다.
표현식은 검증에서 안 잡힙니다. ${...} 경로 오류는 실제로 실행해봐야 드러납니다. 한 번은 돌려보세요.
실행 중이면 수정이 거부됩니다. 돌고 있는 실행이 끝나기를 기다리거나 취소한 뒤 다시 시도하세요.
create_workflow는 id가 겹치면 실패합니다. 다른 id를 쓰거나 update_workflow로 고치면 됩니다.

API로 직접 쓰기¶

MCP 없이 REST API를 직접 부를 수도 있습니다. 같은 API 키를 X-API-Key 헤더에 넣습니다.

curl -H "X-API-Key: <발급받은키>" https://api.eeumsae.com/workflows

워크플로우 YAML의 JSON Schema는 아래에서 받을 수 있습니다. 에디터(yaml-language-server)에 물려두면 작성 중에 자동완성과 검증이 됩니다.

https://api.eeumsae.com/schema/workflow.json

다음 → 12. 실전 레시피