Pi 1.0 사용법: MCP·Codemode 설정과 안전한 확장 가이드

Pi 1.0은 터미널에서 파일을 읽고 수정하며 명령을 실행하는 오픈소스 AI 에이전트 하네스다. 2026년 10월 1일 공개된 1.0 정식판은 단순히 버전 번호만 올린 릴리스가 아니다. MCP를 기본 지원하고, 여러 도구 호출을 작은 JavaScript 프로그램으로 조합하는 Codemode를 추가했으며, 모델 전환·확장·긴 작업을 위한 기반을 정리했다. 다만 Pi의 중요한 특징은 기능 수보다 실행 철학에 있다. 기본 도구는 적고 사용자가 필요한 동작을 직접 조립할 수 있지만, 명령마다 승인 창을 띄우지 않으므로 시작 단계에서 작업 폴더와 권한 경계를 잘 정해야 한다.

이 글은 Pi 1.0을 처음 설치하는 사람을 기준으로 설치 확인, 모델 연결, MCP 서버 추가, Codemode 선택, 확장 프로그램 검토, 안전한 실행 환경까지 한 번에 설명한다. 직접 실행 결과나 성능을 주장하지 않고 2026년 10월 5일 확인한 Pi 공식 발표와 문서를 기준으로 정리했다.

먼저 알아둘 핵심: Pi는 챗봇이 아니라 실행 가능한 하네스다

Pi는 대화를 보여 주는 터미널 UI, 모델 호출, 세션 저장, 파일·셸 도구, 확장 시스템을 한데 묶는다. 사용자는 OpenAI·Anthropic·Google 같은 지원 제공자의 구독 또는 API 키를 연결하거나 로컬 모델을 선택할 수 있다. 작업을 시작하면 Pi는 현재 폴더를 기준으로 관련 파일과 설정을 찾고, 모델이 요청한 읽기·검색·편집·명령 실행을 표시한다.

여기서 “하네스”는 모델 자체가 아니라 모델이 실제 일을 하도록 둘러싼 실행 구조를 뜻한다. 같은 모델을 써도 어떤 파일을 볼 수 있는지, 어떤 도구를 호출할 수 있는지, 세션을 어떻게 이어 가는지에 따라 결과와 위험이 크게 달라진다. Pi는 이 구조를 작고 확장 가능하게 유지하는 쪽을 택했다. AGENTS.md 같은 지침 파일, 재사용 프롬프트, 스킬, TypeScript 확장을 필요에 따라 더할 수 있다.

Pi 1.0에서 달라진 점

변화	의미	주의할 점
MCP 기본 지원	stdio 또는 Streamable HTTP 서버의 도구·리소스를 연결한다.	프로젝트 설정과 자격증명 위치, 도구 노출 범위를 분리해야 한다.
Codemode	QuickJS 샌드박스 안의 JavaScript가 여러 도구 호출을 병렬 실행하고 결과를 줄여 모델에 전달한다.	스크립트 자체는 격리되지만 호출된 파일·셸·MCP 도구의 권한까지 자동 격리되는 것은 아니다.
가상 모델·중간 시스템 메시지	작업 단계에 따라 모델을 라우팅하거나 대화 중 지침과 도구 구성을 바꿀 수 있다.	확장은 Pi 프로세스와 같은 운영체제 권한으로 실행된다.
Pi Durable	장기 실행·체크포인트·다중 대화를 위한 별도 실험 패키지다.	일반 Pi를 대체하는 안정판이 아니라 API가 바뀔 수 있는 실험 단계다.

1.0.1과 1.0.2도 10월 3~4일에 이어졌다. 프로젝트별 MCP 서버 덮어쓰기, OAuth 관련 선택지, 출력 제한 오류 수정 등이 포함됐으므로 새 설치라면 1.0.0에 고정할 특별한 이유가 없는 한 최신 안정 릴리스를 확인하는 편이 낫다.

설치 전 준비사항

• 작업용 폴더: 처음부터 홈 디렉터리 전체가 아니라 복사본이나 별도 Git 작업 트리를 준비한다.
• 모델 접근 수단: 지원 구독, API 키, 로컬 모델 중 하나가 필요하다. Pi 자체 라이선스는 MIT지만 모델 사용 비용과 약관은 제공자별로 다르다.
• 버전 관리 또는 백업: 편집 전 상태로 되돌릴 수 있어야 한다. 중요한 저장소에서는 깨끗한 브랜치와 커밋 상태를 먼저 확인한다.
• 격리 계획: 신뢰하지 않는 저장소나 무인 작업은 컨테이너·가상 머신·샌드박스 안에서 실행한다.
• Node.js 확인: 공식 설치 스크립트는 필요한 구성 요소를 처리할 수 있지만 npm 직접 설치는 Node.js 22.19 이상이 필요하다.

