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 использует ту же схему mcpServers, что и Claude Desktop. Конфиг проекта приоритетнее глобального.

VS Code → Cline → MCP Servers → Edit

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

Щёлкните значок MCP Servers на боковой панели Cline, затем "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 использует массив объектов серверов, а не map.

~/.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 — эффект x10

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

Ещё

Ресурсы

📖 Читать официальный README на GitHub

🐙 Открытые задачи

🔍 Все 400+ MCP-серверов и Skills