Pi MCP Adapter

Pi에서 컨텍스트 창을 소모하지 않고 MCP 서버를 사용하세요.

이 어댑터가 존재하는 이유

Mario는 MCP가 필요하지 않을 수도 있는 이유에 대해 작성했습니다. 문제는 도구 정의(tool definitions)가 매우 장황하다는 것입니다. 단일 MCP 서버 하나만으로도 10k 토큰 이상을 소모할 수 있으며, 이 도구를 사용하든 안 하든 그 비용을 지불해야 합니다. 몇 개의 서버를 연결하면 대화가 시작되기도 전에 컨텍스트 창의 절반을 태워버립니다.

그의 견해는 다음과 같습니다: MCP 자체를 건너뛰고 대신 간단한 CLI(Command Line Interface) 도구를 작성하는 것입니다.

하지만 MCP 생태계에는 데이터베이스, 브라우저, API 등 유용한 것들이 있습니다. 이 어댑터는 비대함 없이 접근할 수 있게 해줍니다. 수백 개의 서버 대신 단일 프록시 도구(~200 토큰)만 사용합니다. 에이전트는 필요할 때 필요한 것을 스스로 발견합니다. 서버는 실제로 사용될 때만 시작됩니다.

pi-mcp-adapter 대 Pi의 내장 MCP 기능

그 이후로, Pi 0.99 버전은 자체적으로 MCP 지원을 추가했으며, 이 역시 도구 정의를 컨텍스트에서 제외하는 기능을 합니다. 이 어댑터를 설치하면 Pi 세션에서 기존 기능을 대체합니다. 전환함으로써 얻는 이점은 다음과 같습니다:

• 유휴 서버에 대한 비용 지불 없이 여러 서버 설치. 내장 기능은 모든 Pi 세션에서 활성화된 모든 서버를 시작하고, 세션이 끝날 때까지 실행 상태로 유지합니다. 기본적으로 어댑터는 모델이 처음 호출할 때 서버를 시작하고 10분간 유휴 상태일 경우 중지합니다.
• 일상적인 호출 시 토큰 감소. 기본적으로 내장 기능은 단 한 번의 조회(lookup)조차도 모든 MCP 호출을 codemode 스크립트로 실행합니다. 어댑터의 스크립트는 기본적으로 꺼져 있어, 조회가 mcp 도구로 가는 작은 JSON 호출 하나만으로 이루어지며, 테스트 결과 10~33% 비용 절감 효과를 보였습니다. 여러 레코드를 대상으로 대량 작업을 할 때는 settings.scriptMode로 스크립트를 켜면 되며, 이때는 codemode와 비슷한 비용이 발생합니다.
• 더 많은 서버가 완벽하게 작동. 서버는 양식을 통해 질문을 하거나, 상호작용하는 UI를 보여주거나, 슬래시 명령어(slash commands)로 프롬프트 템플릿을 제공할 수 있습니다. 내장 기능은 이러한 기능을 처리하지 못합니다.
• 의미에 따라 도구 찾기. 내장 기능의 도구 검색은 단어 일치만 합니다. System One 키를 사용하면 어댑터는 의미에 따라 도구를 순위화(rank)할 수도 있습니다. 95개의 도구 중 12가지 일상 요청을 테스트한 결과, 어댑터는 올바른 도구를 11번 중 10번 첫 번째로 배치했지만, 단어 검색은 5번만 성공했습니다.
• 로그인 토큰이 OS 키체인에 저장됨. 기본적으로 평문 JSON 파일(~/.pi/agent)이 아닌 OS 키체인(암호화된 파일)에 저장됩니다.
• 서버 추가가 더 쉬워짐. 에이전트에게 서버의 URL을 제공하면, 같은 세션 내에서 이를 설치하고 도구를 확인하며, 서버가 필요로 할 경우 로그인 절차를 먼저 진행합니다. 이때 셸 명령어(shell command)나 /reload가 필요 없습니다. Cursor, Claude Code, Codex 또는 VS Code에 이미 구성된 서버는 /mcp-adapter setup으로 가져올 수 있으며, 이 과정에서 Figma 및 GitHub와 같은 프리셋도 추가됩니다.

내장 기능에는 어댑터가 가지지 못한 두 가지 장점이 있습니다. Pi의 권한 확장(permission extensions)은 모든 MCP 호출을 변경 없이 자체 도구 호출로 인식하며, 서버에 루트 디렉토리(세션 디렉토리)를 전송합니다. Pi의 codemode는 이 두 가지 모두와 작동합니다.

전체 비교 내용에는 Pi 0.99.2 기준의 출처가 포함된 모든 행이 있습니다.

