@agent-native/core 0.21.0 → 0.22.0

package/docs/content/external-agents.md

@@ -8,7 +8,7 @@ search: "Claude ChatGPT Claude Code Codex Cursor Claude Cowork MCP Apps agent-na
 
 An agent-native app is reachable by any MCP-compatible host — Claude, Claude Desktop, Claude Code, ChatGPT custom MCP apps, Codex, Cursor, Claude Cowork, VS Code GitHub Copilot, Goose, Postman, MCPJam, and future clients that implement the standard. External agents are great at producing artifacts (a draft, an event, a dashboard) but they often live in a terminal or another app. Without a bridge, the user gets a wall of JSON and has to go find the thing.
 
-The external-agent bridge closes the loop. First you connect your own agent to a **hosted** app — one command, no token copying where we can write the client config, or a standard remote MCP endpoint everywhere else. Then the agent does the work over MCP and hands the user either an inline **MCP App** UI in compatible hosts or a single **"Open in <app> →"** link that opens the real app focused on exactly what was produced. It reuses the existing `navigate` / `application_state` contract the UI already drains every 2s (see [Context Awareness](/docs/context-awareness)) — there is no second navigation mechanism.
+The external-agent bridge closes the loop. First you connect your own agent to a **hosted** app — one command writes the local client config, using standard remote MCP OAuth for clients that support it and a browser-authorized bearer fallback for older clients. Then the agent does the work over MCP and hands the user either an inline **MCP App** UI in compatible hosts or a single **"Open in <app> →"** link that opens the real app focused on exactly what was produced. It reuses the existing `navigate` / `application_state` contract the UI already drains every 2s (see [Context Awareness](/docs/context-awareness)) — there is no second navigation mechanism.
 
 ## Connect Claude Code, Codex, Cursor, and Cowork {#connect}
 
