+- **`pi-mcp-py`: an optional extension that connects the MCP servers an ACP client passes (new package `packages/pi-mcp`, version 0.1.0)**: an editor such as Zed passes its MCP servers in `session/new`. With this package installed, the agent connects them (stdio, Streamable HTTP and SSE) and gives their tools to the model. The core, the harness and the CLI still have no MCP client, and the agent still reads no `mcp.json`; the extension takes the servers from `pi.client_mcp_servers` and claims them, so the notice "its tools are not available" does not appear. Without the package, nothing changes. **Tools**: each tool is named `mcp__<server>__<tool>` (letters, digits, `_` and `-`; at most 64 characters, cut with a hash; a repeated name gets `_2`, `_3`). The prefix is needed: a tool of an extension that has the name of a built-in tool replaces it, and an MCP tool named `bash` would take over `bash`. The permission mode `ask` asks about every MCP tool call unless the server declares the tool harmless (`readOnlyHint`, or neither destructive nor open-world), as for all tools. A result is text; text over 50 KB is cut with a note, a result with only `structuredContent` is sent as JSON text, and an MCP error result becomes an error tool result. **One task for each server**: the MCP SDK uses `anyio` cancel scopes, which must end in the task that began them. `session_start` starts the servers and returns at once; a turn waits at most 10 s for servers that are still starting (`session/cancel` ends the wait) and then goes on without them. A server that is slower sends one notice, and its tools join in a later turn. **Limits** (environment variables): `PI_MCP_STARTUP_TIMEOUT` (60 s) and `PI_MCP_CALL_TIMEOUT` (120 s); a call also ends when the user cancels the turn. **When a server stops**: the user gets one notice for each server and kind of event (did not start, stopped, cannot reconnect), and a good start gets none, so a thread without MCP trouble stays blank. The next tool call connects the server again, at most 3 times in a row (a call that gets an answer starts the count again). A call that was already sent when the server died is not repeated, because the server may have run it. `/mcp` lists the servers (name, transport, state, number of tools), and `/mcp reconnect <name>` connects one again with no limit. **Secrets**: `env`, `headers`, `args` and `url` hold tokens. Notices, `/mcp`, errors and logs show only the server name, the name of the executable, or the host; the values of `env`, the values of `headers` and the URL are masked in error text. **Environment of a stdio server**: the default list of the MCP SDK, the proxy, certificate, locale and time zone variables, and the `env` of the client. `${VAR}` is not expanded (`langchain-mcp-adapters` would expand it from the environment of the agent, which has the LLM key, so the extension starts stdio servers itself), and the keys of the LLM provider are not passed. stderr of a server goes to `<home>/logs/mcp/<name>.log`, not to the stderr of the agent, where a full pipe would stop it. **Servers on this machine** are reached without the proxy of the system: `httpx` reads the proxy settings of Windows and does not skip loopback addresses. **End**: when the session closes, each server gets its stdin closed first, and then its process tree is stopped; a test checks that no process stays, on Windows and on Linux. **Not supported**: OAuth (it works only if the editor passes a token in `headers`; not verified), MCP resources, prompts, sampling and elicitation, a server shared by two sessions (each session starts its own), and a configuration file. A legacy SSE server whose POST fails ends a call only with the call timeout (the SDK hides the error). **Limits of the package**: it needs `pi-agent-core-lc` 0.6.0 or later; an older core makes it log a warning and do nothing. The `Release` workflow installs the package for its pre-release tests and builds it with the other packages, so the upload to PyPI has it (`pip install pi-mcp-py`). Tests: 192 in `packages/pi-mcp/tests` with real child processes (stdio, HTTP, SSE), the real `AgentHarness`, and the real `PiAcpAgent` over ACP, run on Windows and WSL. Design: `docs/specs/2026-10-23-mcp-extension-design.md`.
0 commit comments