MoAI-ADK는 Claude Code의 MCP 생태계 위에 올라타되, 그 위에 자체 MCP 서버를 하나 더 얹습니다. 바이너리 하나(moai mcp-server)가 stdio 로컬 서버로 실행되며, SPEC 라이프사이클 감사, 검증 스냅샷, 골 엔진, 교차 모델 감사, codex 위임 등 MoAI-ADK 고유의 17개 도구를 Claude Code 런타임에 노출합니다.

두 MCP 문서의 관계

Claude Code 일반 MCP는 플랫폼 자체의 MCP(Model Context Protocol) 통합을 다룹니다 — USB 포트 비유, 서버 등록, 전송 타입, /mcp 명령, OAuth 인증, 지연 로드 원리.

이 문서는 그 위에 올라탄 MoAI 자체 MCP 서버를 다룹니다. 두 표면은 같은 코어 규칙을 공유하지만, 다루는 주체가 다릅니다.

Claude Code의 MCP 생태계와 MoAI의 자체 MCP 서버는 서로 별개의 서버이면서, 동일한 운용 원칙 위에 놓입니다. 세 가지 코어 규칙을 공유합니다.

flowchart TD
    CC["Claude Code 런타임
(도구 권한 · 지연 로드 · 승인)"]
    CMCP["일반 MCP 서버
(context7, chrome-devtools, …)"]
    MMCP["moai mcp-server
(MoAI 자체 · 17 도구)"]
    CC --> CMCP
    CC --> MMCP
    MMCP --> TOOLS["SPEC lifecycle · 검증 · 골 · 감사 · codex 위임"]
    CMCP --> EXT["외부 도구 (라이브러리 문서 · 브라우저 자동화 · …)"]

핵심은 “MoAI가 MCP를 프로비저닝하지 않는다"는 것이 반쪽짜리 진실이라는 점입니다. 외부 MCP 서버(context7, playwright 등)는 기본으로 프로비저닝하지 않는 것이 맞습니다. 하지만 MoAI 자체 서버 하나는 moai init 시점에 default-on으로 깔립니다. 이 서버가 곧 MoAI의 17-도구 카탈로그가 Claude Code에 닿는 통로입니다.

moai init은 프로젝트 루트에 .mcp.json(project scope)을 생성하며, 그 안에 정확히 하나의 활성 엔트리를 깝니다 — 자체 moai 로컬 stdio 서버입니다.

{
  "mcpServers": {
    "moai": {
      "command": "moai",
      "args": ["mcp-server"]
    }
  },
  "staggeredStartup": {
    "enabled": true,
    "delayMs": 500,
    "connectionTimeout": 15000
  }
}

staggeredStartup은 서버가 순차적으로 시작되도록 조절하는 Claude Code 런타임 필드입니다. 서버가 여럿일 때 동시 기동 경쟁(race)을 막아 줍니다.

배포 기본값은 moai 서버 하나만 활성입니다. 네 개의 외부 서버는 문서에 기록되어 있지만 비활성 상태로, moai mcp add <이름> 명령으로 켭니다.

.mcp.json은 git-tracked 파일입니다. 그래서 “비밀을 싣는 엔트리, 자격 증명이 필요한 엔트리, 중립성 검사에 실패하는 엔트리"는 금지됩니다. 모든 환경변수 값은 ${VAR} 리터럴로 적습니다 — Claude Code 런타임이 실제 값을 확장하며, 해석된 비밀이 git-tracked .mcp.json에 직렬화되지 않습니다.

{
  "remote-needs-auth": {
    "type": "http",
    "url": "https://mcp.example.com/sse",
    "headers": {
      "Authorization": "Bearer ${MY_API_KEY}"
    }
  }
}

${MY_API_KEY}는 런타임이 환경변수에서 채웁니다. 파일 자체에는 리터럴 문자열만 남으므로, 비밀이 저장소에 노출되지 않습니다.

사용자가 직접 .mcp.json을 손편집하지 않습니다. moai mcp add|remove|list CLI가 파일을 관리하며, 이 CLI는 atomic-RWM seam(flock 파일 잠금 + compare-retry + 백업 후 기록 + idempotent-skip)으로 동작합니다. 두 세션이 동시에 편집해도 한쪽의 변경이 다른 쪽을 덮어쓰지 않습니다.

moai mcp-server가 노출하는 17개 도구는 다섯 그룹으로 나뉩니다. 호출 시점에는 모두 mcp__moai__ 접두사가 붙습니다.

plan-phase(manager-spec이 새 SPEC을 저작할 때, 시대 분류와 드리프트 확인)와 sync-phase(manager-docs가 라이프사이클 종결을 검증할 때)에서 쓰입니다. plan-auditor는 spec_audit / spec_drift로 plan-phase 회의적 검토를 수행합니다.

manager-develop가 run-phase 자가 검증(이음매 §E)에서 쓰며, sync-auditor와 super-advisor는 추이를 검토합니다. verify_snapshot은 HEAD 다이제스트를 키로 하는 스냅샷을 읽거나 기록하고, verify_trend는 수렴 판단을 위한 이력을 드러냅니다.

goal_arm은 오케스트레이터 전용입니다 — 자율 루프 무장은 오케스트레이터 관심사이므로 에이전트 안에서 호출하지 않습니다. 평면 계층 무장 표면을 보존하기 위한 설계입니다. goal_status는 manager-develop / manager-kanban가 무장된 조건의 진행을 읽는 채널이고, session_list는 manager-kanban가 팬아웃 전 동일 체크아웃의 동시 세션을 감지하는 경쟁 완화 수단입니다.

단일 백엔드 감사 모드는 프로젝트의 audit_model 설정으로 결정합니다: codex+glm(기본값, audit_multi로 수렴) | glm | codex | none(Claude 단독, 백엔드 호출 없음). 모든 백엔드는 fail-open입니다 — 사용 불가 백엔드는 inconclusive를 반환하며, Go error가 아닙니다.

codex 위임 도구군은 super-advisor에 배선되어 있습니다 — 수시 고추론 자문 에이전트가 백그라운드 교차 모델 위임의 자연스러운 소비자이기 때문입니다. codex_task로 작업을 위임하고, codex_job_status / codex_job_result로 완료를 폴링하고, codex_job_cancel로 중단합니다. codex는 선택적(optional)입니다 — 누락되거나 사용 불가면 fail-open inconclusive를 반환하며, hard error가 아닙니다.

에이전트의 tools: 목록에 MCP 도구가 있으면 CLI보다 MCP 경로를 우선합니다. 두 경로는 같은 구현을 뒤에서 실행합니다. MCP 경로가 유리한 이유는 세 가지입니다:

• 구조화된 출력을 반환한다 (파싱이 필요 없다)
• shell-quoting 위험을 피한다
• 서브에이전트에서 Bash가 제한될 수 있는 환경에서 저지연으로 동작한다

CLI는 MCP 도구가 tools: 목록에 없거나, 메인 세션에서 CLI 형태가 더 자연스러울 때만 씁니다.

GLM 세션(moai glm 또는 moai cg의 GLM 패널)에서 실행하면, 웹 검색과 웹 조회가 내장 WebSearch / WebFetch 대신 z.ai MCP 도구로 라우팅됩니다. 인증은 ~/.moai/.env.glm에서 읽어옵니다.

z.ai MCP 서버(zai-mcp-server, web_search_prime, web_reader)는 기본으로 비활성이며, GLM 세션에서 moai glm tools enable로 켭니다. GLM 세션에서의 라우팅 규칙은 다중 LLM 백엔드를 참조하세요.

codex 감사 / 위임 도구(codex_audit, codex_task 등)는 ~/.codex/auth.json에서 인증 자격을 읽습니다. codex는 선택적입니다 — 인증 파일이 없거나 codex가 설치되지 않았으면, 관련 도구는 inconclusive를 반환하고 계속 진행합니다. 에이전트 작업이 codex 가용성에 매이지 않는 설계입니다.

GLM, codex, Claude — 세 백엔드 모두 fail-open 원칙을 따릅니다. 사용 불가한 백엔드는 inconclusive를 반환할 뿐, Go error를 일으키지 않습니다. 하나의 백엔드가 빠져도 나머지로 감사가 수렴하며, 아무 백엔드도 없으면 Claude 단독으로 동작합니다(audit_model: none).

codex 위임 도구 가운데 codex_task는 background: true로 백그라운드 작업을 시작할 수 있습니다. 이 경우 작업이 끝날 때까지 대기하지 않고 즉시 작업 ID를 반환합니다.

진행 상태는 두 도구로 폴링합니다:

codex_task(background=true) ──▶ 작업 ID 반환
       │
       ├── codex_job_status(작업 ID) ──▶ 실행 중 / 완료 / 실패
       │
       └── codex_job_result(작업 ID) ──▶ 완료 시 출력 읽기

필요하면 codex_job_cancel(작업 ID) ──▶ 중단

MCP 콘솔(웹 콘솔)에서 각 도구별 설정과 인증 상태를 확인할 수 있습니다. 자세한 콘솔 기능은 웹 콘솔을 참조하세요.

MoAI 자체 MCP 서버도 Claude Code 일반 MCP와 같은 지연 로드 원칙을 따릅니다. 도구 정의 전체를 컨텍스트에 상시 로드하면 컨텍스트 윈도우가 빠르게 차므로, 평소에는 짧은 메타데이터만 두고 실제 호출 시점에 스키마를 불러옵니다.

지연 도구를 호출하려면 먼저 ToolSearch로 스키마를 활성 컨텍스트로 불러와야 합니다.

도구가 필요해짐 ──▶ {스키마가 컨텍스트에 있는가?}
                           │
                    ┌──────┴──────┐
                    아니오          예
                    │              │
            ToolSearch로          도구 호출
            스키마 선행 로드
                    │
                    └──▶ 도구 호출

이 절차를 건너뛰면 도구 호출이 검증 오류로 거부됩니다. 지연 로드 원리에 대한 배경 설명은 Claude Code 일반 MCP 문서의 “지연 로드와 Tool Search” 절을 참조하세요.

• Claude Code 일반 MCP — 플랫폼 자체 MCP 통합 (USB 포트 비유, 서버 등록, 전송 타입, /mcp 명령)
• 다중 LLM 백엔드 — Claude × GLM 다중 백엔드 운용 · GLM 세션에서 웹 검색/조회가 z.ai MCP 도구로 라우팅되는 규칙
• 교차 모델 감사 — 다중 감사자 수렴 메커니즘
• 웹 콘솔 — MCP 도구별 설정 및 인증 표면