[refactor] Replace the public MCP server contract

[mmabrouk]

Context

The MCP editor exposed stdio commands, environment values, and manual tool names even though the hosted runner only delivers external HTTP MCP servers to Claude. MCP execution also depended on a service flag that was not available to the UI, so users could save a server and still see no MCP tools.

Changes

This is a breaking pre-production reset. There is no compatibility decoder, migration, feature flag, or dual write.

Before:

{"name":"memory","transport":"http","url":"https://example.com/mcp","env":{},"secrets":{},"tools":[]}

After:

{
  "name": "memory",
  "connection": {
    "type": "http",
    "url": "https://example.com/mcp",
    "headers": {},
    "credentials": {"type": "none"}
  },
  "policy": {"tools": {"mode": "all"}, "permission": "ask"}
}

The SDK now separates saved author intent from resolved secret-bearing headers. The runner accepts only the nested HTTP wire object and keeps its private trusted agenta-tools stdio shim separate.

The UI removes transport, command, arguments, environment, and manual exposed-tool controls. It shows external MCP authoring only when the selected harness publishes mcp.user_servers in the existing runtime harness catalog. Claude publishes it; Pi omits it until slice 2.2 works. Local Docker and Agenta Cloud use the same catalog, so this adds no frontend or cloud-specific environment variable.

Tests / notes

• 98 focused Python SDK and capability tests passed.
• 4 service MCP resolution tests passed.
• 110 runner MCP, run-plan, layering, and orchestration tests passed.
• 69 focused frontend request and capability tests passed.
• Runner, @agenta/entities, and @agenta/entity-ui TypeScript checks passed.
• Ruff, frontend pnpm lint-fix, and Helm lint passed.
• The web root has no typecheck script; the two touched packages passed tsc --noEmit.

What to QA

• Select Claude in the agent editor. The MCP section appears and a new server asks only for name, URL, public headers, and authentication.
• Select Pi. The MCP section is absent until slice 2.2 adds runtime support.
• Add a no-auth HTTPS MCP server on Claude local and Daytona. The saved revision contains the nested object and the runner delivers it through ACP.
• Regression: Agenta gateway tools still work through the private agenta-tools channel and never appear in this editor.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 13, 2026 9:33pm

[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: a1a9b0e0-f82f-4a35-8f0a-a3b94345eb66

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 refactor/mcp-public-contract

---

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: Coordination cleanup: the first version of this branch accidentally absorbed two unrelated cold-Pi continuity hunks from the shared sandbox_agent.ts worktree. I rewrote and force-pushed the branch under the GitButler lock. Commit 47a9539b27 now contains only this PRs intended MCP server.policy.permission hunk in that file; the Pi hunks and their test are isolated on PR #5284. Local and remote SHAs match.

[mmabrouk]

🤖 The AI agent says:

Updated this PR to address the documentation-sync review alongside the retarget conflict:

• removed the deleted AGENTA_AGENT_MCPS_ENABLED / agentRunner.enableMcp configuration from the shipped self-hosting page
• updated the public-edge, in-service, and runner interface inventories to the nested HTTP-only public contract
• updated all seven agent-workflows living-doc pages to distinguish external HTTP MCP from the trusted internal agenta-tools channel
• replaced the stale stdio/deleted-constant RTM rows and corrected the runner test comment
• preserved the upstream default-deny egress setup while resolving mcp-servers.test.ts

Verification: docs production build passed; 5 focused runner test files passed (118 tests); push hooks passed frontend lint and secret scanning. The branch is now based directly on current big-agents and GitHub CI is running.