pi-mcp-adapter MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

One proxy tool (~200 tokens) instead of hundreds of tool schemas
On-demand tool discovery via search and describe verbs
Lazy / eager / keep-alive server lifecycle modes
Optional 'direct tools' promote hot tools to first-class Pi tools (~150-300 tokens each)
Bearer + OAuth (authorization code, client credentials) support

라이브 데모

실제 사용 모습

pi-mcp-adapter.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pi-mcp-adapter": {
      "command": "npx",
      "args": [
        "-y",
        "pi-mcp-adapter"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "pi-mcp-adapter": {
      "command": "npx",
      "args": [
        "-y",
        "pi-mcp-adapter"
      ],
      "_inferred": true
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "pi-mcp-adapter": {
      "command": "npx",
      "args": [
        "-y",
        "pi-mcp-adapter"
      ],
      "_inferred": true
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "pi-mcp-adapter": {
      "command": "npx",
      "args": [
        "-y",
        "pi-mcp-adapter"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "pi-mcp-adapter",
      "command": "npx",
      "args": [
        "-y",
        "pi-mcp-adapter"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "pi-mcp-adapter": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "pi-mcp-adapter"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add pi-mcp-adapter -- npx -y pi-mcp-adapter

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: pi-mcp-adapter

Run Pi with 10+ MCP servers without blowing the context window

👤 Power users of the Pi coding agent ⏱ ~20 min intermediate

언제 쓸까: You want filesystem, git, github, postgres, playwright, fetch, firecrawl — more than Pi can eagerly load.

사전 조건

Pi installed — See badlogic/pi-mono

흐름

Install the adapter

Run pi install npm:pi-mcp-adapter and restart Pi.✓ 복사됨

→ Adapter listed in Pi's extensions
Configure all your MCPs

Add filesystem, git, github, postgres MCPs to pi-mcp-adapter in lazy mode.✓ 복사됨

→ Servers registered; no boot overhead
Use via search

Use mcp({search: 'list files'}) to find the right tool, then call it.✓ 복사됨

→ Relevant tool surfaced; then called

결과: Full MCP ecosystem available inside Pi, with a tiny context footprint.

함정

Search misses a tool because description is bad — Promote frequent tools to 'direct tools' so Pi sees them eagerly

Promote your 3 most-used MCP tools to first-class Pi tools

👤 Devs who use Pi daily ⏱ ~10 min beginner

언제 쓸까: You notice Pi calling mcp({search: ...}) every time before using filesystem read — add it as a direct tool to skip the dance.

흐름

Identify hot tools

Which mcp tool calls show up most in my recent Pi session logs?✓ 복사됨

→ Top-N list
Mark as direct

Configure these as direct tools in pi-mcp-adapter settings.✓ 복사됨

→ Tools now appear as first-class Pi tools

결과: Faster agent loop + lower token spend on repetitive tool discovery.

함정

Too many direct tools = defeats the purpose — Keep direct-tool count to ≤5; promote only if frequency is high

Use OAuth-protected MCP servers (e.g. Linear, Slack) with Pi

👤 Pi users on enterprise MCPs ⏱ ~15 min intermediate

언제 쓸까: Your MCP server requires OAuth and you'd rather not hand-craft token refresh.

흐름

Enable autoAuth

Set autoAuth: true in pi-mcp-adapter config for the linear server.✓ 복사됨

→ Pi opens browser on first use
Authorize in browser

Approve the scope request; tokens are persisted.✓ 복사됨

→ Subsequent calls use refreshed tokens automatically

결과: OAuth-protected MCP integrations 'just work' in Pi.

함정

Tokens stored unencrypted on disk — Use an encrypted home directory or OS keychain bridge

조합

다른 MCP와 조합해 10배 효율

pi-mcp-adapter + filesystem + git-2 + github

Full dev loop inside Pi with lazy tool loading

Register filesystem, git, and github via pi-mcp-adapter in lazy mode.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
mcp	{search?: str} \| {describe?: str} \| {tool?: str, args?: JSON-string}	Universal proxy — the only tool Pi sees by default	~200 tokens eager + on-demand tool execution
/mcp-auth <server>	server name	Manually trigger OAuth for a specific server	free

비용 및 제한

운영 비용

API 쿼터: None of its own — proxies to underlying MCPs
호출당 토큰: ~200 tokens eager overhead vs N*~500 for full tool listing
금액: Free, open source
팁: Start lazy. Only promote tools to direct when telemetry shows Pi calls them ≥5× per session.

보안

권한, 시크릿, 파급범위

자격 증명 저장: OAuth tokens in ~/.pi/mcp-adapter/ — treat as sensitive

데이터 외부 송신: Depends on configured upstream MCPs

Cross-session server sharing not implemented — each Pi session runs its own server processes (some memory cost).
Idle servers disconnect after 10 minutes by default — configurable via timeout setting.

문제 해결

자주 발생하는 오류와 해결

mcp({tool: ...}) says 'tool not found'

Tool name is case-sensitive and namespaced by server. Use describe first to get the exact name.

OAuth loop never completes

Adapter's local callback port may be blocked. Check the redirect URL matches what's registered with the provider.

Server starts but tool calls hang

Upstream MCP crashed silently. Switch to eager mode temporarily to see the boot error.

확인: pi-mcp-adapter logs

대안

pi-mcp-adapter 다른 것과 비교

대안	언제 쓰나	단점/장점
Raw MCP integration	You run Pi with only 1-2 MCP servers	Simpler, but eats context as you add servers
mcp-gateway	You need security/PII redaction across many MCPs (not just token efficiency)	Python gateway; aimed at security more than token-saving

pi-mcp-adapter