1단계: 설치하고 시작 위치를 확인한다

macOS와 Linux의 공식 설치 명령은 다음과 같다.

curl -fsSL https://pi.dev/install.sh | sh
pi --version

Windows에서는 PowerShell 설치 명령을 제공한다.

powershell -c "irm https://pi.dev/install.ps1 | iex"

npm으로 직접 설치하려면 다음 명령을 쓸 수 있다. 공식 문서는 설치 스크립트가 전이 의존성을 고정하지만 npm 설치는 그렇지 않다고 구분한다.

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

설치 후에는 반드시 작업 대상 폴더로 이동한 뒤 Pi를 실행한다.

cd /path/to/project
pi

완료 확인은 세 가지다. pi --version이 버전을 출력하고, Pi 화면 하단에 현재 폴더와 모델 상태가 보이며, 의도한 프로젝트 폴더에서 세션이 시작됐는지 확인한다. 폴더를 잘못 잡았다면 모델에게 일을 시키기 전에 종료하고 다시 시작하는 편이 안전하다.

Pi 공식 Quickstart에 공개된 터미널 화면. 하단 상태 영역에서 작업 폴더와 모델을 확인할 수 있다. 출처: Pi Documentation, 확인일 2026-10-05.

2단계: 모델을 연결하고 작은 읽기 작업으로 점검한다

Pi 안에서 /login을 실행해 제공자를 선택한다. 지원 구독으로 로그인하거나 API 키를 저장할 수 있고, 이후 /model로 사용 가능한 모델을 바꿀 수 있다. 키를 프로젝트 파일이나 프롬프트에 직접 붙여 넣지 말고 공식 로그인 흐름이나 환경변수 방식을 이용한다.

첫 작업은 파일을 바꾸는 요청보다 읽기 전용 점검이 좋다.

이 저장소의 구조와 실행 가능한 검사 명령을 설명해 줘. 아직 파일은 수정하지 마.

모델이 읽은 파일과 실행한 검색, 제안한 명령을 살펴본다. Pi는 각 도구 호출을 보여 주지만 매번 승인받는 제품은 아니다. 따라서 “화면에 보인다”는 사실과 “권한 경계로 막혀 있다”는 사실을 혼동하면 안 된다.

3단계: MCP 서버는 사용자 범위와 프로젝트 범위를 나눈다

Pi 1.0은 로컬 stdio 서버와 원격 Streamable HTTP 서버를 지원한다. 예를 들어 현재 폴더를 대상으로 공식 파일시스템 예제 서버를 추가하고 연결 상태를 확인하는 흐름은 다음과 같다.

pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp list
pi

이 명령은 기본적으로 사용자 수준 설정인 ~/.pi/agent/mcp.json에 서버를 추가한다. 특정 프로젝트에서만 필요한 서버라면 --local 또는 -l을 사용해 .pi/mcp.json에 저장한다. 프로젝트 MCP 설정은 프로젝트 신뢰를 승인한 뒤 읽힌다.

실무 기준은 간단하다. 개인 계정과 자격증명이 필요한 서버는 사용자 설정에 두고, 저장소 구성원 모두에게 필요한 서버 정의만 프로젝트 설정에 둔다. 토큰 값은 JSON에 직접 적기보다 ${NAME} 환경변수로 참조한다. 추가 뒤에는 pi mcp list의 종료 상태와 오류를 확인하고, 실행 중 바꿨다면 /reload를 수행한다.

4단계: 도구 노출 범위를 최소화한다

MCP 서버를 연결했다고 모든 도구를 모델에 바로 보여 줄 필요는 없다. Pi는 서버 또는 개별 도구에 네 가지 노출 방식을 제공한다.

• codemode: 기본값이다. 도구 선언을 매 요청에 모두 싣지 않고 Codemode가 검색해 조합 호출한다.
• deferred: tool_search가 관련 도구를 찾았을 때 다음 모델 호출에 선언한다. 큰 서버에 적합하다.
• direct: 작은 핵심 도구를 일반 내장 도구처럼 모델에 바로 선언한다.
• hidden: 등록은 유지하지만 모델이 호출할 수 없게 한다.

