pi-delegate-mcp

██████╗ ██╗    ██████╗ ███████╗██╗     ███████╗ ██████╗  █████╗ ████████╗███████╗
██╔══██╗██║    ██╔══██╗██╔════╝██║     ██╔════╝██╔════╝ ██╔══██╗╚══██╔══╝██╔════╝
██████╔╝██║    ██║  ██║█████╗  ██║     █████╗  ██║  ███╗███████║   ██║   █████╗
██╔═══╝ ██║    ██║  ██║██╔══╝  ██║     ██╔══╝  ██║   ██║██╔══██║   ██║   ██╔══╝
██║     ██║    ██████╔╝███████╗███████╗███████╗╚██████╔╝██║  ██║   ██║   ███████╗
╚═╝     ╚═╝    ╚═════╝ ╚══════╝╚══════╝╚══════╝ ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝
                            ███╗   ███╗ ██████╗██████╗
                            ████╗ ████║██╔════╝██╔══██╗
                            ██╔████╔██║██║     ██████╔╝
                            ██║╚██╔╝██║██║     ██╔═══╝
                            ██║ ╚═╝ ██║╚██████╗██║
                            ╚═╝     ╚═╝ ╚═════╝╚═╝

pi 코딩 에이전트를 위임 가능하고 조종 가능한 워커로 노출하는 MCP 서버입니다.

Claude Code(또는 모든 MCP 호스트)를 이 서버에 연결하고 pi의 약 38개 제공자(DeepSeek, Grok, GLM, Kimi, Qwen, Codex, OpenRouter, 로컬 llama.cpp) 중 하나에 작업을 위임하세요. 서브 에이전트의 컨텍스트는 메인 대화에 들어오지 않습니다.

용도

메인 하네스는 비싼 모델에서 실행되며, 신경 쓰는 컨텍스트 윈도우가 있습니다. 하네스가 하는 일 중 상당수는 그 모델이 필요 없고, 오히려 컨텍스트를 적극적으로 손상시킵니다: 모든 호출 지점을 찾기 위해 저장소를 grep 하기, 한 가지 질문에 답하기 위해 2000줄짜리 파일 읽기, 리팩터링이 남긴 것을 감사하기.

그 작업을 대신 위임하세요:

• 비용. 단순 작업은 DeepSeek, GLM, Kimi, Qwen 또는 로컬 llama.cpp에서 실행됩니다. 실제로 프론티어 모델이 필요한 추론에만 프론티어 가격을 지불합니다.

• 컨텍스트. 위임 에이전트는 자체 예산으로 파일을 읽고 결과를 반환합니다. 읽은 200KB는 결코 대화에 들어오지 않습니다.

• 피해 범위. 위임 에이전트는 기본적으로 읽기 전용(read, grep, find, ls)이며, 세션 구성 시 강제됩니다. 탐색 작업을 하는 저렴한 모델은 옵트인하지 않는 한 트리에 손을 댈 수 없습니다.

위임 에이전트는 항상 pi 에이전트입니다. Codex, Grok, DeepSeek 등은 그 뒤의 모델을 공급합니다. 이것은 그들의 CLI를 감싼 래퍼가 아닙니다.

Related MCP server: handoff-mcp

왜 pi인가, opencode나 CLI 래퍼가 아닌가?

위임 에이전트는 두 채널이 열려 있어야만 조종할 수 있습니다: 작업 중에 방향을 바꿀 수 있어야 하고, 에이전트가 질문을 하고 답변을 받을 때까지 블록할 수 있어야 합니다. 다른 프로그램에서 코딩 에이전트를 구동하는 대부분의 방식은 둘 다 닫아버립니다.

pi -p와 --mode json은 ctx.hasUI = false로 설정합니다. 그렇게 시작된 위임 에이전트는 구조적으로 발사 후 잊기(fire-and-forget)입니다: 질문을 제기할 수 없고, 방향을 바꿀 수도 없습니다.

opencode의 SDK는 별도의 서버 프로세스를 위한 타입드 클라이언트입니다: createOpencode()는 opencode serve를 부팅하고 HTTP로 통신합니다. 깔끔한 설계이지만, 감독해야 할 두 번째 프로세스가 생기고, 노출하는 세션 표면(prompt, abort, revert, messages)에는 턴 중간 조종이 없으며 에이전트가 호출자에게 질문할 경로도 없습니다.