@@ -26,15 +26,19 @@ Or run the same command through npm without installing anything globally:
 npx @agent-native/core connect https://mail.agent-native.com
 ```
 
-This opens your browser at the app. You are already logged in, so you just click **Authorize** once. The command then asks which local agent clients should receive MCP config. All clients are preselected the first time; after you choose, the selection is saved to `~/.agent-native/connect.json` so the next run can reuse it with Enter, or you can edit the checked items.
+The command asks which local agent clients should receive MCP config. All clients are preselected the first time; after you choose, the selection is saved to `~/.agent-native/connect.json` so the next run can reuse it with Enter, or you can edit the checked items.
 
-| Local client                  | Config written by `connect`                                 |
-| ----------------------------- | ----------------------------------------------------------- |
-| Claude Code / Claude Code CLI | `.mcp.json` or `~/.claude.json`, depending on `--scope`     |
-| Codex                         | `~/.codex/config.toml` under `[mcp_servers.<app>]`          |
-| Claude Cowork                 | `~/.cowork/mcp.json` using the Claude Code MCP server shape |
+For Claude Code and Claude Code CLI, `connect` writes a standard remote HTTP MCP entry with no static headers. Restart Claude Code, run `/mcp`, and choose **Authenticate**; Claude completes the OAuth flow and stores its own tokens. For Codex and Claude Cowork, `connect` uses the compatibility device-code flow: it opens your browser at the app, you click **Authorize** once, and the command writes a scoped bearer-token entry. If you choose a mix of clients, it does both.
 
-There is no token to copy and no local server to run. Restart the agent client after connecting so it picks up the new MCP server.
+If you previously connected Claude Code through the old bearer-token flow, just run the same `agent-native connect ... --client claude-code` command again. The CLI replaces the legacy `Authorization` headers with the URL-only OAuth entry and tells you to re-authenticate from `/mcp`.
+
+| Local client                  | Config written by `connect`                             | Auth flow                                       |
+| ----------------------------- | ------------------------------------------------------- | ----------------------------------------------- |
+| Claude Code / Claude Code CLI | `.mcp.json` or `~/.claude.json`, depending on `--scope` | Standard remote MCP OAuth in Claude's `/mcp` UI |
+| Codex                         | `~/.codex/config.toml` under `[mcp_servers.<app>]`      | Browser-authorized bearer fallback              |
+| Claude Cowork                 | `~/.cowork/mcp.json` using the Claude Code MCP shape    | Browser-authorized bearer fallback              |
+
+There is no token to copy and no local server to run. Restart the agent client after connecting so it picks up the new MCP server; OAuth-native clients may then prompt you to authenticate from their MCP UI.
 
 Use `--client codex` (or `--client claude-code`, `--client claude-code-cli`, `--client cowork`, `--client all`) to skip the picker for scripts or one-off installs.
 
@@ -46,7 +50,7 @@ npx @agent-native/core connect --all
 
 The client picker appears once and the same selection is used for every hosted app.
 
-The connection is **per-user, scoped, and revocable**. The browser session you authorized with is the identity the agent acts as; nothing exposes the deployment's shared secret.
+The connection is **per-user, scoped, and revocable**. In the OAuth path, the host stores the tokens after `/mcp` authentication; in the fallback path, the browser session you authorized with is the identity the agent acts as. Nothing exposes the deployment's shared secret.
 
 ### No-CLI alternative {#no-cli}
 
@@ -57,7 +61,7 @@ If you'd rather not run a command, open the app in your browser and use its **Co
 {
   "mcpServers": {
     "mail": {
-      "type": "url",
+      "type": "http",
       "url": "https://mail.agent-native.com/_agent-native/mcp",
       "headers": { "Authorization": "Bearer <minted-token>" },
     },
@@ -67,7 +71,34 @@ If you'd rather not run a command, open the app in your browser and use its **Co
 
 Restart the agent client after connecting so it picks up the new MCP server.
 
-Use this manual block for MCP clients that are not yet written by `agent-native connect`, including Cursor, Claude web/Desktop connector setup, ChatGPT developer-mode custom MCP apps, VS Code GitHub Copilot, Goose, Postman, MCPJam, and any other host that accepts a remote Streamable HTTP MCP endpoint.
+Use this manual bearer block for MCP clients that cannot complete the standard remote MCP OAuth flow, or for one-off debugging when you explicitly want to paste a token.
+
+### Standard remote MCP OAuth {#standard-oauth}
+
+Hosted agent-native apps also support the standard remote MCP OAuth flow. For clients that implement MCP OAuth, add the remote HTTP server URL with no static headers:
+
+```bash
+claude mcp add --transport http agent-native-mail \
+  https://mail.agent-native.com/_agent-native/mcp
+```
+
+This is the same URL-only entry that `agent-native connect https://mail.agent-native.com --client claude-code` writes for you. Then run `/mcp` in Claude Code and choose **Authenticate**. The client discovers auth from the MCP server's `401 WWW-Authenticate` challenge, fetches `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, dynamically registers a public OAuth client, opens the app's authorization page, and stores the resulting token securely. ChatGPT developer-mode connectors use the same server URL:
+
+```text
+https://mail.agent-native.com/_agent-native/mcp
+```
+
+The OAuth flow is authorization-code + PKCE with refresh-token rotation. Access tokens are audience-bound to the exact MCP resource URL and carry the signed user/org identity, so tool calls, `resources/read`, and MCP App iframe-initiated `tools/call` all run through the same `runWithRequestContext` tenant scoping as the existing connect-minted JWT path. The iframe never receives raw OAuth tokens; the host mediates calls through the authenticated MCP connection.
+
+Current scopes are:
+
+| Scope       | Allows                                                                    |
+| ----------- | ------------------------------------------------------------------------- |
+| `mcp:read`  | read-only MCP actions and ordinary tool/resource discovery                |
+| `mcp:write` | mutating actions and the `ask-agent` meta-tool                            |
+| `mcp:apps`  | MCP Apps resource listing/reading and inline UI rendering where supported |
+
+When the client requests no explicit scope, the app grants all three so the connector behaves like the browser-authorized Connect flow. Keep the bearer-token Connect page and `agent-native connect --token <token>` fallback around for local dev, fallback hosts, and clients where you need a ready-to-paste config block.
 
 ## What you can do once connected {#what-you-can-do}
 
