pi-mcp-adapterCAUTION
Token-efficient MCP adapter for Pi coding agent
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
Use MCP servers with Pi without burning your context window.
https://github.com/user-attachments/assets/4b7c66ff-e27e-4639-b195-22c3db406a5a
Why This Exists
Mario wrote about why you might not need MCP. The problem: tool definitions are verbose. A single MCP server can burn 10k+ tokens, and you're paying that cost whether you use those tools or not. Connect a few servers and you've burned half your context window before the conversation starts.
His take: skip MCP entirely, write simple CLI tools instead.
But the MCP ecosystem has useful stuff - databases, browsers, APIs. This adapter gives you access without the bloat. One proxy tool (~200 tokens) instead of hundreds. The agent discovers what it needs on-demand. Servers only start when you actually use them.
pi-mcp-adapter vs Pi's built-in MCP
Since then, Pi 0.99 added MCP support of its own, which also keeps tool definitions out of context. Installing the adapter replaces it in Pi sessions. What you get by switching:
- Install many servers without paying for idle ones. The built-in starts every enabled server in every Pi session and keeps it running until the session ends. By default, the adapter starts a server when the model first calls it and stops it after 10 idle minutes.
- Fewer tokens on everyday calls. By default, the built-in runs every MCP call as a
codemodescript, even a single lookup. The adapter's scripts are off by default, so a lookup is one small JSON call to themcptool, which cost 10–33% less in our tests. For bulk work across many records, turn scripts on withsettings.scriptMode; then it costs about the same ascodemode. - More servers work fully. Servers can ask you questions through forms, show interactive UIs, and offer prompt templates as slash commands. The bui
393ccd3364d6OBSERVED · 2026-10-12Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add pi-mcp-adapter --env CHILD_SECRET=${CHILD_SECRET} --env MCP_AUTH_URL=${MCP_AUTH_URL} --env MCP_HASH_TOKEN=${MCP_HASH_TOKEN} --env MCP_OAUTH_CALLBACK_PORT=${MCP_OAUTH_CALLBACK_PORT} -- npx -y [email protected]{
"mcpServers": {
"pi-mcp-adapter": {
"command": "npx",
"args": [
"-y",
"[email protected]"
],
"env": {
"CHILD_SECRET": "${CHILD_SECRET}",
"MCP_AUTH_URL": "${MCP_AUTH_URL}",
"MCP_HASH_TOKEN": "${MCP_HASH_TOKEN}",
"MCP_OAUTH_CALLBACK_PORT": "${MCP_OAUTH_CALLBACK_PORT}"
}
}
}
}Exposed tools (68)
65 read · 3 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
abort_pending | read | Waits for a pending input handler |
add_comment | write | Add a comment to an issue. |
add_label | write | Add a label to an issue. |
alpha | read | Expanded alpha description |
app | read | App |
app_only | read | App |
both | read | Both |
brief | read | Daily brief on a topic |
classic_initialize_reached | read | Classic initialize completed |
close_app | read | Close the demo app |
close_issue | read | Close an issue, optionally posting a comment first. |
create_note | write | Create a note. |
date | read | Optional ISO date |
demo_lookup | read | New lookup |
demo_read_guide | read | Live guide |
demo_search | read | Search demo v2 |
do-thing | read | Current |
do_thing | read | Do thing |
echo | read | Echo a value and record receipt |
fail | read | Return an MCP tool error |
fallback_read_manual | read | Cached manual |
find | read | Find |
find_records | read | Find records |
fixture_control | read | Controls the modern listen fixture |
fresh | read | Fresh tool |
fresh_prompt | read | Fresh prompt |
fresh_tool | read | Fresh tool |
get_issue | read | Get one issue by number. |
get_nodes | read | Nodes |
get_nodes_secret | read | Secret nodes |
get_pull | read | Get one pull request by number. |
get_screenshot | read | Screenshot |
get_transcript | read | Get a meeting transcript as plain text. |
haiku | read | Compose a haiku |
hang | read | Never resolves |
launch_app | read | Launch the demo app |
legacy_after_sibling_probe | read | Classic initialize completed after disposable probe exit |
legacy_complete | read | Legacy result without a resultType |
list | read | List things |
list_issues | read | List issues in the repository. Results are paginated; request further pages until fewer than per_page items are returned. |
list_labels | read | List repository labels. |
list_projects | read | List projects |
list_pulls | read | List pull requests. Paginated like list_issues. |
list_transcripts | read | List meeting transcripts. |
lookup | read | Lookup from disk |
mcp__team_docs | read | Team docs |
modern_discovery_reached | read | MCP 2026-07-28 negotiation completed |
namespace.tool | read | Namespaced tool |
namespace_tool | read | Underscored |
needs_ui | read | Needs an input handler |
old | read | Old tool |
one_round | read | One input-required round |
other | read | Other |
other_tool | read | Another tool |
read | read | Read a file |
read_namespace.tool | read | Tool before colliding resource |
search | read | Search |
search-records | read | Search |
search_docs | read | Search product documentation. Returns matching sections as markdown. |
search_records | read | Failed |
show_chart | read | |
sized | read | Return an exact-sized UTF-8 JSON result |
stale | read | Stale |
stream_adventure | read | |
topic | read | Topic to summarize |
two_rounds | read | Two input-required rounds |
unselected | read | Not selected |
visible | read | Visible |
Trust audit
CAUTIONgrade C · trust 76/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- none-observed
- Network
- none-observed
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- found
Findings (25)
console.log(`MCP Auth: Token expired for ${serverName}, attempting refresh`);console.log(`MCP Auth: Token expired for ${serverName}, attempting refresh`)const SECRET = "sk-host-managed-sentinel-7f3a";
const token = "synthetic-secret-never-real";
-----BEGIN PRIVATE KEY-----
writeJson(join(home, ".pi", "agent", "settings.json"), { packages: ["git:../../outside-package"] });import { runMcpScript } from "../../mcp-code.ts";import type { McpExtensionState } from "../../state.ts";import { createRequestHeadersCommandFetch } from "../../request-headers-command.ts";serverName: "../../server",
it("does not exfiltrate the baked VK when a url-only override repoints the server", async () => {- `SYSTEMONE_ENDPOINT` can point at a System One server on your own machine, such as `http://127.0.0.1:8080/v1/systemone`. Plain `http` is accepted only on `localhost`, `127.0.0.0/8`, and `[::1]`; eve
- `/mcp-adapter setup` offers Figma (desktop) when the Figma app is installed. It adds the app's local server at `http://127.0.0.1:3845/mcp` and, if nothing answers there yet, says how to turn it on i
- OAuth callbacks now default to `http://127.0.0.1:<port>/callback` instead of `localhost`, as RFC 8252 recommends. Servers that reject `localhost`, such as Lovable, now work without extra setup. If a
url: `http://127.0.0.1:${address.port}/mcp`,url: `http://127.0.0.1:${address.port}/mcp`,@modelcontextprotocol/ext-apps, @modelcontextprotocol/sdk, chart.js, mermaid, zod, esbuild, typescript
@modelcontextprotocol/ext-tasks, @napi-rs/keyring, ajv, ajv-formats, cross-spawn, open, smol-toml, strip-json-comments
- 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- Jev can send System One requests to any HTTPS provider endpoint set in `SYSTEMONE_ENDPOINT`. TypeSafe stays the default. API keys are stored per endpoint, and an invalid endpoint turns Jev off inste
- Each Pi session runs its own server processes; [rmcp-mux](https://github.com/nicobailon/pi-mcp-adapter/blob/main/docs/servers.md#shared-mcp-processes-with-rmcp-mux) can share one across sessions
Servers defined or changed by project-scoped MCP files (`.mcp.json`, `.pi/mcp-adapter.json`, and opted-in ancestor project files) do not run merely because a repository was opened. This includes serve
`pi-mcp-adapter doctor` loads the config a session in the current directory would (including Pi's own `mcp.json` files when `pi --version` reports 0.99 or later), gives each enabled server 15 seconds
banner.png
pi-mcp.mp4
Gates applied: no_behavioural_pass.
393ccd3364d6full audit observations/trust-audit/mcp-server/nicobailon__pi-mcp-adapter.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-12 | 393ccd3364d6 | CAUTION | C | 76 | first audit |
Questions
What is the pi-mcp-adapter MCP server?
Token-efficient MCP adapter for Pi coding agent
What tools does pi-mcp-adapter expose?
68 in total: 65 read-only, 3 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is pi-mcp-adapter safe to connect to an agent?
With care. The audit graded it C (76/100) and found 25 things worth knowing before you trust this server, listed below with the exact line each was found on.
What credentials does pi-mcp-adapter need?
It reads CHILD_SECRET, MCP_AUTH_URL, MCP_HASH_TOKEN, MCP_OAUTH_CALLBACK_PORT, MCP_OAUTH_DIR, MCP_TEST_BEARER_TOKEN, MCP_TEST_BEARER_TOKEN_ENV, MCP_TEST_MALFORMED_TOKEN, OPENROUTER_API_KEY, PI_MCP_ADAPTER_DISABLE_AUTH_CACHE, PI_MCP_ADAPTER_DISABLE_KEYRING_RECOVERY and PI_MCP_ADAPTER_FAKE_KEYRING_STORE from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does pi-mcp-adapter run?
It speaks stdio and streamable-http, so it runs as a local process your client starts. It is published on npm as pi-mcp-adapter at 5.2.0.
How current is this page?
The grade is for one exact copy of the source (393ccd3364d6), read on 2026-10-12. The repository is watched and re-audited when it changes.