nicobailon/pi-mcp-adapter v5.0.0

on GitHub

pi-mcp-adapter 5.0.0 makes the adapter the one place Pi runs MCP. Servers you added with pi mcp add, servers other extensions register, sign-ins from Pi's built-in MCP, and tokens from Pi's /login all work here now. It also runs far fewer servers: each one is discovered at startup and then stopped until you use it, so a big server list no longer means a big pile of running processes. Servers you rarely use stay searchable, long tools that report progress no longer time out, and a stray Enter can no longer approve a project server.

Highlights

• Works with Pi's own MCP setup. Pi's mcp.json files, pi.registerMcpServer() servers, built-in MCP sign-ins, and /login provider tokens all work in the adapter.
• Only the servers you use stay running. With 100 servers installed and 3 in use, 3 run instead of 100.
• Rarely used servers stay searchable. Cached tools no longer expire after a week.
• pi-mcp-adapter doctor checks your servers from a shell or CI.
• Fewer surprises. Long tools that report progress keep going, and the project-server approval prompt now starts on "Don't allow".

Need to know

Full changelog

Highlights

• The adapter now works with Pi's own MCP setup: servers added with pi mcp add, servers other extensions register, sign-ins made with Pi's built-in MCP, and provider tokens from Pi's /login all work here.
• Far fewer servers stay running. Servers are discovered at startup and then stopped until you use them, so with 100 servers installed and 3 in use, only those 3 run.
• Servers you rarely use stay searchable. Cached tools no longer expire after a week.
• pi-mcp-adapter doctor checks your servers from a shell or CI.
• Long tools that report progress no longer time out, and a stray Enter can no longer approve a project server.

Breaking

• On Pi 0.99 and later, the adapter replaces Pi's built-in MCP extension in sessions, except when a host supplies its own config through createMcpAdapter(): /mcp opens the adapter, and the built-in no longer connects servers. On the first start after you install or update the adapter, it also turns the built-in off in Pi's user settings ("-builtin:mcp", as pi config writes), so Pi stops warning that the built-in was not loaded. Turning it back on in pi config sticks. Shell pi mcp commands still use Pi's own files. See Pi's built-in MCP.
• pi-mcp-adapter/config exports getPiMcpGlobalConfigPath() and getProjectPiMcpConfigPath() instead of getLegacyPiMcpGlobalConfigPath() and getLegacyProjectPiMcpConfigPath().

Added

• On Pi 0.99 and later, the adapter also reads Pi's ~/.pi/agent/mcp.json and .pi/mcp.json, so servers added with pi mcp add work here. Each file sits right below the mcp-adapter.json in its folder. Pi settings without an exact adapter equivalent are ignored, and entries the adapter can't run, such as SSE servers, are skipped; both are reported at startup, and a loaded server's ignored settings are also listed under it in /mcp-adapter. .pi/mcp.json servers need project trust and approval, and exclusive mode reads neither file. See configuration.
• On Pi 0.99 and later, the adapter connects servers that other extensions add with Pi's pi.registerMcpServer(), so Pi no longer reports them as unconnected. They are translated like Pi's mcp.json entries and are proxy-only: direct and deferred exposure are ignored and reported. A config entry or an earlier registerMcpServer() registration of the same name wins, and the registration is reported as overridden. Registering a name again with a different config replaces the server, and unregistering disconnects it. See the extension API.
• On Pi 0.99 and later, sign-ins made with Pi's built-in MCP can be imported: interactive sessions ask once per OAuth server whose exact URL has a sign-in in Pi's ~/.pi/agent/mcp-auth.json and none in the adapter, and ctrl+p in /mcp-adapter imports every eligible server. If the server rotates refresh tokens, the adapter's first refresh can sign Pi's shell pi mcp commands out. See Import a sign-in from Pi's built-in MCP.
• HTTP servers accept "auth": { "provider": "<name>" }, in adapter config and Pi's mcp.json, to send the token of a provider you signed in to with Pi's /login (Pi 0.99.2 or later). The token is read on every request and sent only to the server's origin, never through a redirect. User-global config only, and https except on loopback. Without a token the server needs /login <provider>; it never starts MCP OAuth. See Pi provider tokens.
• pi-mcp-adapter doctor [--json] checks your MCP servers from a shell or CI: each enabled server's state, tool count, and error or hint, exiting 1 when one fails. The report prints before connections close, and a failed shutdown also exits 1. It follows project trust and never starts OAuth. See Check servers from a shell.
• Server entries accept a description, the same key as Pi's mcp.json. mcp({ server }) shows it, mcp({ search }) ranks the server's tools by it, and the /mcp-adapter panel shows it when you expand the server, falling back to the first line of the server's instructions.

