공개 문서
learn/canonical/knot/CODEX-HARNESS-MCP-PROFILE.md
아래는 learn/canonical/knot/CODEX-HARNESS-MCP-PROFILE.md 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
# Codex flavor — Harness MCP 프로필
> **대상**: `multi-agent-codex/` (Codex = 오케스트레이터)
> **목적**: 하네스에 불필요한 전역 MCP 연결 시도를 제거해 시작 로그·지연·크래시를 줄인다.
---
## 심층 분석 요약
### Codex flavor는 MCP가 필수가 아님
| 역할 | 호출 방식 | MCP 필요? |
|------|-----------|-----------|
| **Orchestrator** | Codex 세션 (`AGENTS.md`) | ❌ |
| **codex-main** | Codex **native subagent** | ❌ |
| **claude-critic** | `claude -p` **CLI** (작업별 승인) | ❌ |
| **gemini** | `agy` **CLI** (`call_worker.sh`) | ❌ |
정본: `templates/codex/_shared/backends.json` — `call_type: native | cli` 만 사용.
프로젝트 설치본(`multi-agent-codex/`)에는 **`.mcp.json` / MCP 설정 파일이 없음**.
### 전역 `~/.codex/config.toml` MCP는 하네스와 분리됨
Codex 앱/CLI가 부팅할 때 `mcp_servers.*` 와 플러그인 MCP를 **전역으로** 올린다.
이것은 Cursor·SaaS 등 **다른 워크플로용 통합**이며, 멀티에이전트 codex flavor **태스크 실행과 무관**하다.
스크린샷에 나온 실패 MCP:
| MCP | 원인 | 하네스 대안 |
|-----|------|-------------|
| **bkit-analysis / bkit-pdca** | bkit 플러그인(Claude Code 전용) | bkit 스킬은 Codex에서 읽기만 가능; MCP 불필요. PDCA는 파일 기반 `tasks/` |
| **playmcp** | 외부 스크립트 경로 의존 | `call_worker.sh` + worker brief |
| **perplexity-ask** | `PERPLEXITY_API_KEY` 미설정 | 웹 검색 CLI, 또는 orchestrator가 직접 조사(승인 후) |
| **notion** | `NOTION_API_TOKEN` 미설정 | `sources/` 에 markdown보내기 |
| **supabase** | `SUPABASE_ACCESS_TOKEN` 미설정 | 프로젝트 DB는 target_repo 앱에서 직접 |
| **notebooklm-mcp** | 프로세스 hang (53s+) | NotebookLM 웹 UI 직접; 하네스 무관 |
### 시작 시간 기준
| MCP 수 | 체감 |
|--------|------|
| **12개** (prune 전) | 1분+ — `notebooklm-mcp` 등이 마지막까지 hang |
| **3개** (harness-minimal) | 수 초 — `node_repl`, `codex`, `vercel`만 |
Codex는 등록된 **모든** MCP를 세션 시작 시 기동한다. 하네스에 불필요한 항목이 있으면 **정상이 아닌 긴 대기**가 발생한다.
---
| Host flavor | Codex MCP 필요? | 비고 |
|-------------|-----------------|------|
| **codex** (`multi-agent-codex`) | **No** | native + CLI |
| **cursor** (`multi-agent-cursor`) | **Yes** — `.cursor/mcp.json` 의 `codex` 1개 | worker 호출 primary |
| **claude** | **Yes** — `.mcp.json` 의 `codex` | critique primary |
| **antigravity** | **No** | Codex CLI primary |
---
## 권장 프로필 (harness-minimal)
### 유지
| 항목 | 이유 |
|------|------|
| `node_repl` | Codex 번들 (브라우저 플러그인) |
| `codex` (`mcp-server`) | Cursor host가 Codex worker 호출 시 사용 |
| `vercel` | OAuth 연결 시 배포 작업용 (선택) |
### 제거 / 비활성
| 항목 | 방법 |
|------|------|
| `playmcp`, `perplexity-ask`, `notion`, `supabase` | `codex mcp remove <name>` |
| `bkit@bkit-marketplace` | `config.toml` → `enabled = false` |
| `slack@claude-plugins-official` | 이미 `enabled = false` 권장 |
---
## 적용 방법
```bash
chmod +x tools/codex/prune-global-mcp-for-harness.sh
# 미리보기
bash tools/codex/prune-global-mcp-for-harness.sh --dry-run
# 기본 prune (실패·느린 MCP + bkit 비활성) — harness-minimal: node_repl + codex + vercel
bash tools/codex/prune-global-mcp-for-harness.sh
```
백업: `~/.codex/config.toml.harness-prune-backup-<timestamp>`
복구:
```bash
cp ~/.codex/config.toml.harness-prune-backup-<timestamp> ~/.codex/config.toml
```
Codex 재시작: 세션에서 `/quit` → `codex`
---
## Cursor host 사용자
codex flavor만 쓸 때 전역 MCP를 prune해도 **Cursor harness**에는 영향 없음.
Cursor는 **프로젝트** `.cursor/mcp.json` (또는 Cursor UI MCP)을 사용한다.
Cursor에서 codex worker가 필요하면:
1. `.cursor/mcp.json` 에 `codex` stdio 서버 유지
2. Cursor MCP UI에서 Connected 확인
3. 실패 시 `call_worker.sh codex` CLI fallback (`operator-runbook.md`)
---
## 관련 문서
- `multi-agent-system/docs/learn/chapters/07-four-flavors.md` — flavor별 MCP
- `multi-agent-system/docs/learn/lab/practice/ch02-post-install-lab.md` — codex flavor는 `.cursor/mcp.json` 비필수
- `multi-agent-system/runs/run-038-phase59-codex-mcp-connection-check/` — MCP 실패 분류
공개 문서 변환 코드 (HTML)
<h1>Codex flavor — Harness MCP 프로필</h1>
<blockquote>
<p><strong>대상</strong>: <code>multi-agent-codex/</code> (Codex = 오케스트레이터)<br><strong>목적</strong>: 하네스에 불필요한 전역 MCP 연결 시도를 제거해 시작 로그·지연·크래시를 줄인다.</p>
</blockquote>
<hr>
<h2>심층 분석 요약</h2>
<h3>Codex flavor는 MCP가 필수가 아님</h3>
<table>
<thead>
<tr>
<th>역할</th>
<th>호출 방식</th>
<th>MCP 필요?</th>
</tr>
</thead>
<tbody><tr>
<td><strong>Orchestrator</strong></td>
<td>Codex 세션 (<code>AGENTS.md</code>)</td>
<td>❌</td>
</tr>
<tr>
<td><strong>codex-main</strong></td>
<td>Codex <strong>native subagent</strong></td>
<td>❌</td>
</tr>
<tr>
<td><strong>claude-critic</strong></td>
<td><code>claude -p</code> <strong>CLI</strong> (작업별 승인)</td>
<td>❌</td>
</tr>
<tr>
<td><strong>gemini</strong></td>
<td><code>agy</code> <strong>CLI</strong> (<code>call_worker.sh</code>)</td>
<td>❌</td>
</tr>
</tbody></table>
<p>정본: <code>templates/codex/_shared/backends.json</code> — <code>call_type: native | cli</code> 만 사용.<br>프로젝트 설치본(<code>multi-agent-codex/</code>)에는 <strong><code>.mcp.json</code> / MCP 설정 파일이 없음</strong>.</p>
<h3>전역 <code>~/.codex/config.toml</code> MCP는 하네스와 분리됨</h3>
<p>Codex 앱/CLI가 부팅할 때 <code>mcp_servers.*</code> 와 플러그인 MCP를 <strong>전역으로</strong> 올린다.<br>이것은 Cursor·SaaS 등 <strong>다른 워크플로용 통합</strong>이며, 멀티에이전트 codex flavor <strong>태스크 실행과 무관</strong>하다.</p>
<p>스크린샷에 나온 실패 MCP:</p>
<table>
<thead>
<tr>
<th>MCP</th>
<th>원인</th>
<th>하네스 대안</th>
</tr>
</thead>
<tbody><tr>
<td><strong>bkit-analysis / bkit-pdca</strong></td>
<td>bkit 플러그인(Claude Code 전용)</td>
<td>bkit 스킬은 Codex에서 읽기만 가능; MCP 불필요. PDCA는 파일 기반 <code>tasks/</code></td>
</tr>
<tr>
<td><strong>playmcp</strong></td>
<td>외부 스크립트 경로 의존</td>
<td><code>call_worker.sh</code> + worker brief</td>
</tr>
<tr>
<td><strong>perplexity-ask</strong></td>
<td><code>PERPLEXITY_API_KEY</code> 미설정</td>
<td>웹 검색 CLI, 또는 orchestrator가 직접 조사(승인 후)</td>
</tr>
<tr>
<td><strong>notion</strong></td>
<td><code>NOTION_API_TOKEN</code> 미설정</td>
<td><code>sources/</code> 에 markdown보내기</td>
</tr>
<tr>
<td><strong>supabase</strong></td>
<td><code>SUPABASE_ACCESS_TOKEN</code> 미설정</td>
<td>프로젝트 DB는 target_repo 앱에서 직접</td>
</tr>
<tr>
<td><strong>notebooklm-mcp</strong></td>
<td>프로세스 hang (53s+)</td>
<td>NotebookLM 웹 UI 직접; 하네스 무관</td>
</tr>
</tbody></table>
<h3>시작 시간 기준</h3>
<table>
<thead>
<tr>
<th>MCP 수</th>
<th>체감</th>
</tr>
</thead>
<tbody><tr>
<td><strong>12개</strong> (prune 전)</td>
<td>1분+ — <code>notebooklm-mcp</code> 등이 마지막까지 hang</td>
</tr>
<tr>
<td><strong>3개</strong> (harness-minimal)</td>
<td>수 초 — <code>node_repl</code>, <code>codex</code>, <code>vercel</code>만</td>
</tr>
</tbody></table>
<p>Codex는 등록된 <strong>모든</strong> MCP를 세션 시작 시 기동한다. 하네스에 불필요한 항목이 있으면 <strong>정상이 아닌 긴 대기</strong>가 발생한다.</p>
<hr>
<table>
<thead>
<tr>
<th>Host flavor</th>
<th>Codex MCP 필요?</th>
<th>비고</th>
</tr>
</thead>
<tbody><tr>
<td><strong>codex</strong> (<code>multi-agent-codex</code>)</td>
<td><strong>No</strong></td>
<td>native + CLI</td>
</tr>
<tr>
<td><strong>cursor</strong> (<code>multi-agent-cursor</code>)</td>
<td><strong>Yes</strong> — <code>.cursor/mcp.json</code> 의 <code>codex</code> 1개</td>
<td>worker 호출 primary</td>
</tr>
<tr>
<td><strong>claude</strong></td>
<td><strong>Yes</strong> — <code>.mcp.json</code> 의 <code>codex</code></td>
<td>critique primary</td>
</tr>
<tr>
<td><strong>antigravity</strong></td>
<td><strong>No</strong></td>
<td>Codex CLI primary</td>
</tr>
</tbody></table>
<hr>
<h2>권장 프로필 (harness-minimal)</h2>
<h3>유지</h3>
<table>
<thead>
<tr>
<th>항목</th>
<th>이유</th>
</tr>
</thead>
<tbody><tr>
<td><code>node_repl</code></td>
<td>Codex 번들 (브라우저 플러그인)</td>
</tr>
<tr>
<td><code>codex</code> (<code>mcp-server</code>)</td>
<td>Cursor host가 Codex worker 호출 시 사용</td>
</tr>
<tr>
<td><code>vercel</code></td>
<td>OAuth 연결 시 배포 작업용 (선택)</td>
</tr>
</tbody></table>
<h3>제거 / 비활성</h3>
<table>
<thead>
<tr>
<th>항목</th>
<th>방법</th>
</tr>
</thead>
<tbody><tr>
<td><code>playmcp</code>, <code>perplexity-ask</code>, <code>notion</code>, <code>supabase</code></td>
<td><code>codex mcp remove <name></code></td>
</tr>
<tr>
<td><code>bkit@bkit-marketplace</code></td>
<td><code>config.toml</code> → <code>enabled = false</code></td>
</tr>
<tr>
<td><code>slack@claude-plugins-official</code></td>
<td>이미 <code>enabled = false</code> 권장</td>
</tr>
</tbody></table>
<hr>
<h2>적용 방법</h2>
<pre><code class="language-bash">chmod +x tools/codex/prune-global-mcp-for-harness.sh
# 미리보기
bash tools/codex/prune-global-mcp-for-harness.sh --dry-run
# 기본 prune (실패·느린 MCP + bkit 비활성) — harness-minimal: node_repl + codex + vercel
bash tools/codex/prune-global-mcp-for-harness.sh
</code></pre>
<p>백업: <code>~/.codex/config.toml.harness-prune-backup-<timestamp></code></p>
<p>복구:</p>
<pre><code class="language-bash">cp ~/.codex/config.toml.harness-prune-backup-<timestamp> ~/.codex/config.toml
</code></pre>
<p>Codex 재시작: 세션에서 <code>/quit</code> → <code>codex</code></p>
<hr>
<h2>Cursor host 사용자</h2>
<p>codex flavor만 쓸 때 전역 MCP를 prune해도 <strong>Cursor harness</strong>에는 영향 없음.<br>Cursor는 <strong>프로젝트</strong> <code>.cursor/mcp.json</code> (또는 Cursor UI MCP)을 사용한다.</p>
<p>Cursor에서 codex worker가 필요하면:</p>
<ol>
<li><code>.cursor/mcp.json</code> 에 <code>codex</code> stdio 서버 유지</li>
<li>Cursor MCP UI에서 Connected 확인</li>
<li>실패 시 <code>call_worker.sh codex</code> CLI fallback (<code>operator-runbook.md</code>)</li>
</ol>
<hr>
<h2>관련 문서</h2>
<ul>
<li><code>multi-agent-system/docs/learn/chapters/07-four-flavors.md</code> — flavor별 MCP</li>
<li><code>multi-agent-system/docs/learn/lab/practice/ch02-post-install-lab.md</code> — codex flavor는 <code>.cursor/mcp.json</code> 비필수</li>
<li><code>multi-agent-system/runs/run-038-phase59-codex-mcp-connection-check/</code> — MCP 실패 분류</li>
</ul>