mcp-delegate

Claude Code(오케스트레이터)가 별도의 완전한 에이전트 루프(로컬은 Ollama, 원격은 OpenRouter를 통해)에서 실행되는 다른 모델에 작업을 위임할 수 있는 도구를 제공하는 MCP 서버입니다. 이 루프는 자체 도구 접근 권한(파일, bash 등)을 가지며 최종 결과만 반환합니다. 기능적으로는 네이티브 서브에이전트와 동일하지만 모델에 구애받지 않습니다.

전체 빌드 계획은 mcp-subagent-delegation-plan.md를 참조하세요. 각 단계는 별도의 커밋/체크포인트로 구성되어 있습니다.

상태

1, 2, 3, 4단계가 완료되었습니다.

• delegate_task — 구성된 OpenAI 호환 엔드포인트(Ollama, LM Studio, vLLM, OpenRouter 등)에 대한 단일 호출 채팅 완성.

• delegate_agentic_task — 위임된 모델에 자체 도구 사용 루프(read_file, write_file, run_bash)를 제공하며, 호출자가 지정한 작업 디렉터리로 범위가 제한됩니다. 모델이 도구 호출을 중단하거나, max_iterations에 도달하거나, timeout_seconds를 초과할 때까지 실행됩니다.

• list_recent_delegations — 과거 위임(두 도구 모두)이 실제로 무엇을 했는지 로그를 뒤지거나 다시 실행하지 않고 검사합니다.

• get_delegation_transcript — capture_transcript=True로 실행된 경우(예: 모델 비교/평가 실행) 단일 위임에 대한 전체 메시지/도구 호출 기록.

원래 계획과의 차이점: 2단계에서는 agent-loop를 하위 프로세스로 래핑하도록 요구했습니다. agent-loop는 Linux/macOS/WSL만 지원하며, 이 서버는 Windows에서 기본적으로 실행되어야 하므로 5단계의 대안으로 설명된 프로세스 내 루프를 구축했습니다. 동일한 도구 인터페이스, 하위 프로세스/ANSI 제거 복잡성 없음, agent-loop의 AGPL/비상업적 라이선스 문제를 완전히 우회합니다. delegate/agentic.py를 참조하세요.

안전 참고 사항: working_dir은 호출자가 지정하며 고정 샌드박스가 아닙니다. 위임된 모델은 지시된 디렉터리에 대해 무인 파일/bash 액세스 권한을 얻습니다. 파일 도구(read_file/write_file)는 working_dir 내에 머물도록 범위가 제한됩니다. run_bash는 해당 디렉터리를 cwd로 실행되지만 셸 명령은 완전히 샌드박스 처리되지 않아 벗어날 수 있습니다(예: cd ..). 무인 모델이 읽고, 쓰고, 명령을 실행해도 괜찮은 디렉터리를 가리키도록 하세요.

가드레일 참고 사항: 원래 계획의 4단계는 agent-loop 자체 가드레일(반복 상한, 반복 감지)이 활성화되어 있는지 확인하도록 요구했습니다. agent-loop를 사용하지 않으므로 직접 적용되지는 않지만, 우리 루프에는 자체 max_iterations 및 timeout_seconds 상한이 있습니다(테스트에서 확인됨). 그러나 반복 감지는 없습니다. 두 도구 호출 사이에 갇힌 모델은 조기에 감지되지 않고 max_iterations에 도달할 때까지 실행됩니다. 실제로 그런 일이 발생한다면 추가할 가치가 있습니다.

Related MCP server: Thinking Agent MCP

설정

uv sync
cp .env.example .env             # fill in DELEGATE_BASE_URL / DELEGATE_API_KEY / DELEGATE_MODEL
cp models.json.example models.json   # optional: named backends, see below

여러 백엔드

두 도구 모두 선택적 backend 매개변수를 사용하여 기본 DELEGATE_* 환경 변수 대신 models.json에서 base_url/model/api_key를 조회합니다. 예를 들어 한 호출에는 backend="ollama-local"을, 같은 턴의 다른 호출에는 backend="openrouter-free"를 사용하여 각각 동시에 실행할 수 있습니다. model도 함께 제공되면 해당 백엔드 내에서 모델 문자열만 재정의합니다.

키에 대해 models.json에 직접 작성하는 대신 환경 변수를 참조하세요:

{
  "openrouter-free": {
    "base_url": "https://openrouter.ai/api/v1",
    "model": "nvidia/nemotron-nano-9b-v2:free",
    "api_key_env": "OPENROUTER_API_KEY"
  }
}

models.json은 .env와 마찬가지로 gitignore 처리됩니다.

동시성

MCP 도구 호출은 이미 별도의 작업자 스레드에서 실행되므로 추가 배선 없이 동시 위임이 병렬로 실행됩니다. DELEGATE_MAX_CONCURRENCY(기본값 4, .env.example 참조)는 두 도구 모두, 모든 백엔드에서 한 번에 실행되는 위임 수를 제한하여 대규모 팬아웃이 로컬 모델 서버나 유료 API의 속도 제한을 압도하지 않도록 합니다.

