[docs] Plan MCP product features after Pi parity

docs/design/agent-workflows/projects/mcp-product-features/README.md

@@ -0,0 +1,25 @@
+# MCP product features
+
+Status: planned, not implemented
+
+This is the separate slice 3 plan that follows the MCP public-contract cleanup and Pi slice 2.2.
+It covers connection testing, discovery, visible status, enforceable tool selection, credentials,
+OAuth, and the decision about where long-run MCP execution belongs.
+
+It does not change the saved `MCPServerConfig` shape defined by the cleanup project.
+
+## Documents
+
+- [Context](context.md)
+- [Research](research.md)
+- [Interface](interface.md)
+- [Plan](plan.md)
+- [QA](qa.md)
+- [Status](status.md)
+
+## Dependencies
+
+1. Slices 0-2: breaking contract and capability-gated UI.
+2. Slice 2.1: Claude local and Daytona no-secret acceptance.
+3. Slice 2.2: agreed Pi delivery bridge.
+4. This project: product features and long-run execution boundary.

docs/design/agent-workflows/projects/mcp-product-features/context.md

@@ -0,0 +1,23 @@
+# Context
+
+After the cleanup, users can save a truthful external HTTP MCP configuration for supported
+harnesses. They still cannot prove a server connects before a run, see discovered tools, diagnose
+initialization failures, or select tools from real server metadata. Static secret references
+exist in the contract, but OAuth and the long-run credential boundary do not.
+
+## Goals
+
+- Test the same connection behavior execution uses.
+- Show safe connection and initialization status.
+- Discover tools and let users select real tool names.
+- Enforce selection and permission at an execution boundary.
+- Add credential-backed and OAuth connections without storing values in revisions.
+- Choose the long-run execution boundary with evidence from Claude and Pi.
+
+## Non-goals
+
+- Reintroducing public stdio.
+- Adding a compatibility decoder or feature flag.
+- Changing the role-based saved object.
+- Treating prompt instructions as policy enforcement.
+- Choosing the MCP gateway before the Pi 2.2 plan establishes the actual bridge requirements.

docs/design/agent-workflows/projects/mcp-product-features/interface.md

@@ -0,0 +1,57 @@
+# Interface design
+
+## Stable saved object
+
+This project extends behavior around the existing roles:
+
+```json
+{
+  "name": "memory",
+  "connection": {
+    "type": "http",
+    "url": "https://memory.example.com/mcp",
+    "headers": {},
+    "credentials": {"type": "none"}
+  },
+  "policy": {
+    "tools": {"mode": "all"},
+    "permission": "ask"
+  }
+}
+```
+
+Connection results and discovered tools are not written into this object.
+
+## Connection test result
+
+```json
+{
+  "state": "connected",
+  "server": {"name": "Memory", "version": "1.2.0"},
+  "protocol_version": "2025-11-25",
+  "tools": [
+    {"name": "remember", "description": "Store a memory", "input_schema": {}}
+  ],
+  "error": null
+}
+```
+
+This is ephemeral protocol context owned by the MCP client. Errors use stable codes plus safe
+messages and never include headers or credential values.
+
+## OAuth credential
+
+```json
+{
+  "type": "oauth_connection",
+  "connection_ref": "memory-production"
+}
+```
+
+The referenced platform connection owns scopes, token refresh, revocation, and callback state.
+
+## Policy enforcement
+
+`all` exposes every discovered tool. `include` exposes only names in `policy.tools.names`.
+Enforcement applies to both list and call paths. A direct call to an excluded tool fails even if a
+model knows the tool name from earlier context.

docs/design/agent-workflows/projects/mcp-product-features/plan.md