pi는 createAgentSession을 임베드 가능한 라이브러리로 제공합니다. 이 서버는 세션 객체를 프로세스 내에서 보유하므로, session.steer()가 현재 도구 호출 이후, 다음 모델 호출 이전에 메시지를 넣을 수 있고, 합성 uiContext가 에이전트의 질문을 받아 answer를 위해 대기시킵니다. 셸로 빠져나가는 것이 없고, 감독할 것도 없습니다.

* 질문은 pi 확장에서 오므로, 그 채널은 extensions: true로 생성된 위임 에이전트에게만 열려 있습니다. 웹 검색 및 기타 확장 도구를 참조하세요.

(표는 위임 채널을 비교한 것이지 샌드박싱이 아닙니다; opencode에는 자체 권한 구성이 있습니다. 이 서버가 무엇을 강제하고 강제하지 않는지는 기본 읽기 전용을 참조하세요.)

도구

설치

Node.js 22.19+와 한 번 로그인된(pi, 그다음 /login) 작동하는 pi 설치가 필요합니다.

Claude Code

claude mcp add pi -e PI_DELEGATE_MODEL=openrouter/stealth/ox-alpha -- npx -y pi-delegate-mcp

.mcp.json을 통한 모든 MCP 호스트

{
  "mcpServers": {
    "pi": {
      "command": "npx",
      "args": ["-y", "pi-delegate-mcp"],
      "env": { "PI_DELEGATE_MODEL": "openrouter/stealth/ox-alpha" },
      "timeout": 1800000
    }
  }
}

npx는 매 실행마다 패키지를 해석합니다. 고정하려면 전역으로 설치하고 바이너리를 직접 호출하세요:

npm install -g pi-delegate-mcp

{ "mcpServers": { "pi": { "command": "pi-delegate-mcp", "timeout": 1800000 } } }

서버 키는 모든 도구 이름에 접두사로 붙으므로(mcp__pi__spawn) 짧게 유지하세요.

소스에서

git clone https://github.com/howznguyen/pi-delegate-mcp && cd pi-delegate-mcp
npm install && npm run build && npm link

첫 실행

에이전트에게 무언가를 위임하라고 요청하세요. 에이전트는 이 서버가 도달할 수 있는 것을 배우기 위해 init을 한 번 호출한 다음 spawn을 호출합니다:

{ "id": "audit-01", "label": "who still imports onnxruntime",
  "prompt": "Search this repo for anything still importing onnxruntime and list the files.",
  "cwd": "/path/to/repo" }

{ "sessionId": "audit-01", "state": "running", "model": "opencode-go/deepseek-v4-flash",
  "activeTools": ["read", "grep", "find", "ls"] }

spawn은 즉시 반환합니다. status로 순서가 있는 도구 추적과 답변을 폴링하거나, 여러 개가 진행 중일 때는 sessions를 폴링하세요. init이 실패하면 정확히 무엇이 빠졌는지 말해줍니다: pi 미설치, 로그인된 제공자 없음, 또는 일치하는 것이 없는 모델 범위.

아래 예시의 모델 이름은 예시용입니다. models를 실행하여 자신의 pi 설치가 실제로 도달할 수 있는 것을 확인하세요.

추적 가능성

spawn과 run 모두 사용자 정의 id와 자유 텍스트 label을 허용합니다:

{
  "id": "search-audit-01",
  "label": "what ONNX removal left behind",
  "prompt": "...",
  "model": "opencode-go/deepseek-v4-flash"
}

Id는 [A-Za-z0-9._:-], 1-64자, 영숫자로 시작해야 하며 활성 세션 간에 고유해야 합니다. 생략하면 UUID가 생성됩니다.

완료된 세션은 사라지지 않고 status와 sessions로 계속 읽을 수 있으므로, 위임 에이전트가 실제로 무엇을 했는지 돌아가 확인할 수 있습니다. 가장 최근의 PI_DELEGATE_HISTORY(기본 50)개가 유지됩니다. forget은 하나를 일찍 제거합니다.

status는 순서가 있는 toolCalls 추적을 반환합니다: 위임 에이전트가 실행한 모든 도구와 인자, 타이밍. 호출 id와 결과를 보려면 verbose: true를 추가하세요:

{
  "seq": 1,
  "id": "call_467b4bb4…",
  "name": "bash",
  "state": "ok",
  "ms": 10,
  "args": "{\"command\":\"echo hello-trace\"}",
  "result": "hello-trace\n"
}