서버를 직접 실행합니다(주로 오류 없이 시작되는지 확인하는 데 유용하며, 그 후 MCP 클라이언트를 위해 stdio에서 대기합니다):

uv run server.py

로깅

모든 delegate_task/delegate_agentic_task 호출(성공 또는 실패)은 로컬 SQLite 파일인 delegations.db(gitignore 처리, 첫 사용 시 생성)에 기록됩니다: 도구, 백엔드, 모델, 작업 텍스트, 시작/종료 시간, 반복 횟수, 성공/실패, 잘린 결과/오류 미리보기, 백엔드가 반환한 경우 토큰 사용량. list_recent_delegations 도구를 통해 쿼리하거나 sqlite3 delegations.db "select * from delegations order by id desc limit 20"로 직접 쿼리할 수 있습니다. 로깅은 최선의 노력 방식입니다. 로깅 실패가 성공적인 위임을 중단시키지 않습니다.

두 도구 모두 백엔드가 사용량을 보고할 때 자체 반환 값에 [tokens: N prompt / N completion / N total ($cost)] 줄을 추가하므로 호출 에이전트는 별도의 list_recent_delegations 호출 없이 즉시 확인할 수 있습니다.

비용 추적

pricing.json은 모델 문자열을 {input_per_million, output_per_million} USD 요율로 매핑합니다. 호출의 해석된 모델에 항목이 있으면 실제 토큰 사용량에서 비용이 계산되어 delegations.db(cost_usd 열)에 기록되고 [tokens: ...] 접미사에 포함됩니다. 항목이 없는 모델은 cost_usd = NULL로 기록됩니다. 알 수 없음, 무료로 가정하지 않음 — 누락된 항목이 지출을 조용히 과소 보고할 수 없습니다. 로컬 모델은 일반적으로 이러한 이유로 항목이 없습니다. 진정으로 무료인 모델(예: OpenRouter :free 모델)은 생략하는 대신 명시적 {"input_per_million": 0, "output_per_million": 0} 항목을 얻습니다.

.env/models.json과 달리 pricing.json은 비밀이나 환경별 파일이 아니므로 gitignore 처리하지 않고 직접 커밋합니다. 가격은 변동됩니다. 배포된 파일은 이 서버가 구축된 모델 비교 베이크오프에서 명명된 모델에 대해 2026-08-21에 OpenRouter의 /api/v1/models에서 가져온 것입니다. 필요에 따라 다시 가져와서 모델을 추가/업데이트하세요.

기록 캡처(모델 비교/평가 실행)

두 도구 모두 capture_transcript: bool = False를 사용합니다. 설정하면 최종 답변뿐만 아니라 모든 모델 메시지, 도구 호출, 도구 결과를 포함한 전체 메시지 교환이 기록되고 반환 값에 [delegation_id: N] 접미사가 추가됩니다. get_delegation_transcript(delegation_id)로 가져옵니다.

이 기능은 동일한 작업을 여러 다른 모델/백엔드에서 실행하고 최종 답변뿐만 아니라 각 모델이 그 결과에 도달한 방식(도구 선택, 잘못된 도구 호출, 재시도)을 비교하기 위해 존재합니다. 예를 들어 프로덕션 사용 전에 후보 모델 간 베이크오프를 수행하는 경우입니다. 일상적인 위임에는 원하지 않는 추가 로깅 오버헤드이므로 기본적으로 꺼져 있습니다.

Claude Code에 등록

프로젝트 범위의 .mcp.json이 이미 체크인되어 있습니다(uv run server.py). 이 디렉터리에서 Claude Code를 다시 시작하거나 claude mcp list를 실행하여 delegate 서버를 인식했는지 확인한 다음, 간단한 프롬프트로 delegate_task를 호출하여 왕복을 확인하세요.

도구

• delegate_task(prompt, model=None, system_prompt=None, backend=None, capture_transcript=False) -> str — 구성된 백엔드에 대한 단일 호출 채팅 완성.

• delegate_agentic_task(task, working_dir, model=None, max_iterations=20, timeout_seconds=600, backend=None, capture_transcript=False) -> str — working_dir로 범위가 제한된 read_file/write_file/run_bash 도구를 사용한 다단계 위임. capture_transcript=True가 아닌 한 전체 기록이 아닌 최종 답변만 반환합니다.

• list_recent_delegations(limit=20) -> list[dict] — 가장 최근에 기록된 위임, 최신순.

• get_delegation_transcript(delegation_id) -> list[dict] — capture_transcript=True로 기록된 단일 위임에 대한 전체 기록.

delegate_task/delegate_agentic_task는 오류(잘못된 구성, 엔드포인트에 연결할 수 없음, 시간 초과, 반복 상한)를 발생시키는 대신 "Error: ..." 문자열로 반환하므로 호출 에이전트가 무엇이 잘못되었는지 확인할 수 있습니다.