Changed

• Startup no longer leaves every server running until the idle timeout. At each start, the adapter discovers servers whose cached tools are missing, from an older config, or past a server-declared TTL, 10 at a time, saves them together, and stops plain lazy servers right away; they start again on first use. Before, only the first session discovered servers, so a server added later stayed unsearchable until it was used. A lazy or lazy-keep-alive server that fails discovery or needs sign-in is tried once per config: later sessions don't start it until its config changes or it is used. Temporary HTTP outages are retried next session.
• Cached tool metadata no longer expires after 7 days. Servers you rarely use used to drop out of search a week after the first session. An entry now stays valid until the server's config changes or a TTL the server declared runs out, and it is refreshed the next time the server connects. A prompt command whose cached arguments are out of date no longer rejects the call: it connects, refreshes them, and checks again.
• A tool call's timeout (requestTimeoutMs, or the MCP SDK default of 60 seconds) now restarts whenever the tool reports progress, as in Pi's built-in MCP, so a long tool that keeps reporting progress no longer times out. Tool calls always ask the server for progress, with or without a UI.
• On Pi 0.99 and later, directTools: "search" tools are Pi deferred tools. Pi's tool_search finds them, and Pi keeps their activation on the session branch, so it survives a resume. Permission extensions see their MCP annotations, and codemode scripts get their CallToolResult. Calls still go through the adapter's approval and output limits. See search-activated direct tools.
• Choosing direct tools is faster when many servers use includeTools or excludeTools: with 100 servers × 50 tools, about 1 second → 60 ms.
• The README is now a short overview. The full reference moved into docs/: configuration, server options, authentication (formerly OAUTH.md), using MCP tools, scripting, prompts and MCP UI, and the extension API.
• The README compares the adapter with Pi's built-in MCP on what you get by switching: with 100 servers installed and 3 used, Pi 0.99.2 keeps all 100 running (7.0 GB) while the adapter runs only the 3 in use; single tool lookups cost 10–33% fewer tokens than the built-in's default codemode; and with a System One key, semantic search put the right tool first in 10 of 11 test requests, where word search did in 5. See the full comparison.

Fixed

• Pressing Enter at the project-server approval prompt no longer approves the server. The prompt now starts on "Don't allow", so a first prompt typed while it is open can't approve a server by accident; choose "Allow" to approve it. Thanks to @meirm for #797.
• Idle shutdown no longer closes a server that is still in use. A tool call waiting for approval, an open MCP UI page, and an accepted browser (URL) request now keep the server running, so the approved call, a UI button, or the retry after the browser step no longer fails because the server was stopped meanwhile.
• Ending or switching a session no longer prints MCP: runtime cleanup failed: Cannot access 'scopedMaterializedResourceSessions' before initialization, and temp files from binary MCP resources are removed again. Thanks to @wu546526 for #781.
• Connecting to Figma (desktop) while its server is off now says nothing is listening on 127.0.0.1:3845 instead of a bare fetch failed.
• /mcp-adapter setup adds Figma (desktop) to the global config instead of writing .mcp.json into whatever project you opened setup from.
• /mcp-adapter setup warns when a server you add won't be used, because another config file already defines or disables it, or the current config mode doesn't read the file it was written to.
• A bearer token or header value that isn't a valid HTTP header value, such as one containing a newline, no longer appears in connection errors. This covers bearerToken (including !command and ${VAR} forms), bearerTokenEnv, and configured headers; the error now names the server and header instead.