예를 들어 읽기 도구는 검색 가능하게 두고 삭제 계열은 숨길 수 있다. 서버가 제공하는 readOnlyHint, destructiveHint, idempotentHint 같은 주석은 권한 확장이 확인 흐름을 만드는 데 활용할 수 있지만, 주석만으로 안전이 보장되지는 않는다.

Pi 공식 MCP 문서의 도구 노출 설정. 서버 전체 기본값과 개별 도구의 toolExposure를 조합할 수 있다. 출처: Pi Documentation, 확인일 2026-10-05.

5단계: Codemode는 토큰 절약 도구이면서 실행 설계다

Codemode가 켜지면 모델은 QuickJS 샌드박스에서 JavaScript를 작성해 여러 도구를 호출할 수 있다. 스크립트에는 Node API, 파일시스템, 네트워크, 타이머가 직접 제공되지 않는다. 외부 작업은 오직 Pi 도구와 models 인터페이스를 통해서만 수행한다. 여러 검색을 병렬로 실행하고 필요한 항목만 추린 뒤 짧은 결과를 모델에 전달하는 용도에 잘 맞는다.

MCP 서버의 기본 노출이 codemode이면 자동으로 활성화될 수 있다. MCP 없이 모든 세션에서 켜려면 ~/.pi/agent/settings.json 또는 신뢰한 프로젝트의 .pi/settings.json에 다음처럼 추가한다.

{
  "defaultTools": ["+codemode"]
}

일회성 실행에서는 --tools가 기존 선택을 통째로 대체하므로 필요한 도구를 모두 적어야 한다.

pi --tools read,bash,edit,write,codemode

중요한 한계도 있다. QuickJS 스크립트가 격리돼 있다는 이유로 tools.bash()나 MCP 도구의 실제 효과까지 격리되는 것은 아니다. 실패 전에 실행된 도구 호출은 자동으로 되돌아가지 않는다. 따라서 Codemode는 보안 샌드박스의 대체물이 아니라 도구 호출을 더 효율적으로 구성하는 계층으로 이해해야 한다.

활용 예시 1: 여러 로그를 읽고 원인 후보만 요약하기

목적은 큰 로그 여러 개를 모델 컨텍스트에 그대로 넣지 않고 오류 패턴만 추리는 것이다. 읽기 전용 폴더를 컨테이너에 마운트하고, 대상 파일 범위와 시간대를 프롬프트에 지정한다. Codemode는 여러 읽기 호출을 병렬로 실행하고 오류 줄과 주변 문맥만 반환하도록 구성할 수 있다. 검토 기준은 누락된 파일 목록, 시간대 일치, 원문 위치, 추정과 사실의 구분이다. 로그가 민감하면 외부 모델 제공자에게 전달되는 데이터 범위도 먼저 확인해야 한다.

활용 예시 2: MCP 문서 검색 결과를 비교표로 만들기

문서용 MCP 서버를 codemode 또는 deferred로 연결하고, 제품 버전·지원 운영체제·인증 방식처럼 비교할 필드를 미리 정한다. 에이전트가 여러 검색 결과를 모은 뒤 출처 URL과 확인 날짜가 있는 항목만 표에 넣도록 요청한다. 결과 검토 때는 문서의 최신 버전과 각 값의 출처가 실제로 연결되는지 확인한다. 쓰기 도구가 필요 없는 작업이므로 수정·삭제 도구는 숨기는 편이 낫다.

활용 예시 3: 가상 모델로 계획과 구현을 분리하기

Pi 1.0의 확장은 가상 모델을 등록해 단계별 라우팅을 만들 수 있다. 예를 들어 계획 단계에는 긴 문맥을 다루는 모델을, 구현 단계에는 코드 편집에 맞는 모델을 선택하는 구조다. 입력은 작업 목표, 변경 금지 영역, 테스트 명령, 비용 제한이다. 산출물은 계획서와 실제 변경 diff로 분리하고, 전환 기준이 예상대로 동작했는지 /session의 모델별 비용과 캐시 사용을 확인한다. 이 방식은 유연하지만 확장 코드가 프롬프트·도구 호출·자격증명·세션 기록을 볼 수 있으므로 직접 읽고 신뢰한 확장만 로드해야 한다.

보안 체크리스트: 프로젝트 신뢰는 샌드박스가 아니다