인자와 결과는(PI_DELEGATE_TRACE_ARGS, PI_DELEGATE_TRACE_RESULT) 잘린 길이가 기록된 채로 클리핑되므로, 큰 파일의 read 한 번이 컨텍스트를 넘치게 할 수 없습니다.

위임 에이전트에게 또 다른 턴 주기

완료된 위임 에이전트는 끝난 것이 아닙니다. pi는 세션을 메모리에 유지하므로, follow_up은 이미 읽은 모든 것이 여전히 컨텍스트에 있는 상태로 같은 에이전트를 다시 프롬프트합니다:

{ "sessionId": "search-audit-01", "prompt": "Now check whether the build files reference it too" }

{ "sessionId": "search-audit-01", "state": "running", "turnsSoFar": 1 }

위임 에이전트는 중단한 지점에서 이어갑니다. 첫 턴에 읽은 파일을 여전히 보유하므로, 두 번째 질문은 저장소를 다시 읽는 새 세션 대신 모델 호출 한 번만 듭니다.

이것이 위임 에이전트와 대화하는 저렴한 방법입니다. 새로 생성하면 작업을 다시 설명하고 같은 파일을 다시 읽는 비용을 지불해야 하며, 답변에는 그에 이른 추론이 전혀 포함되지 않습니다.

follow_up은 아직 작업 중인 위임 에이전트를 거부합니다. 작업 중간에 방향을 바꾸는 것은 steer의 역할이기 때문입니다. 둘은 상호 교환할 수 없습니다: steer는 실행 중인 에이전트의 도구 호출 사이에 적용되고, follow_up은 완료된 에이전트에서 새 턴을 시작합니다.

팬아웃

spawn_batch는 한 번의 호출로 전체 배치를 시작합니다. 작업은 배치 수준의 model, cwd, tools, extensions를 상속하고, 필요한 곳에서 개별적으로 재정의합니다:

{
  "idPrefix": "audit",
  "model": "opencode-go/deepseek-v4-flash",
  "cwd": "/repo",
  "tools": ["ls"],
  "tasks": [
    { "prompt": "What still imports onnxruntime?", "label": "imports" },
    { "prompt": "Which build files still reference ONNX?", "label": "build" },
    {
      "prompt": "Any ONNX model files left on disk?",
      "label": "artifacts",
      "model": "opencode-go/ox-alpha-free"
    }
  ]
}

그러면 audit-01, audit-02, audit-03으로 이름이 지정되고 몇 밀리초 안에 반환됩니다. 위임 에이전트를 시작하는 것은 생각할 때까지 기다리지 않기 때문입니다.

배치는 아무것도 시작하기 전에 검증됩니다: id 형식, 배치 내 중복 id, 이미 활성화된 id, 차단된 도구, 모든 모델 이름. 하나의 잘못된 작업은 호출을 실패시키고 아무것도 시작하지 않습니다. 팬아웃의 절반이 최악의 결과입니다. 시작된 위임 에이전트에 대한 비용을 지불하면서 어떤 것이 시작되지 않았는지도 알아내야 하기 때문입니다.

전체 배치를 위임 에이전트당 status 하나씩이 아니라 sessions 호출 하나로 폴링하세요. 실제로 읽고 싶은 위임 에이전트에 대해서만 status로 내려가세요. steer와 abort는 세션별로 유지됩니다.

호출별 모델 선택

모든 호출의 model은 PI_DELEGATE_MODEL을 재정의합니다. 해석할 수 없는 이름은 조용한 기본 모델 폴백이 아니라 하드 오류입니다. 조용한 폴백은 요청하지 않은 모델에 비용이 청구되는 방식이기 때문입니다.

어떤 이름이 해석되는지는 pi 자체의 enabledModels 범위가 결정하며, 이 서버는 단순히 표시만 하는 것이 아니라 강제합니다:

opencode-go/deepseek-v4-flash  -> ok      (listed in enabledModels)
opencode-go/glm-5.3            -> refused (out of scope)
knowns-hub/claude-opus         -> ok      (custom provider, see below)