@@ -109,7 +140,7 @@ On top of the per-action tools the MCP server exposes a stable verb set, so an e
 Every allow-listed template that produces or lists a navigable resource ships a `link` builder, and the ingest-heavy ones ship a GET + `publicAgent` action so a connected agent can pull live state:
 
 - **Mail** — `manage-draft` returns a `compose`-encoded deep link; clicking it opens the inbox with the draft restored into a `compose-<id>`. `list-emails` / `search-emails` point at a filtered inbox view.
-- **Calendar** — `manage-event-draft` returns a `calendarDraft` + `eventDraftId` deep link; clicking it opens the New Event form prefilled for review/send. `create-event` still returns `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })`; the click lands on the calendar with that event focused on its date.
+- **Calendar** — `manage-event-draft` returns a `calendarDraft` + `eventDraftId` deep link; clicking it opens a visible draft placeholder on the calendar with the native event editor for review/send. `create-event` still returns `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })`; the click lands on the calendar with that event focused on its date.
 - **Analytics** — `update-dashboard` / `save-analysis` return `buildDeepLink({ app: "analytics", view: "adhoc", params: { dashboardId } })`; the agent builds a dashboard over MCP and hands back "Open dashboard in Analytics".
 - **Design** — `get-design-snapshot` is the GET + `publicAgent` ingest action: it returns the **live** Yjs file contents plus the resolved tweak values so the agent continues from the tuned design, not the original tokens. `apply-tweaks` round-trips back with an "Open design" editor link.
 - **Content** — `pull-document` is the GET + `publicAgent` ingest action: it flushes any open live collaborative session to SQL first so the external agent ingests exactly what the user sees, then surfaces a deep link to the document.