• Pi를 실행한 운영체제 사용자가 접근할 수 있는 파일과 프로세스는 Pi도 접근할 수 있다고 가정한다.
• 신뢰하지 않는 저장소는 컨테이너·VM·별도 계정에서 열고 필요한 폴더만 노출한다.
• 자격증명은 짧은 수명과 최소 권한을 우선하고, 가능하면 실행 환경 밖에 둔다.
• .pi/extensions, .pi/mcp.json, .pi/settings.json을 승인 전에 읽는다.
• AGENTS.md, 코드 주석, 명령 출력도 프롬프트 인젝션 경로가 될 수 있다고 본다.
• 확장과 설치 패키지는 Pi 프로세스와 같은 권한으로 실행될 수 있으므로 출처와 코드를 검토한다.
• 중요한 변경은 Git diff, 테스트, 백업으로 사람이 확인한다.

프로젝트 신뢰 기능은 폴더가 실행 가능한 확장과 MCP 설정을 몰래 로드하는 일을 줄여 주지만, 승인 후 도구가 접근할 수 있는 운영체제 권한을 제한하지 않는다. 공식 문서도 감시와 변경 검토가 보안 경계 자체는 아니라고 명시한다.

자주 막히는 문제와 해결 순서

pi 명령이 보이지 않을 때

새 터미널을 열고 pi --version을 다시 확인한다. npm 설치라면 Node.js가 22.19 이상인지, 전역 실행 경로가 PATH에 포함됐는지 확인한다. Nix 설치는 pi update가 아니라 Nix 명령으로 갱신한다.

MCP 서버가 연결되지 않을 때

pi mcp list를 먼저 실행한다. 설정 형식 오류, 실행 파일 누락, 환경변수 미설정, OAuth 로그인 필요 여부를 확인하고, 세션 안에서는 /mcp에서 전체 오류와 stdio 서버의 stderr 끝부분을 본다. Pi는 일부 네트워크 오류를 재시도하지만 도구 호출 자체는 중복 실행 위험 때문에 자동 재시도하지 않는다.

도구가 너무 많이 노출될 때

서버 기본 exposure를 codemode나 deferred로 낮추고, 자주 쓰는 읽기 도구만 direct로 올린다. 파괴적 도구는 패턴을 이용해 hidden으로 막는다. pi mcp list와 /mcp의 Tools 화면에서 실제 적용값을 확인한다.

Codemode 출력이 너무 크거나 중간에 실패할 때

스크립트 안에서 원본을 전부 누적하지 말고 필터링·집계를 먼저 한다. 실패 전 실행된 외부 도구 호출은 취소되지 않을 수 있으므로 쓰기 작업을 여러 번 묶기보다 읽기와 검증을 먼저 끝낸다. 큰 데이터는 도구로 파일에 저장하고 모델에는 요약과 경로만 전달하는 방식이 안전하다.

Pi Durable은 언제 살펴볼까

일반 Pi는 한 사용자가 터미널에서 세션을 이끌어 가는 코딩 에이전트에 맞춰져 있다. 프로세스가 죽어도 체크포인트에서 다시 이어야 하거나, 여러 사람이 같은 대화를 관찰·조정하거나, 여러 대화를 동시에 실행하는 애플리케이션을 만들고 싶다면 Pi Durable이 대상이다. 다만 2026년 10월 5일 기준 실험 패키지이며 API 변경 가능성이 있다. 처음부터 Durable로 복잡하게 시작하기보다 Pi 본체의 작업 폴더·모델·MCP·권한 경계를 이해한 뒤 별도 프로토타입으로 시험하는 편이 합리적이다.

정리

Pi 1.0의 장점은 모든 기능을 미리 넣어 둔 거대한 제품이 아니라, 작은 터미널 에이전트 위에 MCP·Codemode·확장·모델 라우팅을 필요한 만큼 조립할 수 있다는 점이다. 시작 순서는 설치, 작업 폴더 확인, 모델 로그인, 읽기 전용 점검, MCP 연결 검증, 도구 노출 최소화, 격리 환경 적용이 좋다. 특히 Codemode의 QuickJS 샌드박스와 실제 도구의 운영체제 권한은 서로 다른 경계라는 점을 기억해야 한다.

공식 출처

• Earendil, Pi 1.0 발표
• Pi Documentation, Quickstart
• Pi Documentation, MCP Servers
• Pi Documentation, Codemode
• Pi Documentation, Security
• Earendil, Pi Durable 발표

자료 확인일: 2026년 10월 5일

English version: Pi 1.0 Guide: Set Up MCP, Codemode, and Extensions Safely