사용자 정의 제공자는 범위를 우회합니다. ~/.pi/agent/models.json에 선언된 제공자가 서비스하는 모든 모델은 enabledModels가 이름을 지정하지 않아도 제공됩니다. 제공자를 수동으로 선언하는 것 자체가 사용 의도이기 때문입니다. 이것이 목록이 enabledModels보다 훨씬 길 수 있는 이유입니다: 범위의 세 항목에 두 개의 사용자 정의 제공자를 더하면 쉽게 열다섯 개의 제공 모델이 될 수 있습니다. init은 적용될 때 models.scopeNote에서 명시적으로 말합니다.

두 가지 스위치가 이를 변경합니다:

현재 적용 중인 설정에서 실제로 도달 가능한 것을 보려면 models를 호출하세요.

상태 줄

Claude Code는 정확히 하나의 statusLine 명령만 허용하므로, pi-delegate-statusline은 이미 실행 중인 것을 감싸고 이 작업 공간의 위임 에이전트를 보여주는 세그먼트를 추가합니다:

{
  "statusLine": {
    "type": "command",
    "command": "PI_DELEGATE_STATUSLINE_WRAP=ccstatusline pi-delegate-statusline",
    "refreshInterval": 10
  }
}

PI_DELEGATE_STATUSLINE_WRAP를 내려놓으면 pi 세그먼트만 출력합니다.

π ▸ audit engine·t1·12s audit index·t2·8s   running, with turn counts and elapsed time
π ▸ migrate·t7·3m04s ?1 waiting             one delegate is blocked on a question
π ✓2                                        finished, nothing running

어떤 위임 에이전트가 어떤 세션에 속하는가

디렉터리로 필터링하는 것만으로는 충분하지 않습니다: 같은 저장소에 열린 두 Claude Code 세션이 서로의 위임 에이전트를 보여줄 수 있습니다. 귀속은 대신 프로세스 계보를 사용합니다.

MCP 호스트는 세션당 서버 하나를 생성하므로, 서버는 process.ppid, 즉 호스트의 pid를 기록합니다. 같은 호스트가 생성한 상태 줄은 자신의 조상을 탐색하고 hostPid가 거기서 발견되는 상태 파일만 유지합니다. 같은 저장소, 두 세션, 누화 없음. 디렉터리 필터는 이것이 생기기 전에 작성된 상태 파일을 위한 폴백으로 남아 있습니다.

상태는 $XDG_STATE_HOME/pi-delegate-mcp/<pid>.json에 저장됩니다(PI_DELEGATE_STATE_DIR로 위치 변경). 파일은 해당 프로세스가 사라졌을 때 정리되며, 오직 ESRCH인 경우에만 그렇습니다. EPERM은 프로세스가 다른 사용자로 살아 있음을 의미하기 때문입니다. 서버는 또한 stdin이 닫히거나 호스트 pid가 사라지면 스스로 종료되므로, 전송을 닫지 않은 채 호스트가 죽더라도 아무것도 남지 않습니다.

기본적으로 읽기 전용

도구는 세션 생성 시점에 read, grep, find, ls로 잠깁니다. 그 외의 것은 세션이 만들어지기도 전에 거부됩니다.

범위를 넓히려면 서버에 추가 도구 이름을 지정하세요:

"env": { "PI_DELEGATE_ALLOW_TOOLS": "bash" }

또는 PI_DELEGATE_ALLOW_WRITE=1로 모든 것을 허용할 수 있습니다.

bash는 절충안이 아닙니다. pi에는 권한 시스템이 없으므로 bash를 가진 델리게이트는 write와 edit가 목록에 있는지와 관계없이 파일을 쓰고, 삭제하고, 네트워크에 접근할 수 있습니다. 그 두 개를 거부하면서 bash를 허용하는 것은 의도를 기록할 뿐 아무것도 강제하지 않습니다. Claude Code의 권한 프롬프트와 훅은 pi가 하는 일을 결코 보지 못합니다. 실제 경계가 필요하다면 이 서버를 컨테이너 안에서 실행하세요.

웹 검색 및 기타 확장 도구

pi의 자체 도구는 read, grep, find, ls, bash, powershell, write, edit입니다. 그중에는 검색도 fetch도 없습니다. 그것들은 자체 도구를 등록하는 pi 확장에서 제공되며, 델리게이트가 사용할 수 있습니다.

호출에 extensions: true를 설정하고 서버에서 도구 이름을 허용하세요:

"env": { "PI_DELEGATE_ALLOW_TOOLS": "web_search,fetch_content" }

{ "prompt": "Find the current Node LTS version and tell me just the number",
  "extensions": true, "tools": ["read", "grep", "find", "ls", "web_search"] }