@@ -0,0 +1,48 @@
+# Plan
+
+## Phase 0: prerequisites and measurements
+
+1. Finish Claude no-secret acceptance in local and Daytona.
+2. Finish the Pi 2.2 delivery design.
+3. Record where Claude and Pi own MCP or tool sessions, calls, and errors.
+4. Choose direct clients or gateway using latency, credential boundary, session ownership, and
+   operating cost.
+
+Exit: one documented execution owner, with rejected alternatives and migration consequences.
+
+## Phase 1: connect and status
+
+1. Add a test-connection operation that uses the chosen production client path.
+2. Return redacted initialization status, negotiated server identity, capabilities, and errors.
+3. Surface status in the MCP editor without mutating saved revisions.
+4. Add retry and reconnect only where the underlying client supports deterministic semantics.
+
+Exit: a user can distinguish saved, connecting, connected, and failed.
+
+## Phase 2: discovery and policy
+
+1. Return discovered tool schemas from the connection operation.
+2. Populate selection from discovery rather than free text.
+3. Persist explicit `all` or `include` intent.
+4. Enforce the same selection on tool listing and tool calls.
+5. Show renamed or missing selected tools without widening access.
+
+Exit: selected tools are observable and enforceable.
+
+## Phase 3: credentials
+
+1. Enable static header secret references on the chosen execution boundary.
+2. Add a platform OAuth connection resource and `oauth_connection` discriminator.
+3. Redact service, runner, gateway, ACP, sandbox, trace, and UI error surfaces.
+4. Test revocation, refresh, missing references, and host restrictions.
+
+Exit: no raw credential appears in a revision or user-visible response.
+
+## Phase 4: parity and rollout
+
+1. Run Claude and Pi across local and Daytona.
+2. Compare connect, list, call, policy denial, reconnect, and credential behavior.
+3. Publish capability details only for cells that pass.
+4. Add replay or deterministic integration coverage for each delivery adapter.
+
+Exit: the runtime catalog truthfully represents the supported matrix.

docs/design/agent-workflows/projects/mcp-product-features/qa.md

@@ -0,0 +1,25 @@
+# QA
+
+## Matrix
+
+For Claude and Pi on local and Daytona:
+
+- no-auth connect, list, and call;
+- invalid URL and failed initialization;
+- `all` and `include` tool policy;
+- excluded-tool direct call;
+- stale selected tool after upstream rename;
+- static header secret reference;
+- missing or revoked credential;
+- OAuth connect, refresh, and revoke;
+- reconnect after upstream interruption;
+- no credential values in logs, traces, responses, or saved revisions.
+
+## Release gates
+
+- The connection-test path and run path use the same MCP client behavior.
+- Status never claims connected before initialization completes.
+- Policy is enforced outside the model prompt.
+- Unsupported harness and environment cells omit the capability.
+- Internal `agenta-tools` never appears in external discovery or status.
+- A deterministic fixture or replay test covers every adapter.

docs/design/agent-workflows/projects/mcp-product-features/research.md

@@ -0,0 +1,33 @@
+# Research
+
+## Existing seams
+
+- Claude receives external HTTP MCP entries through ACP session initialization.
+- Pi uses the Agenta tool plane and does not currently consume ACP MCP entries.
+- The runner already validates external URLs and blocks unsafe SSRF targets.
+- The service already resolves project secret references per run.
+- Claude ACP exposes MCP status and reconnect surfaces, but Agenta discards that state.
+- The UI already consumes the runtime harness catalog and can gate feature surfaces per harness.
+
+## Architectural choice still open
+
+There are two credible execution shapes:
+
+1. Direct per-harness clients. Claude keeps ACP delivery and Pi gains a runner MCP client that
+   projects tools onto its existing tool plane.
+2. A platform MCP gateway owns upstream sessions, credentials, discovery, policy, and calls, then
+   projects tools onto the common Agenta plane for both harnesses.
+
+The gateway is attractive for credential isolation and parity, but it adds session ownership,
+scaling, routing, and observability work. The plan must compare those costs against the concrete
+Pi 2.2 bridge instead of assuming the answer.
+
+## Security facts
+
+- Saved configs may contain secret names, never values.
+- Direct Claude delivery puts resolved header values in service, runner, ACP, and harness process
+  memory.
+- Daytona secret facilities can narrow one remote path but do not solve local and Daytona with one
+  boundary.
+- A platform gateway can keep upstream values outside harness sandboxes, but only if it owns calls
+  rather than returning credentials to clients.

docs/design/agent-workflows/projects/mcp-product-features/status.md

@@ -0,0 +1,29 @@
+# Status
+
+Last updated: 2026-07-13
+
+## Stage
+
+Planning draft. No implementation started.
+
+## Locked
+
+- The saved role-based MCP object stays stable.
+- Public stdio remains absent.
+- Protocol status and discovered tools are ephemeral.
+- OAuth references a platform connection.
+- Tool policy must be enforced on list and call.
+- Pi 2.2 precedes this feature work.
+
+## Open decisions
+
+1. Direct per-harness MCP clients or platform gateway?
+2. Who owns upstream MCP session lifetime and reconnect state?
+3. Does a failed required MCP connection abort the run by default?
+4. What is the cache lifetime for discovery results?
+5. Which platform connection domain owns OAuth?
+
+## Next
+
+Complete the Pi 2.2 design, then resolve the Phase 0 execution-owner decision before defining
+endpoints or implementation PRs.