feat(mcp): add pi-mcp-py, an extension that connects the MCP servers a client passes - #36

Summary

Stacked on #35 (base: feat/client-mcp-hooks, which is on #34). Core and CLI still have no MCP client and do not import this package. This PR adds the optional package pi-mcp-py (module pi_mcp, entry point pi-mcp). It connects the MCP servers that the ACP client passes in session/new|load|resume, and gives their tools to the model.

session/new (mcp_servers) ──► pi.client_mcp_servers                       (#35)
  activate(pi)                                  entry point group pi_agent.extensions
    pi.claim_client_mcp_servers(names)          "I connect these"          (no "not connected" notice)
    session_start ──► Manager.start()           one runner task per server (stdio | http | sse)
                                                connect ─► initialize ─► list_tools ─► register
    pi.add_turn_barrier(manager.wait_started)   the first turn waits at most 10 s for a slow server
    pi.register_cleanup(manager.close)          ends every server process when the session ends
    /mcp, /mcp reconnect <name>

tool call: mcp__<server>__<tool>
  ServerConnection.call                         time limit 120 s; one retry only if the request was NOT sent;
                                                reconnect at most 3 times in a row
  shape_result                                  structuredContent -> text; text cut at 50 KB with a note; images kept

packages/pi-mcp/
├── pi_mcp/__init__.py     activate(), the /mcp command
├── pi_mcp/manager.py      the servers of one session: start, status, reconnect, close
├── pi_mcp/connection.py   one server: state machine, one runner task, calls, reconnect
├── pi_mcp/transport.py    stdio / Streamable HTTP / SSE; safe env of a child; direct client for this machine
├── pi_mcp/tools.py        names (max 64 characters), result shape
├── pi_mcp/errors.py       error text for the model, failure classes
├── pi_mcp/redact.py       env, headers, args and url of a server never reach a log, notice or error
├── pi_mcp/settings.py     PI_MCP_STARTUP_TIMEOUT, PI_MCP_CALL_TIMEOUT
└── tests/                 192 tests, a FastMCP mock server

Wiring: workspace member and testpaths in pyproject.toml; the CI test job installs the package (ci.yml); module-map row in AGENTS.md; README status row; CHANGELOG; the design (docs/specs/2026-10-23-mcp-extension-design.md) is synced with the code.

Release (last commit, ci(release)): release.yml installs the package for the pre-release tests and builds it (Build pi-mcp). publish-pypi uploads every file of dist/ and github-release attaches dist/*, so the next tag publishes pi-mcp-py 0.1.0 with the other packages. The README table and install lines, the package README (it is the PyPI description), the CHANGELOG and spec 9 say "on PyPI from 0.6.0".

Design points that are easy to miss:

• Tools are named mcp__<server>__<tool>. The harness lets an extension tool replace a tool of the same name, so a server with a tool named bash would take the place of the real bash without the prefix.
• The MCP SDK needs each cancel scope to end in the task that began it, so each server has one runner task. A transport that is ended by cancellation does not tell the pending requests; a call races a gone future (ConnectionEnded) instead of waiting for its time limit.
• httpx reads the proxy of the system (on Windows, the registry) and does not skip loopback addresses. A server at localhost, 127.0.0.1 or ::1 uses a client with trust_env=False.
• A stdio server gets the safe list of the MCP SDK, the proxy and certificate variables, and the env of the editor. It does not get the LLM keys of the agent.

Evidence

• Before (base of this PR, Zed passes its context7 server): the notice says the server is not connected. After: the model calls it.

  test_a_server_of_the_client_gives_the_model_its_tools
    new_session(mcp_servers=[stdio mock]) -> prompt
    before: "mcp__mock__echo" is not offered to the model
    after : offered; the call returns "echo: via acp"; no "ignored" message to the client
  

• Real server. The context7 server of Zed, started as Zed passes it (Zed has no system Node: its own node.exe runs the script of its extension): ready in 3.1 s, 2 tools (both with readOnlyHint), resolve-library-id("react") returned 1683 characters, no process left after close.

• Real model. PiAcpAgent (entry-point discovery, real stream function, config of the maintainer: deepseek / deepseek-flash) and that server in session/new: session/new answered in 0.45 s. The model called mcp__mcp-server-context7__resolve-library-id (argument names libraryName, query), got the 1683 characters, and answered with the library id /reactjs/react.dev. 10.1 s for the turn, stop_reason=end_turn, 0 permission requests (auto mode), 0 node processes after close_session.

• Tests. The 192 tests of packages/pi-mcp/tests pass on Windows with Python 3.11, 3.12 and 3.13, and on Linux (WSL2) with Python 3.12. Whole suite, run before the last test-only edits: Windows 2905 passed / 42 skipped; Linux 2931 passed / 16 skipped.

• 28 one-line mutations of pi_mcp (no prefix, whole environment to the child, no redaction, no second try for an unsent request, no time limit, no direct client for loopback, a name given twice, no cut of a long result, and others): every one makes at least one test fail. One survived at first (a tool registered again after a reconnect); the assertion is now exact and the mutation is caught.

• Release content (last commit). actionlint finds nothing in release.yml. A dry run of Release from this branch (run 40162795623; a manual run publishes nothing): Pre-release tests pass (the job now installs the package and runs its tests), Build Python packages pass with the new step Build pi-mcp, Publish to PyPI is skipped. The dist artifact has 14 files, among them pi_mcp_py-0.1.0-py3-none-any.whl and pi_mcp_py-0.1.0.tar.gz, and twine check --strict passes for all 14. The wheel has the eight modules and the pi-mcp entry point. I cancelled the two TUI build jobs of the run: this change does not touch them.

• ruff check . and ruff format --check .: clean, also with the CI-pinned ruff 0.16.0.

• Not done: OAuth; MCP resources, prompts, sampling, roots, elicitation, tools/list_changed; websocket servers. The legacy SSE transport of the SDK swallows the errors of its POST requests, so a call to a dead SSE server ends by its time limit. A session/new that Zed sends before its first worktree loads has an empty mcpServers (zed#64611); the agent cannot tell that from "no servers". Whether Zed gives OAuth tokens to an agent as headers is not verified.

Merge Danger

Door: two-way. It is a new package; nothing in core or CLI imports it. Uninstall pi-mcp-py and the agent is as after #35.

Blast Radius: the CI test job, and everyone who installs the package.

• The extension starts the commands that the client names (command and args of a stdio server). The editor has already asked the user (Zed keeps the servers of a project off in Restricted Mode until the worktree is trusted), so the agent does not ask a second time (spec 6.3). In ask mode, each MCP tool call is still asked about unless the server marks the tool readOnlyHint (or neither destructive nor open-world).
• CI: the test job installs one more package. Measured on the runs of feat(extensions): give extensions the MCP servers a client passes, a way to tell the user, and turn barriers #35 and this PR: Python 3.11 2m31s to 4m10s, 3.12 1m48s to 3m58s, 3.13 2m36s to 3m17s. All checks of this PR pass. tui-ci.yml is not changed.
• Release. The last commit changes release.yml (two edits: the install line of the pre-release tests, and the step Build pi-mcp). The next tag publishes pi-mcp-py 0.1.0 with the other packages. Three things that I cannot check from here:
  • The first upload of a new PyPI project needs a PYPI_API_TOKEN that may create projects (an account-wide token, or a pending publisher for the name). The name pi-mcp-py is free (/pypi/pi-mcp-py/json gives 404). With skip-existing: true, a re-run after a token fix is safe.
  • The floor pi-agent-core-lc>=0.5.0 in packages/pi-mcp/pyproject.toml must become >=0.6.0 with the version bump, because the extension needs the hooks of feat(extensions): give extensions the MCP servers a client passes, a way to tell the user, and turn barriers #35. test_extension_packaging.py fails until it does, so CI says so.
  • "From 0.6.0" in the docs is my assumption for the version of the next release.
• The notice of feat(extensions): give extensions the MCP servers a client passes, a way to tell the user, and turn barriers #35 tells the user to "install the pi-mcp-py package". That is true after the release that publishes it, so release soon after this merge.
• Design defaults that the maintainer can change are in spec 10 (Q1 to Q11).