[docs] Plan Pi MCP parity with pi-mcp-adapter

[mmabrouk]

Context

Pi cannot currently use the remote MCP servers configured on an agent. The shared service path already resolves those servers for every harness, but pi-acp stores ACP MCP entries without forwarding them into Pi. The latest checked pi-acp@0.0.31 still documents that limitation and points users to pi-mcp-adapter.

Changes

This design keeps the existing saved and resolved MCP objects unchanged and reuses pi-mcp-adapter only for Pi's harness-specific last mile.

Before:

ResolvedMCPServer[] -> Claude ACP MCP entries
ResolvedMCPServer[] -> Pi unsupported gate

Proposed:

ResolvedMCPServer[] -> Claude ACP MCP entries
ResolvedMCPServer[] -> temporary pi-mcp-adapter config

The first implementation slice uses the adapter's default proxy tool because it works on the first process start. Cache-backed direct tools, OAuth, public stdio, MCP UI, probing, compatibility logic, and the future gateway remain out of scope. Local and Daytona use the same renderer and asset path.

Tests / notes

• Verified the current runner pins pi-acp@0.0.29 and Pi 0.80.6.
• Verified latest pi-acp@0.0.31 still does not wire MCP into Pi.
• Reviewed pi-mcp-adapter@2.11.0 HTTP, header, proxy, and direct-tool behavior.
• Verified the remote PR diff against big-agents contains only the seven design files.

Review focus: whether proxy-first is the right MVP presentation, and whether the temporary secret-bearing adapter-config lifecycle matches the intended harness boundary.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 14, 2026 1:23am

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c7efee3b-f14d-4d51-9e89-a6d121aa88c0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/pi-mcp-parity

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

🤖 The AI agent says:

This is the Pi MCP parity design requested after #5296 and #5297. Please focus review on two decisions:

1. Use upstream pi-mcp-adapter in proxy mode for the first slice, avoiding direct-tool cache warm-up and restart logic.
2. Render the existing ResolvedMCPServer[] into a temporary, secret-bearing adapter config with the same lifecycle locally and on Daytona.

The public MCP object, service secret resolution, frontend UI, and future gateway boundary do not change.