어댑터를 설치하거나 업데이트하면, Pi 설정에서 자동으로 Pi의 내장 MCP를 비활성화합니다 (이는 pi config → Built-in과 동일한 스위치입니다). 따라서 두 가지 기능이 동시에 실행되지 않습니다. 어댑터를 제거할 경우, 해당 위치에서 내장 기능을 다시 활성화해야 합니다 (상세 정보).

설치

pi install npm:pi-mcp-adapter

설치 후 Pi를 재시작하십시오.

DeepSeek Harness (제3자 브릿지): pi2dsh를 통해 수정되지 않은 어댑터를 DSH에서 실행할 수 있습니다. 검증된 dsh-TUI 및 Web MCP 가이드를 참조하십시오.

첫 실행 시 발생하는 일

어댑터는 표준 MCP 파일을 자동으로 읽습니다. 이미 해당 파일들이 있다면 추가적인 설정이 필요하지 않습니다.

빠른 시작 (Quick Start)

프로젝트의 .mcp.json에 서버를 추가하세요:

{
  "mcpServers": {
    "chrome-devtools": {
...

서버는 기본적으로 지연(lazy) 방식입니다. 실제로 해당 도구 중 하나를 호출할 때까지 연결되지 않습니다. 어댑터는 도구 메타데이터를 캐시하므로 라이브 연결 없이도 검색 및 설명 작업이 가능합니다.

mcp({ search: "screenshot" })

chrome_devtools_take_screenshot
  페이지 또는 요소의 스크린샷을 찍습니다.

...

mcp({ tool: "chrome_devtools_take_screenshot", args: { format: "png" } })

26개의 도구로 컨텍스트를 복잡하게 만드는 대신 두 번의 호출만으로 충분합니다.

일반적인 작업 (Common tasks)

명령어 (Commands)

대화형 세션에서는 인증이 필요한 서버에서 ctrl+a 또는 Enter를 사용하여 /mcp-adapter에서도 인증할 수 있습니다. 서버 없이 /mcp-auth만 실행하면 대화형 UI에 피커(picker)가 열립니다. 게이트웨이 권한 부여 및 수동 콜백 완료는 원격/헤드리스 인증을 참조하십시오.

Pi 0.99 버전 이상에서는 Pi의 내장 MCP로 이미 로그인한 서버를 재사용할 수 있습니다: 어댑터는 서버당 한 번만 요청하며, /mcp-adapter에서 ctrl+p를 사용하여 이를 가져올 수 있습니다. Pi의 내장 MCP에서 로그인 정보 가져오기를 참조하십시오.

작동 방식

• 수백 개 대신 컨텍스트 내에서 하나의 mcp 도구(~200 토큰)
• 서버는 기본적으로 지연(lazy)됩니다. 즉, 시작 시가 아니라 첫 번째 도구 호출 시에 연결합니다.
• 검색/목록 보기/설명 기능이 실시간 연결 없이 작동하도록 도구 메타데이터가 디스크에 캐시됩니다.
• 유휴 상태의 서버는 10분 후(구성 가능) 연결이 끊어지며, 다음 사용 시 자동으로 재연결됩니다.
• npx 기반 서버는 npm 부모 프로세스(~143 MB)를 건너뛰고 직접적인 바이너리 경로로 해결됩니다.
• MCP 서버가 어댑터가 아닌 인수를 검증합니다.
• 원격 Keep-alive 서버는 사용자 입력 전, 건강 상태 확인 중, 그리고 어댑터가 트리거하는 턴 전에 도구 카탈로그를 강제 새로고침하며, 재연결 백오프(backoff) 시간이 제한됩니다.
• 특정 도구를 directTools 설정을 통해 프록시에서 일급 Pi 도구로 승격할 수 있어, LLM이 검색해야 하는 대신 직접적으로 해당 도구를 볼 수 있습니다.

제한 사항

• 각 Pi 세션은 자체 서버 프로세스를 실행합니다. rmcp-mux를 사용하면 이들을 세션 간에 공유할 수 있습니다.
• Compact MCP 결과 렌더링은 텍스트를 요약하지만, 인라인 이미지는 여전히 Pi의 이미지 표시 설정에 의해 제어되며, 컴팩트 텍스트 요약 아래에 렌더링될 수 있습니다.
• Pi는 자체 렌더링된 도구 출력 앞에 하나의 구분선 행을 가지고 있으므로, 컴팩트 모드는 어댑터 렌더링 높이를 줄이지만 진정한 제로 간격(zero-gap) 행을 보장할 수는 없습니다.
• MCP 샘플링 지원은 텍스트 전용입니다. 컨텍스트 포함, 도구, 중지 시퀀스, 오디오 및 이미지 콘텐츠는 명시적인 오류와 함께 거부됩니다.

문서화 (Documentation)

전체 참고 자료는 docs/에 있습니다: