SETTINGS · 외부 에이전트 · MCP

Claude·Codex MCP 연동

공개 9miho 스킬과 현재 Desktop의 지침 준비 범위를 이해하고 Claude Code나 Codex를 실행 중인 9Miho에 MCP로 연결합니다.

에이전트가 들어오는 두 방향

9Miho에는 에이전트가 연결되는 방향이 두 가지입니다. 같은 카탈로그·에셋·검증·Run·승인 계약을 쓰지만 출발점은 서로 반대입니다.

방향 작업이 시작되는 곳 무엇을 설정하나
9Miho 안의 Agent Agent 패널, Storyteller 또는 Assistant node 에이전트 백엔드와 모델에서 백엔드와 모델을 고릅니다. 9Miho가 CLI를 실행합니다.
외부 에이전트 안의 9Miho Claude Code, Codex, Cursor 또는 다른 MCP 호스트 호스트가 9Miho의 내장 MCP 진입점을 실행해 이미 켜져 있는 로컬 서버와 통신합니다.

두 번째 방식은 더 큰 작업이 이미 Claude나 Codex에서 진행 중일 때 유용합니다. 조사 자료와 파일, 코드, 제작 계획을 복사한 프롬프트로 끊지 않고 같은 제작 기록 안으로 가져올 수 있습니다.

공개 9miho 스킬이 더하는 것

공개 KumihoIO/9miho-skills는 Claude Code, Codex, Cursor와 Markdown Skill을 읽는 호스트를 위한 MIT 라이선스 트리거 팩입니다. 비공개 9Miho 애플리케이션이나 제작 엔진의 소스가 들어 있는 저장소는 아닙니다.

설치된 각 트리거는 에이전트가 언제 9Miho에 작업 지침을 요청해야 하는지 알려 줍니다. 실제 지침은 작업 시점에 연결된 설치판의 get_skill(task, detail)에서 가져옵니다. 따라서 에이전트 안에 오래된 복사본을 남기지 않고, 현재 서버의 노드 카탈로그·프로바이더·비용 규칙과 같은 버전을 따릅니다.

이미지·영상 생성, Library 검색, 재사용 가능한 Subject, 제품 사진, 스토리보드, Storyteller 기획과 제작을 위한 트리거가 포함됩니다. 다만 이 목록만 보고 사용할 수 있다고 판단하지 마세요. 실제 기준은 실행 중인 설치판이 돌려주는 list_skills()입니다.

현재 릴리스의 범위: 서명된 Desktop 런타임에는 MCP stdio 진입점이 들어 있지만, 새 Desktop 설치가 같은 버전의 작업 지침 라이브러리까지 자동으로 준비하지는 않습니다. 공개 저장소가 설치하는 것은 에이전트 호스트 쪽 트리거이며 서버 지침 라이브러리는 아닙니다. 저장소의 현재 설정 도우미도 9Miho 소스 체크아웃을 전제로 하므로, 배포된 Desktop 바이너리의 지원 설치 경로로 사용하면 안 됩니다. 따라서 MCP는 연결됐지만 list_skills()가 비어 있거나 공개 트리거보다 오래된 상태일 수 있습니다.

MCP로 할 수 있는 일

연결된 에이전트는 같은 MCP 표면에서 다음 작업을 할 수 있습니다.

  • 현재 노드 카탈로그를 읽고 정확한 Variant와 포트 계약을 확인합니다.
  • Library에서 에셋을 찾고 특정 Revision을 고정하며 제작 계보를 살핍니다.
  • Storyteller의 이야기 구조와 제작 작업을 읽고 제안합니다.
  • Flow를 읽고 설계·검증한 뒤 열린 Canvas에 배치합니다.
  • 유료 그래프를 실행하기 전에 예상 비용을 확인합니다.
  • 검증된 Run을 시작하고 상태와 결과 Kref를 따라갑니다.

기존 Flow를 바꾸기 전에는 먼저 get_flow를 호출해야 합니다. put_flow는 창작자가 보게 될 문서를 실제로 저장하므로 임시 메모가 아니라 편집 작업입니다.

연결 전에 확인할 것

  1. Kumiho Desktop으로 9Miho를 설치하고 실행합니다.
  2. http://127.0.0.1:9999/api/healthz가 {"status":"ok"}를 반환하는지 확인합니다.
  3. Kumiho CE 또는 선택한 Kumiho 연결을 사용할 수 있어야 합니다. 에셋과 스킬 지침이 여기에 저장됩니다.
  4. MCP를 사용할 운영체제 계정에 Claude Code나 Codex를 설치하고 로그인합니다.

포트 9999는 반드시 루프백에만 두세요. 로컬 9Miho HTTP API는 1인용 자체 호스팅 설치를 전제로 하므로 LAN이나 인터넷에 직접 공개하면 안 됩니다.