@@ -260,7 +291,7 @@ You can also write the MCP client config by hand against any deployed endpoint w
 {
   "mcpServers": {
     "analytics": {
-      "type": "url",
+      "type": "http",
       "url": "https://analytics.agent-native.com/_agent-native/mcp",
       "headers": { "Authorization": "Bearer <ACCESS_TOKEN-or-JWT>" },
     },
@@ -296,7 +327,9 @@ If `connect dev` cannot infer your local owner identity from an existing connect
 
 ## How it works & security {#how-it-works}
 
-The hosted `connect` flow never copies the deployment's shared secret. Instead:
+The standard OAuth path never exposes tokens to MCP Apps: the host stores OAuth access/refresh tokens and mediates tool calls and `resources/read` over the authenticated MCP connection. Embedded iframes receive app data and tool results, not bearer secrets.
+
+The fallback hosted `connect` flow never copies the deployment's shared secret. Instead:
 
 - A logged-in browser session mints a **per-user, scoped, revocable** token — an `A2A_SECRET`-signed JWT carrying the caller's `sub` + `org_domain` and a unique `jti`, so every tool run stays tenant-scoped via `runWithRequestContext`.
 - The existing `/_agent-native/mcp` endpoint accepts that token like any other bearer (see [MCP Protocol](/docs/mcp-protocol)) — no new endpoint, no new transport.

package/docs/content/faq.md

@@ -121,9 +121,9 @@ Anywhere. The server runs on Nitro, which compiles to any deployment target: Nod
 
 ## Architecture {#architecture}
 
-### Why polling instead of WebSockets? {#why-polling-not-websockets}
+### Why SSE plus polling instead of WebSockets? {#why-polling-not-websockets}
 
-Polling works in every deployment environment — including serverless, edge, and container platforms where persistent connections aren't available. The framework polls every 2 seconds using a lightweight version counter. When changes are detected, React Query caches are invalidated and components re-render. It's simple, reliable, and universal.
+SSE gives same-process writes an immediate path to the browser without requiring a bidirectional socket server. Polling remains the fallback because it works in every deployment environment — including serverless, edge, and container platforms where persistent connections may not be available. The fallback uses a lightweight version counter; when changes are detected, React Query caches are invalidated and components re-render.
 
 ### Why can't the UI call an LLM directly? {#why-no-inline-llm-calls}
 

package/docs/content/key-concepts.md

@@ -1,6 +1,6 @@
 ---
 title: "Key Concepts"
-description: "How agent-native apps work: the four-area checklist, SQL database, agent chat bridge, polling sync, actions, context awareness, and portability."
+description: "How agent-native apps work: the four-area checklist, SQL database, agent chat bridge, polling sync, actions, external-agent entry points, context awareness, and portability."
 ---
 
 # Key Concepts
@@ -37,7 +37,7 @@ Six rules govern the architecture:
 1. **Data lives in SQL** — all app state lives in the database via Drizzle ORM
 2. **All AI goes through the agent** — no inline LLM calls
 3. **Actions for agent operations** — complex work runs as actions
-4. **Polling keeps the UI in sync** — database changes sync via lightweight polling
+4. **Live sync keeps the UI in sync** — database changes stream over SSE with polling as the universal fallback
 5. **The agent can modify code** — the app evolves as you use it
 6. **Application state in SQL** — ephemeral UI state lives in the database, readable by both agent and UI
 
@@ -45,10 +45,10 @@ Six rules govern the architecture:
 
 Adopting the framework is valuable mostly because of what you stop having to build. The moment your app follows the six rules, you inherit:
 
-- **One action = four surfaces.** Every action defined with `defineAction()` is simultaneously an agent tool, a typesafe frontend mutation (`useActionMutation("name")`), an HTTP endpoint at `/_agent-native/actions/:name`, and an MCP tool (when MCP is enabled). External agents can call it over [A2A](/docs/a2a-protocol) too. One implementation, four consumers.
+- **One action = every surface.** Every action defined with `defineAction()` is simultaneously an agent tool, a typesafe frontend mutation (`useActionMutation("name")`), an HTTP endpoint at `/_agent-native/actions/:name`, a CLI command, an MCP tool for external clients, and an A2A tool for other agent-native apps. Optional `link` and `mcpApp` metadata add deep links and MCP Apps UI without a second implementation.
 - **A full workspace per user.** Skills, shared `LEARNINGS.md`, personal `memory/MEMORY.md`, `AGENTS.md`, custom sub-agents, scheduled jobs, connected MCP servers — all SQL-backed, no dev-box required. See [Workspace](/docs/workspace).
 - **Drop-in React components.** `<AgentPanel />` and `<AgentSidebar />` render chat + workspace anywhere in your app. See [Drop-in Agent](/docs/drop-in-agent).
-- **Live sync between agent and UI.** A 2-second poll invalidates React Query caches whenever the agent writes to the DB. No WebSockets, no serverless-unfriendly long-lived connections. See [Polling Sync](#polling-sync) below.
+- **Live sync between agent and UI.** Same-process writes stream immediately over `/_agent-native/events`; a lightweight poll keeps serverless, cron, and cross-process writes convergent. Mutating actions invalidate action-backed queries automatically, so agent-created records appear without a manual refresh. See [Live Sync](#polling-sync) below.
 - **Auth, orgs, RBAC.** Better Auth with orgs/members/roles is wired in for every template. See [Authentication](/docs/authentication).
 - **Context awareness.** The agent always knows what the user is looking at through the `navigation` app-state key. See [Context Awareness](/docs/context-awareness).
 - **MCP client + server, both directions.** The app ingests MCP servers (local, remote, hub-shared) _and_ exposes its own actions as an MCP server. See [MCP Clients](/docs/mcp-clients) and [MCP Protocol](/docs/mcp-protocol).
@@ -158,27 +158,24 @@ One `defineAction()` call gives you:
 
 Same logic, one definition, wired to every consumer automatically. See [Actions](/docs/actions) for the full reference.
 
-## Polling sync {#polling-sync}
+## Live sync {#polling-sync}
 
-Database changes are synced to the UI via lightweight polling. When the agent writes to the database (application state, settings, or domain data), a version counter increments. The client `useDbSync()` hook (formerly `useFileWatcher`) polls `/_agent-native/poll` every 2 seconds and invalidates React Query caches when changes are detected.
+Database changes are synced to the UI through `useDbSync()`. Same-process writes stream over `/_agent-native/events`; `/_agent-native/poll` remains the cross-process and serverless fallback. When the agent writes to the database (application state, settings, or domain data), a version counter increments and the client invalidates the relevant React Query caches.
 
 ```ts
-// Client: invalidate caches on database changes
+// Client: subscribe to agent/UI data changes once near the app shell
 import { useDbSync } from "@agent-native/core";
 
-useDbSync({
-  queryClient,
-  queryKeys: ["app-state", "settings", "forms"],
-});
+useDbSync({ queryClient });
 ```
 
 The flow is:
 
 1. Agent runs an action that writes to the database
-2. Version counter increments
-3. `useDbSync` detects the new version on next poll
-4. React Query caches are invalidated
-5. Components re-fetch and render the new data
+2. The server emits a change event with a source such as `"action"` or `"settings"`
+3. `useDbSync` receives it over SSE or the polling fallback
+4. `useActionQuery` hooks and source-versioned `useQuery` hooks refetch
+5. Components render the new data without a page reload
 
 This works in all deployment environments — including serverless and edge — because it uses the database, not in-memory state or file system watchers.
 
@@ -196,14 +193,25 @@ The agent always knows what the user is looking at. The UI writes a `navigation`
 
 See [Context Awareness](/docs/context-awareness) for the full pattern: navigation state, view-screen, navigate commands, and jitter prevention.
 
-## Actions, MCP, and A2A — one surface, many protocols {#protocols}
-
-Every action you define automatically becomes available over multiple protocols — you don't pick one. The framework runs both an MCP server and an A2A peer for your app, with actions feeding both.
-
-- **Actions first.** Write the logic once as an action. Use `fetch()` and any SDK you want inside — no wrapper layer.
-- **MCP for the outside world.** Your actions show up as MCP tools to Claude, ChatGPT custom MCP apps, Claude Desktop/Code, Cursor, Codex, and any other MCP client. Actions can also expose MCP Apps UI resources so compatible hosts render inline review/edit surfaces, with deep links back to the full app as the universal fallback. Your app also _consumes_ MCP servers — local, remote, or from a workspace hub. See [External Agents](/docs/external-agents), [MCP Clients](/docs/mcp-clients), and [MCP Protocol](/docs/mcp-protocol).
-- **A2A for other agents.** Other agent-native apps discover and call your actions over [A2A](/docs/a2a-protocol) — same-origin deploys skip JWT entirely.
-- **CLIs still work.** `pnpm action <name>` and direct shell tools (`ffmpeg`, `gh`, `aws`) remain available whenever they're the simplest path.
+## One action, many protocols {#protocols}
+
+Agent-native supports a lot of agent-facing protocols because different hosts standardize different pieces of the same workflow. App authors should not have to choose among them or rebuild the same operation for each client. The center of gravity stays the action system.
+
+| Surface                 | What agent-native provides                                                                                             | What you write                          |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| Agent tool calling      | The in-app agent sees actions as function tools with zod-derived JSON Schema.                                          | `defineAction()`                        |
+| UI actions              | React calls the same action through `useActionMutation()` / `useActionQuery()`.                                        | The same action                         |
+| HTTP and CLI            | Actions auto-mount at `/_agent-native/actions/:name` and run via `pnpm action <name>`.                                 | The same action                         |
+| MCP server              | External MCP hosts get Streamable HTTP tools, the `ask-agent` meta-tool, and optional MCP Apps resources.              | The same action, plus optional `mcpApp` |
+| MCP Auth                | Remote MCP OAuth, PKCE, dynamic client registration, refresh tokens, and `mcp:read` / `mcp:write` / `mcp:apps` scopes. | Nothing per action                      |
+| A2A                     | Other agents discover the agent card and call the app over JSON-RPC tasks.                                             | The same actions and agent config       |
+| Deep links              | Action results can round-trip users into the running UI through `/_agent-native/open` and `agentnative://open`.        | Optional `link` metadata                |
+| MCP clients             | The app can also consume local, remote, or hub-shared MCP servers as `mcp__...` tools.                                 | `mcp.config.json` or settings           |
+| Instructions and skills | `AGENTS.md`, skills, memory, slash commands, sub-agents, jobs, and automations live in the SQL-backed workspace.       | Workspace resources, not protocol glue  |
+| Agent Web               | Public pages can publish `robots.txt`, `sitemap.xml`, `llms.txt`, markdown mirrors, and structured metadata.           | Route access plus `agentWeb` config     |
+| Extensions              | Sandboxed mini-apps call app actions, persist extension data, and use proxied fetch helpers.                           | Extension HTML using `appAction()`      |
+
+The practical rule is simple: implement domain operations as actions, add `readOnly`, `publicAgent`, `link`, or `mcpApp` metadata only when the surface needs it, and use skills/instructions for behavior. MCP, A2A, MCP Apps, MCP Auth, UI mutations, CLI commands, and deep-link handoffs are adapters around that same core.
 
 ## Agent modifies code {#agent-modifies-code}
 

package/docs/content/mcp-protocol.md

@@ -7,7 +7,7 @@ description: "Expose your agent-native app as a remote MCP server so Claude, Cha
 
 Every agent-native app automatically exposes a remote MCP (Model Context Protocol) server. This lets external AI tools like Claude, ChatGPT custom MCP apps, Claude Code, Cursor, Codex, VS Code GitHub Copilot, and Windsurf discover and call your app's actions directly — no extra code needed.
 
-If your goal is to connect Claude, ChatGPT, Claude Code, Codex, Cursor, or Claude Cowork to a hosted agent-native app, start with [External Agents](/docs/external-agents). It documents the one-command `agent-native connect https://mail.agent-native.com` flow, token minting, local client config writes, manual remote MCP setup for hosts we do not write directly, MCP Apps inline UIs, and deep links back into the UI. This page is the lower-level MCP server reference.
+If your goal is to connect Claude, ChatGPT, Claude Code, Codex, Cursor, or Claude Cowork to a hosted agent-native app, start with [External Agents](/docs/external-agents). It documents the one-command `agent-native connect https://mail.agent-native.com` flow, standard remote MCP OAuth for Claude Code, bearer fallback config for older clients, manual remote MCP setup for hosts we do not write directly, MCP Apps inline UIs, and deep links back into the UI. This page is the lower-level MCP server reference.
 
 ## Overview {#overview}
 
@@ -20,7 +20,8 @@ Key concepts:
 - **Same actions** — the exact same action registry that powers agent chat and A2A
 - **`ask-agent` tool** — a meta-tool that delegates to the full agent loop for complex tasks
 - **MCP Apps** — actions can advertise inline HTML UIs through the official `io.modelcontextprotocol/ui` extension
-- **Bearer auth** — uses `ACCESS_TOKEN` or `A2A_SECRET` for authentication
+- **Standard remote MCP OAuth** — OAuth 2.1 discovery, dynamic client registration, authorization-code + PKCE, refresh-token rotation
+- **Bearer auth fallback** — uses `ACCESS_TOKEN`, `ACCESS_TOKENS`, or connect-minted JWTs for clients that cannot run OAuth
 
 ## MCP vs A2A {#mcp-vs-a2a}
 
@@ -39,21 +40,20 @@ You can also use the `ask-agent` MCP tool to get the best of both worlds — cal
 
 ## Manual MCP client config {#claude-code}
 
-For the recommended one-command setup, use [External Agents](/docs/external-agents). If you are hand-writing MCP config, add your app as a remote MCP server in Claude Code's config:
+For the recommended one-command setup, use [External Agents](/docs/external-agents). If you are hand-writing MCP config for an OAuth-capable client, add your app as a remote MCP server with no static headers:
 
 ```jsonc
 // ~/.claude/mcp_servers.json
 {
   "mail": {
-    "type": "url",
+    "type": "http",
     "url": "https://mail.example.com/_agent-native/mcp",
-    "headers": {
-      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
-    },
   },
 }
 ```
 
+Then run `/mcp` in Claude Code and choose **Authenticate**. For clients that cannot perform remote MCP OAuth, use the Connect page or a static bearer-token entry with `headers.Authorization`.
+
 Then in Claude Code, you can use your app's tools naturally:
 
 ```
@@ -105,16 +105,50 @@ The agent runs the same loop as the interactive chat — it can call multiple to
 
 ## Authentication {#authentication}
 
-The MCP endpoint uses the same auth as the rest of the app:
+The MCP endpoint supports standard remote MCP OAuth plus the existing bearer-token fallback:
+
+| Mode                        | How it works                                                                                                          |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Standard MCP OAuth          | Client discovers auth from `WWW-Authenticate`, registers, runs PKCE, and sends `Authorization: Bearer <access-token>` |
+| Connect-minted JWT          | `agent-native connect` / the Connect page mints a per-user, revocable JWT                                             |
+| `ACCESS_TOKEN`              | Static bearer token — client sends `Authorization: Bearer <token>`                                                    |
+| `ACCESS_TOKENS`             | Comma-separated list of valid static bearer tokens                                                                    |
+| `A2A_SECRET`                | JWT-based auth — tokens are verified cryptographically                                                                |
+| _(none set, loopback only)_ | No auth required for local dev probes                                                                                 |
+
+For OAuth-capable MCP hosts, configure the remote server URL with no static headers:
+
+```bash
+claude mcp add --transport http agent-native-mail https://mail.agent-native.com/_agent-native/mcp
+```
+
+The first unauthenticated MCP request receives:
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://mail.agent-native.com/.well-known/oauth-protected-resource", scope="mcp:read mcp:write mcp:apps"
+```
+
+Discovery endpoints:
+
+| Endpoint                                  | Purpose                                     |
+| ----------------------------------------- | ------------------------------------------- |
+| `/.well-known/oauth-protected-resource`   | RFC 9728 protected-resource metadata        |
+| `/.well-known/oauth-authorization-server` | OAuth authorization server metadata         |
+| `/.well-known/openid-configuration`       | OIDC-compatible metadata alias              |
+| `/_agent-native/mcp/oauth/register`       | Dynamic public-client registration          |
+| `/_agent-native/mcp/oauth/authorize`      | Browser authorization + consent             |
+| `/_agent-native/mcp/oauth/token`          | Authorization-code and refresh-token grants |
+
+Access tokens are signed JWTs whose audience is the exact MCP resource URL. The server accepts only tokens issued for itself and applies scopes before listing/calling tools:
 
-| Env var         | How it works                                                |
-| --------------- | ----------------------------------------------------------- |
-| `ACCESS_TOKEN`  | Bearer token — client sends `Authorization: Bearer <token>` |
-| `ACCESS_TOKENS` | Comma-separated list of valid tokens                        |
-| `A2A_SECRET`    | JWT-based auth — tokens are verified cryptographically      |
-| _(none set)_    | No auth required (dev mode)                                 |
+| Scope       | Allows                                      |
+| ----------- | ------------------------------------------- |
+| `mcp:read`  | read-only actions                           |
+| `mcp:write` | mutating actions and `ask-agent`            |
+| `mcp:apps`  | MCP Apps resources (`ui://` HTML resources) |
 
-In production, set `ACCESS_TOKEN` or `A2A_SECRET` to secure the endpoint. In development (no auth env vars configured), all requests are allowed.
+Refresh tokens are stored only as hashes and are rotated on every refresh. `agent-native connect` writes this URL-only OAuth entry for Claude Code clients by default; keep the Connect page, `agent-native connect --token <token>`, and static bearer config for local stdio proxying, older clients, and emergency/debug flows.
 
 ## Custom MCP setup {#custom-setup}
 
@@ -149,9 +183,8 @@ You have a deployed analytics app at `analytics.example.com`. From Claude Code:
 // ~/.claude/mcp_servers.json
 {
   "analytics": {
-    "type": "url",
+    "type": "http",
     "url": "https://analytics.example.com/_agent-native/mcp",
-    "headers": { "Authorization": "Bearer sk-analytics-token" },
   },
 }
 ```

package/docs/content/template-starter.md

@@ -1,11 +1,11 @@
 ---
 title: "Starter Template"
-description: "The minimal agent-native scaffold — agent chat, actions, application state, polling, auth — wired up, with no domain code. Build from scratch."
+description: "The minimal agent-native scaffold — agent chat, actions, application state, live sync, auth — wired up, with no domain code. Build from scratch."
 ---
 
 # Starter
 
-Starter is the minimum viable agent-native app. You get the six-rules architecture, the agent sidebar, the workspace tab, polling sync, auth, and exactly one example action. Nothing else. Build from there.
+Starter is the minimum viable agent-native app. You get the six-rules architecture, the agent sidebar, the workspace tab, live sync, auth, and exactly one example action. Nothing else. Build from there.
 
 <!-- screenshot:
   app: starter
@@ -26,7 +26,7 @@ Pick Starter when you're not sure which domain template fits, or when you want t
 - **Auth** via Better Auth — login, signup, sessions, organizations. The same flow runs locally and in production; in development email verification is skipped so signup is just an email + password.
 - **Actions directory** with one example (`actions/hello-world.ts`) and the `view-screen` / `navigate` standard actions wired up.
 - **Drizzle schema** with the framework's core tables (application_state, settings, oauth_tokens, sessions, resources).
-- **Polling sync** (`useDbSync`) already wired so UI auto-refreshes when the agent writes to the database.
+- **Live sync** (`useDbSync`) already wired so UI auto-refreshes when the agent writes to the database.
 - **AGENTS.md** with the framework-wide rules the agent reads on every turn.
 - **One route** at `/` that says hi and renders the sidebar toggle. That's it.
 

package/docs/content/what-is-agent-native.md

@@ -45,10 +45,12 @@ Three things change when you reach rung 3:
 
 - **You stopped adding buttons to a chatbot. You added an agent to an app.** That's a much higher-quality product on both sides.
 - **The agent has real context.** It sees what you're looking at, what you've selected, what you just did. It writes to the same database the UI reads from, so its work shows up immediately.
-- **External agents can use it too.** Other agent-native apps can call this one's actions over the [A2A protocol](/docs/a2a-protocol). Tools like Claude Desktop can drive it as an [MCP server](/docs/mcp-protocol). One app, many entry points.
+- **External agents can use it too.** Other agent-native apps can call this one's actions over the [A2A protocol](/docs/a2a-protocol). Claude Code, Codex, ChatGPT custom MCP apps, Cursor, and other MCP hosts can drive it as an [MCP server](/docs/mcp-protocol). One app, many entry points.
 
 That's rung 3. That's agent-native.
 
+It also explains why agent-native can support so many protocols without making every app author become a protocol expert. MCP tools, MCP Apps, remote MCP OAuth, A2A, typed React mutations, HTTP action endpoints, CLI actions, deep links, instructions, skills, memory, jobs, and connected MCP servers all hang off the same action and workspace model. Build the domain operation once as an action; the framework projects it into the surfaces each host understands.
+
 ## Why every agent needs a UI {#why-every-agent-needs-a-ui}
 
 The hot take in 2026 is "apps are dead, agents will replace UIs, everyone will just text an agent in Telegram." That's wrong.
@@ -170,7 +172,7 @@ import { AgentSidebar } from "@agent-native/core/client";
 <AgentSidebar />;
 ```
 
-One action, four surfaces: the agent calls it as a tool, the UI calls it as a typesafe mutation, external agents reach it over [A2A](/docs/a2a-protocol), and tools like Claude Desktop talk to it as an [MCP server](/docs/mcp-protocol). See [Actions](/docs/actions) for the full reference.
+One action, many surfaces: the agent calls it as a tool, the UI calls it as a typesafe mutation, external agents reach it over [A2A](/docs/a2a-protocol), and MCP hosts call it through the app's [MCP server](/docs/mcp-protocol), optionally with MCP Apps UI resources and standard remote MCP OAuth handled by the framework. See [Actions](/docs/actions) for the full reference.
 
 ## What's next {#whats-next}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",
@@ -150,6 +150,7 @@
     "nanoid": "^5.1.9",
     "nitro": "3.0.260415-beta",
     "p-limit": "^7.3.0",
+    "prettier": "^3.8.3",
     "react-markdown": "^10.1.0",
     "react-router": "^7.13.1",
     "remark-gfm": "^4.0.1",