{ "seq": 1, "name": "web_search", "state": "ok", "ms": 2568,
  "args": "{\"query\":\"latest stable Node.js LTS version\",\"numResults\":5}" }

이것이 델리게이트에 bash를 넘겨주지 않고 네트워크 접근을 주는 방법입니다. web_search는 검색만 할 수 있고 그 외에는 아무것도 할 수 없으며, 다른 모든 도구와 동일한 허용 목록을 통과하므로 요청하지 않은 호출에는 읽기 전용 기본값이 그대로 유지됩니다.

어떤 도구가 존재하는지는 서버를 실행하는 사용자가 설치한 것에 달려 있습니다. pi-web-access는 web_search, fetch_content, source_check, get_search_content를 제공합니다. pi-mcp-adapter는 ~/.pi/agent/mcp.json의 MCP 서버들을 연결하여 mcp로 노출합니다. pi에는 자체 MCP 클라이언트가 없으므로 그 확장이 유일한 경로입니다.

extensions: true는 원하는 확장 하나만이 아니라 설치된 모든 확장을 신뢰합니다. 확장들은 묶음으로 로드되며, 이 서버 프로세스의 모든 권한으로 실행되고, 일부는 세션보다 오래 지속되는 소켓과 타이머를 엽니다. 기본적으로 켜 두지 말고, 필요로 하는 델리게이트를 위해 호출별로 켜십시오. 또한 실제 시작 시간이 소요되므로 요청하지 않으면 꺼져 있습니다.

구성

장기 실행 작업

MCP TypeScript SDK는 기본적으로 60초 요청 시간 제한을 사용하며, 실제 작업은 이 제한을 훌쩍 넘겨버립니다. 선호 순서대로 세 가지 방어책이 있습니다:

1. spawn + status를 사용하세요. 아무것도 블로킹되지 않으므로 시간 제한이 적용되지 않습니다.

2. run은 주기적으로 진행 알림을 보내며 호스트의 시간 제한을 재설정합니다.

3. .mcp.json의 "timeout" 또는 환경의 MCP_TOOL_TIMEOUT으로 상한을 높이세요.

CLAUDE_AUTO_BACKGROUND_TASKS=1은 Claude Code가 약 2분 후에 긴 MCP 호출을 백그라운드로 전환하게 합니다. 호출이 백그라운드로 전환되면 진행 알림은 버려지므로 (1) 또는 (3) 중 하나를 선택하세요. 둘 다는 안 됩니다.

인증

서버는 자격 증명을 처리하지 않습니다. pi는 ~/.pi/agent/auth.json에서 먼저 인증하고 그다음 환경 변수를 사용합니다. MCP 호스트는 종종 환경 변수가 제거된 환경으로 서버를 실행하므로, 셸 프로필에 키를 내보내는 것보다 auth.json을 사용하는 것이 좋습니다(pi를 한 번 실행하고 /login).

개발

npm install
npm run build       # tsc, src/*.ts -> dist/
npm run typecheck   # tsc --noEmit, strict
npm run test:ci     # offline: boots the server over stdio and lists its tools
npm test            # full suite: needs a logged-in pi, makes real model calls

test:ci는 CI가 실행하는 명령이자 prepublishOnly가 게이트로 삼는 명령입니다. 자격 증명도 네트워크도 필요 없기 때문입니다. npm test는 실제 델리게이트를 실제 공급자에 대해 실행하므로 비용이 들고 pi에 로그인된 환경에서만 작동합니다.

릴리스는 태그 기반입니다. npm version patch && git push --follow-tags는 빌드와 테스트를 실행한 다음 OIDC trusted publishing으로 게시하므로 저장소 어디에도 npm 토큰이 저장되지 않습니다.

이슈와 풀 리퀘스트는 환영합니다. 문제가 있는 델리게이트를 보고하는 경우라면 verbose: true를 지정한 status의 toolCalls 추적을 첨부하는 것이 유용합니다.

관련 사례

abatilo/pi-mcp-bridge는 더 간단한 길을 택합니다: pi --mode json -p --session-id <uuid>를 실행하고 pi가 세션을 디스크에 유지하게 하므로 브리지는 상태를 전혀 가지지 않습니다. 우아하고 읽어볼 가치가 있습니다. 그 단순함을 얻기 위해 방향 제어, 질문, 도구 제어를 포기합니다.

라이선스

MIT