deepseek-subagent-mcp

Claude Code, Codex, 또는 다른 MCP 클라이언트에게 DeepSeek Harness 에이전트를 위임할 수 있는 기능을 제공합니다. 이는 자체 서브에이전트에게 업무를 위임하는 방식과 같습니다.

MCP(Model Context Protocol)는 코딩 에이전트가 외부 도구를 로드하는 표준입니다. DeepSeek Harness는 DeepSeek의 오픈소스 에이전트 런타임으로, 파일 및 셸 도구를 사용하여 루프에서 모델을 실행합니다. 2026년 8월 MIT 라이선스로 출시되었습니다. 이 서버는 그 사이에 위치합니다: 별도 프로세스에서 Harness 에이전트를 실행하고, 시작, 모니터링, 계속, 중지를 위한 6개의 도구를 노출합니다.

하위 에이전트는 자체 컨텍스트 창을 가집니다. 이것이 핵심입니다 — 자체 포함된 작업을 전달하면, 파일을 처리하면서 자체 토큰을 소비하고, 결과를 트랜스크립트 대신 반환합니다.

요구 사항

• Python 3.11 이상

• platform.deepseek.com의 DeepSeek API 키

• Apple Silicon의 macOS 14+ 또는 x86-64/arm64 Linux

Node.js 설치는 필요하지 않습니다: Harness 런타임은 deepseek-harness-sdk 휠 내부에 자체 포함 실행 파일로 제공됩니다. 해당 휠은 또한 플랫폼 제한이 있습니다 — macosx_14_0_arm64, manylinux_2_28_x86_64 및 manylinux_2_28_aarch64만 게시하며, 그 외에는 게시되지 않으므로 Windows, Intel Mac, macOS 13에서는 전혀 설치할 수 없습니다.

설치

uvx --from git+https://github.com/gaztrabisme/deepseek-subagent-mcp deepseek-subagent-mcp

Claude Code

프로젝트의 .mcp.json에 추가하거나, 모든 프로젝트에 대해 ~/.claude.json에 추가합니다:

{
  "mcpServers": {
    "deepseek-subagent": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/gaztrabisme/deepseek-subagent-mcp",
        "deepseek-subagent-mcp"
      ],
      "env": {
        "DEEPSEEK_API_KEY": "sk-...",
        "DSA_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}

Codex

~/.codex/config.toml에 추가:

[mcp_servers.deepseek-subagent]
command = "uvx"
args = ["--from", "git+https://github.com/gaztrabisme/deepseek-subagent-mcp", "deepseek-subagent-mcp"]
env = { DEEPSEEK_API_KEY = "sk-...", DSA_WORKSPACE = "/path/to/your/project" }

도구

실행은 기본적으로 비동기식입니다. 코딩 작업은 몇 분이 걸릴 수 있고 MCP 클라이언트는 개별 도구 호출에 타임아웃이 있기 때문입니다. dsh_delegate는 작업이 대기열에 추가되는 즉시 반환됩니다. dsh_await는 대기하고 진행 상황을 보고합니다. 짧은 작업의 경우 dsh_delegate에 wait_seconds를 전달하고 두 번째 호출을 건너뛸 수 있습니다.

각 dsh_delegate는 하나의 에이전트를 생성하며, 하나의 런타임 프로세스와 하나의 지속 세션을 유지합니다. dsh_continue는 해당 세션에 다시 진입하므로 하위 에이전트는 이전 턴을 컨텍스트로 유지합니다.

모든 위임은 검증 방법을 명시합니다

dsh_delegate는 verification 인수를 필수로 요구합니다: 작업 완료를 증명하는 명령입니다.

dsh_delegate(task="Fix the failing date parser", verification="pytest -q tests/test_dates.py")

서버는 하위 에이전트가 완료된 후, 에이전트 작업 공간에서 해당 명령을 자체 실행합니다. 하위 에이전트가 자체 테스트 결과를 보고하는 것은 주장(claim)입니다. 종료 코드는 사실(fact)이며, 에이전트가 조기에 승리를 선언하는 것은 잘 문서화된 실패 모드입니다.

명령은 하위 에이전트의 자체 호출을 제어하는 동일한 정책으로 분류됩니다 — 호출자는 다른 에이전트이며 프롬프트 인젝션이 가능하므로, "호출자가 요청했으므로"는 권한 부여가 아닙니다. 진정으로 확인할 것아 없을 때는 verification="true"를 전달하십시오; 명백한 거짓말이 목목 기본값보다 낫습니다.

반환되는 내용

전체 트랜스크립트를 반환하는 서브에이전트는 그 목적을 상실합니다. 하위 에이전트의 답변의 크기가 DSA_SUMMARY_TOKENS보다 클 경우, 동일한 세션에서 — 한 번의 추가 른으로 — 7개 섹션으로 대체 요청을 받습니다: 목표, 제약 및 선호 사항, 진척 상황, 주요 결정, 다음 단계, 관련 파일, 중요 컨텍스트. 이 내용이 MCP 경계를 넘어갑니다.

임계값 미만의 답변은 그대로 반환되며 추가 턴 비용이 들지 않습니다. 원시 응답은 항상 보존됩니다: ds_h_transcript(run_id, raw=True).

감독 실행

하위 에에전트의 도구 호출은 실행 전에 게이트됩니다. 런타임 내부의 P_reeToolUse 크가 각 제안된 호출을 이 서버에 전달하면, 서버는 허용 또 거부를 답변합니다; 거부된 호출은 차단된 도구 결과(이유 포함)로 모델에 반환되며, 모델은 적응합니다.

결정적 분류기가 먼저 결정하며, 대부분의 호출을 결정합니다. 파일 읽기, ls, grep, 버전 관리 읽기, 작업 공간 자체 코드 및 테스트 실행은 모델 개입 없이 허용됩니다. 권한 명령, 작업 공간 밖의 삭제, 셸로 파이핑된 페치, SSH 키나 .env를 건드리는 모든 것(무해해 보이는 동사 포함, cat ~/.ssh/id_rsa는 비밀에 적용된 읽기 전용 도구이기 때문에)은 절대 거부됩니다. 분류기가 분류할 수 없는 것만 상위로 이관됩니다.

상위 이관은 클라이언트가 지원하는 최상위 계층에서 실행되며, 시작 시 결정되고 ds_h_list에 의해 보고됩니다:

모든 계층은 실패 시 차단됩니다. 도달할 수 없는 감독자, 시간 초과, 잘못된 요청, 또는 두 기능을 모두 지원하지 않는 클라언트는 모드 승인이 아닌 거부를 생합니다.

사다리는 한 번 선택되지 않고 순차적으로 탐색됩니다: 오류가 발생한 계층은 다음 계층으로 넘어갑니다. 따라서 샘플링을 지원하지 않는 클라언트(2026-07-28 스펙 개정에서 폐기되었지만 오늘날까지 작동)는 모든 것을 거부하지 않고 사용자에게 문의하는 쪽으로 저하됩니다. 시간 초과된 계층은 넘어가지 않습니다. 답변 없는 질문은 '아니오'이며, 다른 채널에서 다시 묻는 대기 시간만 두 배가 됩니다.

DSA_SUPERVISOR=off로 설저정하여 게이트를 완전히 비활성화합니다.

감독자에게 표시되는 것은 구조화된 사실이며, 하위 에이전트의 산문이 아닙니다: 도구, 각 파이프라인 세그먼트의 프로그램, 명령이 이름을 지은 작얍 공간 내/외 플래그가 있는 모든 경로. 하위 에이전트는 명령과 그 정당성을 모두 작성하며, 자신의 사례를 주장할 수 있는 하위 에이전트는 주장할 것입니다. 정적으로 결저할 수 없는 경로($TMPDIR/out.txt)는 추축되지 않고 미결저로 보고되며, 외부로 간주합니다.

exmples/cleude_supervisor.py는 실제 Claude에 대해 전체 패턴을 실행합니다. sampling을 자체적으로 광고하지 않는 클라이언트를 위해:

DEEPSEEK_API_KEY=sk-... uv run python examples/claude_supervisor.py

상한 및 비용

위임된 에이전트는 루프에서 자금을 소비합니다. 따라서 4개의 독립적인 상한이 이를 제한하며, 각 실행은 사용된 비용을 보고합니다.

중간 턴 취소는 와이어 상에서 없으므로 모든 중지는 프로세스 종료입니다. 상한에 의한 중지는 항상 실행 자체가 보고한 것보다 우선합니다: 종료된 프로세스의 출력은 절대 성공으로 읽히지 않습니다.

dsh_delegate, dsh_await 및 dsh_list는 모두 토큰 사용량(입력, 출력, 캐시 읽기 및 쓰기, 단계 수)을 공급자가 보고한 대로 합계로 보고합니다. 단계별 입력은 의도적으로 합계됩니다: 모든 요청은 전체 재전송 접두어에 대해 청구되므로 총계는 위임이 실제로 지출한 비용입니다.

구성

모든 설정은 서버 프로세스의 환변수입니다.

이 기능에 의존하기 전에 알아야 할 제한 사항

다음은 여기서 선택한 사항이 아닌 Harness SDK 와이어 프로토콜에서 비롯된 것입니다.

• 파일시스템 샌드박스는 bash를 포함하지 않습니다. dsh-fs-sandbox는 모델의 write/edit 도구를 작업 공간으로 제한하지만, dsh-bash-sandbox는 번들 런타임 실행 파일에 포함되어 있지 않으므로 bash 자체는 제한되지 않습니다. 감독자가 이를 처리합니다. 감독자는 실행 전에 bash를 포함한 모든 도구를 게이트합니다. DSA_SUPERVISOR=off인 경우 bash에 대한 경계가 전혀 없습니다. 브랜치나 스크래치 디렉터리를 가리키도록 하십시오.

• 샌드박스는 파일 효과만 제한합니다. 네트워크, 프로세스 또는 시스템 호출은 제한하지 않습니다. 그리고 workspace-write는 작업 공간 루트뿐만 아니라 /tmp도 허용합니다.

• 취소는 프로세스를 종료합니다. 와이어에 중간 턴 취소가 없으므로 dsh_cancel은 런타임을 종료합니다. 이미 작성된 편집 내용은 디스크에 남아 있으며, 이후에 세션을 재개할 수 없습니다.

• 회수된 에이전트의 세션은 사라지지만 결과는 사라지지 않습니다. DSA_IDLE_TIMEOUT 이후 프로세스가 해제됩니다. dsh_await 및 dsh_transcript는 완료된 실행에서 여전히 작동하지만 dsh_continue는 작동하지 않습니다.

• 세션은 프로세스가 유지되는 동안 유지됩니다. 세션별 종료가 없으므로 에이전트의 기록에 따라 메모리가 증가합니다. 완료된 에이전트는 취소하십시오.

• 업스트림은 개발자 프리뷰입니다. deepseek-harness-sdk는 ==0.1.0rc7에 고정되어 있습니다. 일주일 안에 두 개의 릴리스 후보가 출시되었습니다. 와이어가 변경될 것으로 예상하십시오.

개발

uv sync
uv run pytest                  # 127 tests, no API key, no network
uv run ruff check .
uv run deepseek-subagent-mcp   # starts on stdio; a client drives it

라이브 테스트는 실제 키가 필요하고 토큰 비용이 발생합니다. pytest로 수집되지 않습니다:

DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_task.py        # the product works
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_result.py      # distillation and the archive
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_supervisor.py  # the gate works
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_escalation.py  # both escalation tiers
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_limits.py      # reaper and deadline
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_mcp.py         # all six tools

CLAUDE.md는 아키텍처와 업스트림 제약 조건을 담고 있습니다. wiki/는 결정 기록과 측정된 내용을 담고 있습니다.

라이선스

MIT.