공개 트리거 설치

Codex와 호환되는 Skill 호스트에서는 다음 명령을 사용합니다.

npx skills add KumihoIO/9miho-skills

Claude Code에서는 다음 명령을 차례로 실행합니다.

/plugin marketplace add KumihoIO/9miho-skills
/plugin install miho@miho

트리거 설치와 MCP 연결은 서로 다른 단계입니다. 저장소를 설치했다고 서버까지 자동 연결되는 것은 아닙니다.

Desktop이 설치한 서명 런타임 연결

Kumiho Desktop이 설치한 9Miho 실행 파일에는 MCP stdio 진입점이 이미 들어 있습니다. 정식 배포판 사용자는 비공개 소스 체크아웃 명령이 아니라 이 실행 파일을 사용해야 합니다.

일반적인 설치 위치는 다음과 같습니다.

플랫폼 MCP 명령
Windows %USERPROFILE%\.kumiho\apps\9miho\bin\9miho.exe --mcp-stdio
macOS /Users/YOU/.kumiho/apps/9miho/bin/9miho --mcp-stdio
Linux /home/YOU/.kumiho/apps/9miho/bin/9miho --mcp-stdio

Codex

~/.codex/config.toml에 MCP 서버를 추가합니다. TOML의 command 값에서는 ~가 안정적으로 확장되지 않으므로 본인 계정의 절대 경로를 쓰세요.

[mcp_servers.miho]
command = "C:\\Users\\YOU\\.kumiho\\apps\\9miho\\bin\\9miho.exe"
args = ["--mcp-stdio"]

[mcp_servers.miho.env]
MIHO_SERVER_URL = "http://127.0.0.1:9999"

macOS나 Linux에서는 command를 위 표의 절대 경로로 바꿉니다.

Claude Code

Windows PowerShell:

claude mcp add -e MIHO_SERVER_URL=http://127.0.0.1:9999 miho -- "$HOME\.kumiho\apps\9miho\bin\9miho.exe" --mcp-stdio

macOS 또는 Linux:

claude mcp add -e MIHO_SERVER_URL=http://127.0.0.1:9999 miho -- "$HOME/.kumiho/apps/9miho/bin/9miho" --mcp-stdio

MCP 설정을 바꾼 뒤에는 해당 호스트를 재시작합니다.

연결 확인

에이전트에게 다음 호출을 순서대로 요청하세요.

  1. list_skills() — MCP가 이 설치판의 작업 지침 라이브러리에 닿는지 확인합니다.
  2. get_skill(task="video") — 이름만이 아니라 실제 작업 지침 섹션이 돌아와야 합니다.
  3. list_catalog(category="video") — 현재 실행 중인 서버의 카탈로그를 읽는지 확인합니다.

MCP 도구 자체가 보이지 않으면 호스트가 새 설정을 아직 불러오지 않은 것입니다. list_skills()가 비어 있거나 공개 트리거보다 오래된 팩을 돌려준다면 MCP 연결은 됐지만 해당 설치판의 지침 라이브러리가 같은 버전으로 준비되지 않은 상태입니다. 서버가 돌려준 안내나 해당 릴리스 노트를 따르세요. 비공개 9Miho 소스 접근을 요구하는 명령으로 대신하면 안 됩니다.

승인과 자격 증명의 경계

  • 프로바이더 API 키는 9Miho Settings → 프로바이더에만 둡니다. Skill 파일이나 MCP 설정에 넣지 마세요.
  • 외부 에이전트는 비용을 계산하고 유료 Run을 제안할 수 있습니다. 일반적인 배포판 경로에서는 9Miho Canvas의 항목별 비용 확인에서 Run이 멈춥니다.
  • confirm_spend=true는 에이전트가 비용을 먼저 설명했다는 표시일 뿐 결제 승인이 아닙니다.
  • Storyteller 제안은 별도 변경 동작인 approve_story_canon이 호출되기 전까지 Draft로 남습니다. MCP 도구 계약은 에이전트가 먼저 사용자의 직접 지시를 받도록 요구하지만, 현재 서버가 두 번째 사람 확인 단계를 강제하지는 않습니다. 이를 권한·보안 경계가 아니라 에이전트 행동 규칙으로 봐야 합니다.
  • 연결된 에이전트는 사용자가 지정한 로컬 미디어를 업로드하고 put_flow로 Flow를 교체할 수 있습니다. 파일 경로를 확인하고 기존 Flow를 먼저 읽은 뒤 허용하세요.

외부 에이전트는 제작 시스템의 넓은 범위를 다룰 수 있습니다. 호스트의 승인과 파일 접근 제한을 켜 두고, Canon 승인은 직접 지시한 뒤 실행하며, 비용이 드는 작업은 9Miho의 항목별 확인 단계를 사용하세요.