feat: add secret-aware fetch gateway

AGENTS.md

@@ -18,7 +18,7 @@ This file is intentionally brief. Detailed instructions live in focused docs:
   - [docs/agents/oxlint-js-plugins.md](./docs/agents/oxlint-js-plugins.md)
   - [docs/agents/remix/index.md](./docs/agents/remix/index.md)
   - [docs/agents/cloudflare-agents-sdk.md](./docs/agents/cloudflare-agents-sdk.md)
-  - [docs/agents/mcp-apps-starter-guide.md](./docs/agents/mcp-apps-starter-guide.md)
+- [docs/agents/mcp-apps-spec-notes.md](./docs/agents/mcp-apps-spec-notes.md)
 - MCP capabilities (search/execute graph, domains, registry):
   - [docs/agents/adding-capabilities.md](./docs/agents/adding-capabilities.md)
 - Project setup references:

docs/agents/adding-capabilities.md

@@ -3,6 +3,11 @@
 User-persisted codemode skills (`meta` domain) are documented in
 [`mcp-skills.md`](./mcp-skills.md).
 
+Secret-bearing outbound requests are governed by
+[`secret-host-approval.md`](./secret-host-approval.md). Read that doc before
+adding any capability or workflow that saves secrets, uses placeholder-based
+`fetch`, or discusses host approval.
+
 Kody exposes a compact MCP surface (`search` and `execute`) and keeps the real
 capability graph behind that surface. To add a new capability, register it
 through a **domain** and the **builtin registry**—do not add a new public MCP
@@ -188,6 +193,10 @@ Keep handlers focused on host-side work. The sandboxed model code should only
 orchestrate capability calls; it should not hold credentials or perform raw
 network access.
 
+For secret-aware outbound requests, treat host approval as admin-only policy. Do
+not add MCP-side or execute-time mutation paths for a secret's allowed hosts.
+Only the authenticated account admin UI may widen that policy.
+
 `CapabilityContext` provides:
 
 - `env`: access to Cloudflare bindings such as D1, KV, R2, AI, and Worker
@@ -202,6 +211,13 @@ Use handlers for things like:
 - Cloudflare product APIs
 - containers or sandbox orchestration
 
+If a capability surfaces secret metadata or secret-using network behavior, make
+the description explicit about the approval model:
+
+- secret save/update does not authorize outbound use
+- a blocked host must be approved through the account admin UI
+- the agent should stop and surface the approval link instead of retrying
+
 ## Testing
 
 Public MCP behavior should be verified through the compact tool surface:

docs/agents/mcp-apps-spec-notes.md

@@ -0,0 +1,27 @@
+# MCP Apps Spec Notes
+
+This repo currently uses one generic MCP Apps shell rather than a family of app
+implementations. For MCP Apps behavior, prefer the upstream spec and API docs
+over project-local conventions.
+
+## Read First
+
+- [MCP Apps API docs](https://apps.extensions.modelcontextprotocol.io/api/)
+- [MCP Apps stable spec](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx)
+- [MCP UI introduction](https://mcpui.dev/guide/introduction)
+- [`@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps)
+
+## Repo-Specific Notes
+
+- The repo exposes a single generic shell via `open_generated_ui`.
+- Saved apps are reopened by `app_id`; inline renders are ephemeral.
+- If an OAuth provider requires a callback URL, use a persisted hosted saved app
+  rather than an inline render.
+- For secret-bearing requests and host approval policy, also read
+  [`secret-host-approval.md`](./secret-host-approval.md).
+
+## Relevant Code
+
+- `packages/worker/src/mcp/tools/open-generated-ui.ts`
+- `packages/worker/client/mcp-apps/generated-ui-shell.ts`
+- `packages/worker/client/routes/saved-ui.tsx`