docs(agent): plan — restore gateway-tool MCP for Claude Code (decision needed)

[mmabrouk]

Context

PR #4831 ("enforce sidecar trust + disable unenforceable sandbox boundaries") disabled the sidecar's stdio MCP implementation to close a real hole: user-declared stdio/NPX MCP servers launch arbitrary processes on the runner host, outside the sandbox boundary. That disable was correct.

But it took out a second, unrelated thing as collateral. The same MCP_UNSUPPORTED_MESSAGE gate was the only channel that delivers Agenta gateway/callback tools to harnesses that accept tools over MCP only — i.e. Claude Code. So today a Claude run that carries gateway tools hard-fails (the fail-loud capability gate added afterward now refuses it). Two different layers were conflated into one switch.

This plan separates them: keep the user-facing stdio MCP capability disabled, and restore only the internal gateway-tool MCP delivery channel — the one the runner synthesizes itself from the run's resolved tools, which only ever carries public tool metadata (credentials stay server-side via the existing relay).

Scope

Design only. No code, no wire/SDK/protocol/golden-fixture change in this PR. It documents the layering distinction, why the internal channel is secure, the recommended transport, and the test/QA plan. Implementation is queued after the decision below lands.

The plan

See docs/design/agent-workflows/projects/gateway-tool-mcp/plan.md. status.md in the same folder is the source of truth for decisions and open questions; README.md holds the three-layer table at the heart of it.

https://claude.ai/code/session_01GYo3UEfvsZpncagqb28Mbc

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jun 25, 2026 12:51pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

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: c4388122-d39f-4cb1-bec1-ee5e8b0620e3

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/gateway-tool-mcp-plan

---

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]

🔸 Decision needed (this is a design decision, not a code review):

1. Transport — deliver gateway tools to Claude via an internal loopback HTTP MCP (recommended: no host process, matches feat(agent): enforce sidecar trust + disable unenforceable sandbox boundaries #4831's security intent) OR restore a scoped stdio bridge (simpler, but re-adds a host process). ← the real choice.
2. Daytona delivery — keep the existing file relay on Daytona (already works) + HTTP advertisement for local. Proposed default — confirm or adjust.
3. Naming — rename the user-facing MCP-unsupported constant so the internal channel never borrows it. Trivial — confirm.

Recommendation: option 1 for transport; accept 2 and 3 as-is. Once you pick, I'll queue the implementation.

[mmabrouk]

lgtm