nicobailon/pi-mcp-adapter

Pi MCP Adapter 는 Pi AI 코드 에이전트용 플러그인입니다. 현실적인 문제를 해결합니다: MCP(Model Context Protocol) 서버는 데이터베이스, 브라우저, API에 접근할 수 있게 해주는 도구들로 구성되지만, 각 서버는 매우 긴 도구 정의를 포함하고 있어, 실제로 사용하기 전에 이미 10,000개 이상의 토큰을 소모합니다. 몇 개의 서버를 연결하기만 해도 이미 컨텍스트 창의 절반을 소모하게 됩니다.

이 어댑터의 핵심 기술은, 모든 서버의 도구를 에이전트의 컨텍스트에 로드하는 대신, 하나의 프록시 도구(~200 토큰) 만 노출하는 것입니다. 에이전트가 실제로 특정 기능이 필요할 때, 프록시를 호출하여 필요한 도구를 동적으로 탐색하고 실행합니다. 서버는 지연 로딩됩니다. 도구를 호출하기 전까지는 연결되지 않습니다. 도구 메타데이터는 캐시되므로, 실시간 연결 없이도 검색과 설명이 가능합니다.

설치는 한 줄의 명령어로 완료됩니다: pi install npm:pi-mcp-adapter.

구성은 표준 MCP 파일(.mcp.json 프로젝트용, ~/.config/mcp/mcp.json 사용자 전역용)에 더해 Pi 전용 오버라이드 파일을 사용합니다. /mcp 패널을 통해 설정이 가능하며, /mcp setup 명령어로 Cursor, Claude Code, Codex 등의 다른 호스트에서의 설정을 Pi로 가져올 수 있습니다. 이 어댑터는 다음 기능도 지원합니다:

• 에이전트 플러그인 — 플러그인 패키지에서 MCP 서버를 로드하며, <plugin>__<server> 형식으로 접두사 지정
• Claude 플러그인 — 로컬 플러그인 디렉터리에서 MCP 서버와 기술을 활성화 (명시적 신뢰 경계; 플러그인을 다운로드하거나 설치하지 않음)
• Pi 패키지 — 별도의 구성 파일 없이 Pi 패키지 내부에 MCP 서버 포함 가능
• 프로그래밍적 사용 — createMcpAdapter({ config })를 사용해 SDK/서버 통합에서 자체 MCP 구성 관리 가능
• OAuth — 공유 모듈 pi-mcp-adapter/oauth를 통해 협업 확장 기능이 URL 기반 OAuth 토큰 재사용 가능
• 이벤트 버스 — 확장 기능은 버전화된 채널에 구독해 읽기 전용 서버 상태 스냅샷 수신 가능

보안 세부 사항: 어댑터는 외부 호스트 파일을 수정하지 않으며, 그 파일에서 조용히 명령어를 실행하지도 않습니다. 플러그인 심볼릭 링크가 디렉터리 외부로 나가는 것을 거부하며, OAuth 흐름의 비밀(예: CSRF 상태, PKCE 검증자)은 흐름 내부에 국한됩니다. 서버 비활성화는 프로젝트 로컬 오버라이드 파일에 disabled 플래그만 기록하고, 원본 파일은 그대로 유지됩니다.

왜 중요한가: 컨텍스트 창의 비용 없이 MCP 생태계에 접근할 수 있게 해주며, 에이전트가 필요한 순간에 도구를 탐색할 수 있도록 해줍니다. 모든 것을 미리 로드할 필요가 없습니다.