Subagent MCP

독립적인 하네스. 하나의 Codex 오케스트레이터.

한 모델이 변경 사항을 계획하고, 구현하고, 검토할 때, 검토자는 작성자의 맥락과 맹점을 공유하게 됩니다. 결국 자신의 계획을 검증하는 대신 확정해버릴 수 있습니다.

Subagent MCP는 Codex를 메인 에이전트이자 최종 의사 결정자로 유지하면서, 제한된 작업을 외부 에이전트 런타임에 위임합니다. 각 런타임은 고유 하네스와 결합된 모델로, Codex는 서로 다른 맥락과 가정을 가진 독립적인 모델로부터 구현이나 검토를 받을 수 있습니다.

이를 통해 Codex의 효과적인 서브에이전트 풀이 확장되며, 이미 보유한 제공업체 할당량을 활용할 수 있습니다. Subagent MCP는 사용량 크레딧이나 유료 초과분을 활성화하거나, 구매하거나, 자동 재충전하거나, 묵시적으로 동의하지 않습니다.

어댑터는 모든 네이티브 하네스를 동일한 수명 주기(위임, 관찰, 조정, 종료)로 변환합니다. 코어는 제공업체 역할이나 모델 이름을 하드코딩하지 않습니다.

안정 버전: 1.0.14는 Windows를 대상으로 합니다. MCP, 패키지, localhost UI, 그리고 Claude Code 및 DeepSeek 네이티브 하네스 통합이 준비되었습니다.

런타임 상태

• Claude Code — 준비 완료. 네이티브 Claude Code 하네스, 제공업체 네이티브 모델 및 추론 설정, 구독 OAuth ID, 그리고 출력을 수락하기 전의 실시간 무-초과 증거를 사용합니다.

• DeepSeek Harness — 준비 완료. 제한된 작업에 네이티브 ACP 전송과 하네스 게시 모델 카탈로그를 사용합니다. MCP 재시작 후 재개, 정확한 제공업체 할당량 증거, 대화형 입력, 선언된 MCP는 여전히 명시적 기능 격차로 남아 있습니다.

다른 런타임은 아직 지원되지 않습니다. 향후 런타임은 코어의 제공업체별 분기가 아닌 어댑터를 사용합니다.

Related MCP server: AI Knowledge Center MCP

빠른 시작

1. 설치

필요한 경우 uv를 설치한 다음, 정확한 격리 릴리스를 등록하고 백그라운드 UI를 시작합니다:

winget install --id=astral-sh.uv -e
codex mcp add subagent-mcp -- uvx --isolated --from subagent-harness-mcp==1.0.14 subagent-harness-mcp serve
uvx --isolated --from subagent-harness-mcp==1.0.14 subagent-harness-mcp ui --background

등록 후 새 Codex 작업을 시작하세요.

2. 런타임 구성

브라우저에서 http://127.0.0.1:8765을 여세요. 백그라운드 UI가 중지된 경우, 동일한 정확한 릴리스를 다시 시작하세요:

uvx --isolated --from subagent-harness-mcp==1.0.14 subagent-harness-mcp ui --background

설정 및 읽기 전용 활동 UI는 고정 루프백 포트에 유지되며 활성 MCP 연결에 의존하지 않습니다.

현재 및 최근 활동은 외부 에이전트별로 나열됩니다. 행을 선택하면 해당 모델, 네이티브 하네스, 작업 공간, 권한, 쓰기 세트, 현재 단계, 수명 주기, 경과 시간, 그리고 편집된 터미널 결과를 검사할 수 있습니다. 프롬프트, 대화 기록, 숨은 사고 과정, 원시 제공업체 이벤트는 절대 표시되지 않습니다.

3. 위임

Codex에 평이한 언어로 요청하세요:

Subagent MCP를 사용하여 외부 에이전트에게 이 변경 사항을 검토하도록 요청한 다음, 그 결과를 독립적으로 평가하세요.

Codex는 무엇을 위임할지 선택하고, 결과를 관찰하며, 최종 판단을 유지합니다. 수명 주기 응답은 기본적으로 간결합니다. 전체 편집 보고서는 로컬 제품 상태에 남아 있으며, 나중에 해시 바인딩 참조로 읽거나 전달할 수 있습니다.

모델 및 폴백 순서

각 네이티브 하네스는 자체 모델 선택을 게시합니다. UI는 친숙한 이름과 순서가 지정된 우선순위 스택을 표시하며, 정확한 제공업체 ID는 고급 경로에서 계속 사용할 수 있습니다.

제공업체가 할당량 또는 크레딧 소진(QUOTA_PAUSED)을 명시적으로 보고하면, Subagent MCP는 해당 정확한 모델을 향후 작업을 위해 목록 맨 아래로 이동합니다. 실패한 작업을 재시도하지는 않습니다. 모호한 실패, 충돌, 시간 초과는 모델 순서를 변경하거나 추가 유료 요청을 트리거하지 않습니다.

실패한 작업은 종료 상태로 유지되지만, 다음 명시적 위임 시 제공업체를 다시 실시간으로 확인합니다. 캐시된 재설정 시계나 대기 체크포인트가 이 확인을 대체하지 않습니다. 네이티브 하네스가 안전한 사전 요청 할당량 엔드포인트를 노출하지 않으면, 상태는 소진으로 추정되지 않고 알 수 없음으로 유지됩니다.

운영 복구는 세 가지 작업으로 제한됩니다. 로컬 상태 작업 또는 명시적으로 재시도 가능한 사전 제공업체 실패만 재시도할 수 있습니다. 이미 실패한 제공업체 작업은 자동으로 다시 전송되지 않습니다.

DeepSeek 경로는 사용자가 승인한 기존 구독, 무제한 제공, 또는 충전된 잔액을 사용할 수 있습니다. Subagent MCP는 해당 잔액을 구매하거나, 재충전하거나, 증가시키지 않습니다.

동시 작성자

쓰기 작업은 write_set에 최대 32개의 저장소 상대 파일 또는 디렉터리 루트를 선언할 수 있습니다. 외부 작성자는 정규화된 절대 집합이 서로 분리된 경우 동시에 실행될 수 있습니다. 동일한 경로와 부모/자식 경로는 충돌합니다. 작업 및 레인 이름은 잠금에 영향을 주지 않습니다.

write_set을 생략하면 하위 호환성을 위해 실행에 전체 작업 공간이 부여됩니다. 각 어댑터는 네이티브 하네스 경계에서 정규화된 경로도 강제합니다. 현재 DeepSeek Harness 네이티브 세션은 하나의 쓰기 가능한 루트를 허용합니다. 다중 루트 작업은 확장되지 않고 컨트롤러에 의해 여러 개의 분리된 작성자 호출로 분해됩니다. 진정한 단일 세션 다중 루트는 공식 ACP additionalDirectories를 광고하고 네이티브로 강제하는 향후 하네스를 위해 예약되어 있습니다. 이러한 임대는 Subagent MCP 실행을 조정합니다. 관련 없는 로컬 프로세스를 위한 운영 체제 샌드박스가 아닙니다.

구성 방식

flowchart LR
    C["Codex<br/>Main agent & orchestrator"]
    M["Subagent MCP<br/>Gateway"]
    UI["Localhost UI<br/>Settings & activity"]

    C -->|"delegate · steer · observe"| M
    UI --> M

    subgraph E["External agent runtimes — adapter-driven"]
        R1["Model<br/>+<br/>native harness"]
        R2["Model<br/>+<br/>native harness"]
        RN["Future runtimes<br/>via adapters"]
    end

    M -->|"normalized lifecycle"| R1
    M -->|"normalized lifecycle"| R2
    M -->|"normalized lifecycle"| RN

Subagent MCP는 수명 주기 정규화, 상태, 편집, 임대, 회로를 담당합니다. 각 어댑터는 해당 계약을 네이티브 하네스로 변환합니다. 전체 계약은 Architecture를 참조하세요.

Windows에서 업데이트 또는 롤백

아직 실행 중일 수 있는 환경을 재설치하지 않고 버전을 전환하세요. 첫 번째 명령은 소스 버전을 사용하고, 추가/시작 명령은 대상 버전을 사용합니다. 이 예시는 1.0.13에서 1.0.14로 업그레이드합니다:

uvx --isolated --from subagent-harness-mcp==1.0.12 subagent-harness-mcp ui --stop
codex mcp remove subagent-mcp
codex mcp add subagent-mcp -- uvx --isolated --from subagent-harness-mcp==1.0.14 subagent-harness-mcp serve
uvx --isolated --from subagent-harness-mcp==1.0.14 subagent-harness-mcp ui --background

항목을 변경한 후 새 Codex 작업을 시작하세요. 기존 작업은 종료될 때까지 이전 런타임을 유지합니다. 정확한 버전을 반대로 하여 동일한 시퀀스를 사용하면 롤백됩니다.

UPDATE_QUARANTINED를 보고하는 이미 실행 중인 MCP는 교체를 안전하게 핫로드할 수 없습니다. 해당 상주 프로세스를 재시도하지 마세요. 네이티브 폴백으로 마무리하고 새 작업에서 새 정확한 등록을 사용하세요.

직접 subagent-harness-mcp serve 항목에서 일회성 마이그레이션의 경우, 먼저 등록을 교체하고 레거시 작업이 자연스럽게 종료되도록 하세요. 교체 후, 선택적으로 더 이상 사용하지 않는 영구 도구를 제거하기 전에 모든 Codex 창을 한 번 닫으세요. 위의 모든 새 명령이 uvx --isolated를 사용하므로 설치된 상태로 두는 것은 안전합니다.

Subagent MCP는 Codex 구성을 편집하거나, Codex/제공업체 프로세스를 종료하거나, uv 캐시를 자체적으로 지우지 않습니다.

안전 및 결제

• Subagent MCP는 사용량 크레딧을 활성화하거나 결제 설정을 변경하지 않습니다.

• Claude 작업은 포함된 구독 할당량을 소비할 수 있습니다. 각 작업은 바인딩된 CLI, 구독 인증, 자격 증명 우선순위, 제어 연결을 검증한 다음, 출력을 수락하기 전에 동일한 응답에서 안전한 요금 증거를 요구합니다.

• Provider Refresh는 모델 프롬프트를 전송하지 않습니다. 네이티브 하네스가 응답 전에 정확한 요금 증거를 노출할 수 없으면, 할당량 결과를 만들어내거나 재설정 시계를 사용하는 대신 상태는 알 수 없음으로 유지됩니다.

• 폴백은 명시적 할당량 소진 후에만 발생합니다. 안전하지 않거나 모호한 증거는 추가 유료 요청을 절대 트리거하지 않습니다.

• 네이티브 대화 기록은 네이티브 하네스가 소유합니다. 제품 상태는 명시적 로컬 루트에 유지되며, 에이전트 출력은 신뢰할 수 없는 조언으로 취급해야 합니다.

쓰기 액세스를 활성화하기 전에 Security 및 Threat model을 읽으세요.

프로젝트

• Architecture

• Adapter authoring

• Contributing

• Changelog

• MIT License