# External Agents

> Connect external agents and MCP hosts (Claude, Claude Desktop, Claude Code, ChatGPT custom MCP apps, Codex, Cursor, Claude Cowork, VS Code GitHub Copilot, Goose, Postman, MCPJam) to an agent-native app over MCP, and round-trip artifacts back into the UI with MCP Apps and deep links. Use when adding an action's `link` builder or `mcpApp`, wiring the `/_agent-native/open` route, exposing an "ingest" action to MCP/A2A, or scaffolding apps from an external agent.

- Skill: `builderio/external-agents` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add builderio/external-agents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/builderio/external-agents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Builder.io (https://skillmd.com/u/builderio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/builderio/external-agents

---


# External Agents (MCP bridge + deep links)

## Rule

- **The connected model is the author.** Write content yourself with create/update tools; never delegate via `ask_app` or wait on an unreachable in-app form — see `DEFAULT_AGENT_NATIVE_MCP_INSTRUCTIONS`.
- **Result shape and key tools are in `actions`** (Return Values, Key Actions).
- **Artifacts fit in one call.** Up to 500,000 characters; return a `storing-data` handle.
- **One tab, one id.** WebMCP sends `X-Agent-Native-Browser-Tab`; state resolves to the driving tab (`context-awareness`).

An agent-native app is reachable by any MCP-compatible host. Keep
setup simple: for workspace or cross-app access, add one remote MCP connector:
`https://dispatch.agent-native.com/mcp`. Dispatch's Agents page
controls whether that single connector reaches all apps or only selected apps,
and Dispatch filters `list_apps`, `ask_app`, and `open_app` to the granted set.
For a deliberately isolated app, add that app directly at
`https://<app>.agent-native.com/mcp` or
`https://<your-host>/mcp`.

In-app, the Agent page's **Access** tab (`/agent#access`) is the home for this:
it shows MCP/A2A URLs, client setup steps, and the full `/mcp/connect` page.
Point users there instead of dictating URLs in chat.

OAuth-capable hosts use the standard remote MCP OAuth flow — Claude, Claude
Code, and ChatGPT discover the protected resource and store their own tokens;
per-host steps are below. Local stdio proxying and older clients can still use
`npx @agent-native/core connect <url>`, which mints a per-user, scoped,
revocable token from a logged-in browser session; no shared secret is copied.

The framework serves MCP `2026-07-28` natively over stateless, per-request HTTP
and keeps the established stateless path for 2025-era clients. New MCP client
code uses the split `@modelcontextprotocol/client` package with
`versionNegotiation: { mode: "auto" }`; do not pin a protocol header or
hand-send `initialize`. OAuth callback handlers preserve `state` and pass the
RFC 9207 `iss` parameter to the v2 SDK for validation before exchanging a
code. The authorization server accepts HTTPS Client ID Metadata Documents after
strict URL, SSRF, size, redirect, schema, and exact callback validation; URL-like
client ids never fall back to dynamic registration. Traditional non-URL clients
continue to use public-client dynamic registration.

Actions marked `needsApproval` use MCP 2026 `input_required` elicitation. The
approval is bound to the authenticated caller, exact action, exact arguments,
and expiry, and its durable grant is consumed atomically before the action runs.
If the host cannot complete the approval exchange, the predicate throws, the
state is invalid or replayed, or durable storage is unavailable, the action
fails closed.

Claude and ChatGPT can cache custom connector tool/resource metadata. After
changing MCP App metadata or the shared `embedApp()` shell, validate with a
fresh tool call; if the host still behaves like the old descriptor, reconnect
the Claude connector or rescan/review the ChatGPT connector.

Once connected, every action that produces or lists a navigable resource SHOULD
return a deep link from a `link` builder, so the external agent can surface an
**"Open in <app> →"** link that drops the user back into the running UI at the
right view and record. Actions can also declare `mcpApp` so hosts that support
MCP Apps render an inline interactive preview. The link is a pure pointer —
the record-focusing write is always scoped to the **browser session**, never
the agent's token.

## Why

External agents are great at producing artifacts (a draft, an event, a
dashboard) but they live in a terminal, chat host, or another app. Without a
bridge, the user gets a wall of JSON and has to go find the thing. MCP Apps
give compatible hosts an inline review/edit surface; the deep-link bridge
closes the loop everywhere else by handing the user a single 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**) — we never invent a second navigation mechanism.

## App-facing MCP connectors

Apps can also consume connected remote MCP servers as a server-side API. The
framework stores each connector's OAuth client registration, discovery metadata,
access token, and refresh token in the encrypted `oauth_tokens` store, scoped to
the user or organization. The browser and sandboxed MCP App iframes never
receive those credentials.

Use the hidden core actions `list-mcp-tools` and `call-mcp-tool` when an app UI
needs a request-scoped API surface. Server-side app actions can import
`listVisibleMcpTools` and `callMcpTool` from `@agent-native/core/mcp-client`.
Both paths require an authenticated request context and enforce user/org server
visibility plus MCP App visibility metadata. Pass the configured server id and
the server's original tool name; the framework resolves the internal prefixed
tool name and injects the connector's bearer token.

```ts
import { callMcpTool } from "@agent-native/core/mcp-client";

const result = await callMcpTool("org_acme_linear", "list_issues", {
  project: "<PROJECT_ID>",
});
```

Use this for bounded product workflows (for example, syncing issues or
refreshing analytics). Do not expose a raw token, arbitrary server URL, or
unbounded proxy from an app action. Keep provider-specific schemas and access
checks in the app action, and use the connector catalog/OAuth button for setup.

## Provider API connectors

The shared workspace connection catalog is also the setup surface for provider
APIs. When a provider advertises OAuth, show that connection as the primary
setup action and retain its API key or token as an explicit fallback. Current
shared OAuth providers include Figma, GitHub, Google Drive, HubSpot, Jira Cloud, Notion, and Sentry. Slack
uses its managed messaging-install OAuth flow. Gmail,
Calendar, and Slides may use template-owned Google OAuth flows with broader
scopes; do not replace those flows with the narrower Drive connection.

Provider API actions resolve credentials server-side. Pass a granted
`connectionId` when a request must use a particular OAuth account; never copy
the access token into a browser, extension, MCP App, prompt, or stored action
payload. Key-only providers should remain in the normal scoped secrets flow
until their upstream OAuth app, scopes, refresh behavior, and identity mapping
have been implemented and configured.

Extensions can consume both classes of connection through the same host-side
action bridge. Use `agentNative.mcp.listTools()` / `callTool()` for connected
remote MCP servers, and `agentNative.providerApi.catalog()` / `docs()` to
discover template-owned provider API actions. The bridge
preserves the current user's or organization's access scope and never exposes
MCP URLs, OAuth tokens, refresh tokens, or client secrets to the iframe. Local
file extensions must declare the corresponding action names in
`permissions.appActions`.

## How

### 1. Connect to hosted apps

Use one connector for normal workspace access:

```text
https://dispatch.agent-native.com/mcp
```

Then open Dispatch → Agents to choose whether the gateway exposes every app or
only selected IDs. Use `list_apps` for grants, `open_app` for links/embeds, and
named actions when cataloged. Use `ask_app` only when direct action is
unavailable or app-agent reasoning helps.

Use a direct app URL only when you intentionally want one isolated app:

```text
https://mail.agent-native.com/mcp
https://<your-app>.agent-native.com/mcp
```

Claude / Claude Desktop: add a custom connector with the URL, click Connect,
then sign in and approve `mcp:read`, `mcp:write`, `mcp:apps`, and
`offline_access`. Claude Code:
add the same remote HTTP URL, restart if needed, run `/mcp`, and choose
Authenticate. ChatGPT: create a custom MCP connector/app, paste the same URL,
choose OAuth, scan/discover tools, then sign in and approve scopes. Each host
stores its own OAuth tokens; MCP App iframes never receive raw tokens because
the host mediates tool and resource calls over the authenticated MCP
connection.

For local stdio proxying, Codex/Cowork compatibility, or clients without
remote MCP OAuth, use the hosted connect fallback:

```bash
npx @agent-native/core@latest connect https://dispatch.agent-native.com
# or, for an isolated app:
npx @agent-native/core@latest connect https://mail.agent-native.com
```

The command opens the app in the browser, the user clicks **Authorize**, and a
per-user, scoped, revocable token is written to the selected client config. The
no-CLI equivalent is `https://<app>/mcp/connect`, which shows
the copyable MCP URL, Claude / ChatGPT / Cursor / Claude Code / Codex / Other
steps, and static-token fallback for clients that need it.

Re-running `npx @agent-native/core@latest connect <url> --client claude-code` over an older
Claude bearer-token entry is the migration path: the CLI replaces
`Authorization` headers with URL-only OAuth config and tells the user to
authenticate from `/mcp`.

To re-authenticate an already-installed local/fallback client without
reinstalling skills or connectors, use:

```bash
npx -y @agent-native/core@latest reconnect https://dispatch.agent-native.com --client codex
# or:
npx -y @agent-native/core@latest connect reconnect https://dispatch.agent-native.com --client codex
```

With no URL, `reconnect` searches local client configs for the existing Agent
Native MCP entry. With a URL, it reconnects only the clients that already have
that MCP URL; pass `--client` to limit which configs it searches. Pass
`--name <serverName>` only when you need to force a custom server name.

Under the hood: a logged-in browser session mints an `A2A_SECRET`-signed JWT
carrying the caller's `sub` + `org_domain` and a unique `jti`, so tool runs
stay tenant-scoped via `runWithRequestContext`. The existing
`/mcp` endpoint accepts it like any bearer — no new endpoint.
The same Connect page lists and revokes minted tokens by `jti`; treat them
like personal access tokens. Nothing exposes the deployment's shared secret.

### 1a. Generic cross-app verbs + scaffolding

Once connected, on top of the per-action tools the MCP server also exposes a
stable verb set (see `packages/core/src/mcp/builtin-tools.ts`) so an external
agent has a predictable surface without guessing per-app action names:

- `list_apps` — workspace apps + their URLs / running state.
- `open_app({ app, view?, path?, params?, embed? })` — returns a deep link or
  direct same-origin app route (no user-data side effects); surfaces as an
  "Open …" link and, with `embed: true`, an inline full-app MCP App in capable
  hosts.
- `ask_app({ app, message })` — routes a natural-language task to that app's
  in-app agent (delegates to the existing `ask-agent` meta-tool). It also
  accepts `async` and `maxWaitMs`; hosted calls wait at most 25 seconds inline
  and return a durable `taskId` plus an `ask_app_status` poll instruction when
  the task is still running.
- `ask_app_status({ app, taskId })` — retrieves the current or terminal result
  for a durable `ask_app` task. Dispatch checks the selected-app grant again
  before polling.
- `create_workspace_app({ name, template })` — scaffolds + boots a new app via
  the workspace path (rejects non-allow-listed templates), returns its running
  URL + deep link.
- `list_templates` — the allow-listed templates only.

A same-named template action overrides a builtin (template-over-core
precedence). Disable the set with `MCPConfig.builtinCrossAppTools: false`.

The advertised `tools/list` and `resources/list` catalogs are intentionally
tiny by default for ChatGPT/Claude-style app hosts, including OAuth MCP Apps
callers. The unified gateway exposes only generic verbs (`list_apps`, `open_app`,
`ask_app`, `create_embed_session`); named actions come from a direct app MCP
connection or page WebMCP. Route UI through
`open_app({ embed: true })`. Stdio/code clients use the same compact surface
unless they explicitly opt into the full catalog, and
`publicAgent.expose` remains the action-level opt-in for safe read/ingest tools
outside the compact MCP Apps catalog. Apps can set
`externalAgents.authenticatedReads: "auto"` to automatically advertise every
action that is GET + `readOnly` + `publicAgent.requiresAuth`, instead of
maintaining a long connector allow-list. This policy never includes writes by
default; use `writes: "ask_app_only"` to keep mutations behind `ask_app`, and
use `denyActions` for defense-in-depth vetoes. `tool-search` remains available
for discovery, but a searched action still needs to be in the connector
catalog, included by the authenticated-read policy, or enabled by the explicit
full-catalog opt-in before `tools/call` can execute it. Do not rely on
action-specific `mcpApp` resources appearing in ChatGPT/Claude discovery by
default; use `open_app` for the
first-class app embed path. If a specific
action truly must remain visible in that compact app-host catalog, set
`mcpApp.compactCatalog: true` as a rare escape hatch.

Generic core `db-schema` and `db-query` are intentionally not automatic
external reads. They remain available to the in-app agent through the normal
scoped SQL path, but broad schema/SQL access is too powerful to infer from
read-only metadata alone. If an app needs direct external querying, expose an
app-owned bounded GET action or add an explicit table/column allow-list with
row, byte, timeout, and audit limits. Keep `db-exec` and `db-patch` outside
automatic external-agent exposure.

Authentication and authorization are separate gates. A verified MCP OAuth or
connect token identifies the caller and organization; `publicAgent` only opts
an action into the external protocol surface and does not grant record access.
Actions still need `accessFilter`, `resolveAccess`, or `assertAccess` so private
documents/dashboards, shares, organization boundaries, and roles are enforced.
For Slack, verified DMs are linked to an existing Agent-Native org member
before execution and run with that user's context; shared channels use a
service principal, and guests/external members cannot borrow personal access.
Managed Slack OAuth and the generated app manifest both request
`users:read.email`; existing installs must reconnect/reinstall after a scope
change, while legacy bot-token installs must add the scope in Slack manually.

### 1b. Fast-path expectations for MCP Apps hosts

Keep ChatGPT/Claude paths short. For a known app-facing intent, the external
agent should call the specific action that creates or opens the thing, then let
the MCP App launch the route. Do **not** route simple UI handoffs
through `ask_app`, broad `list_resources`, or generic app-agent delegation just
to find a screen.

Expected shape:

- Email draft: `manage_draft` → inline Mail compose route. The widget calls
  `create_embed_session` itself.
- Dashboard/filter/search: `open_app({ path, embed: true })` or the dashboard
  action with `mcpApp` → inline full app/dashboard route.
- Calendar invite: `manage-event-draft` → inline Calendar event draft route.
- Forms/content/slides/design/clips: create/search action with `mcpApp` →
  inline editor/player route.

`list_apps` is fine when the model genuinely needs to choose among granted
apps. `resources/list`/`resources/read` are host plumbing for MCP Apps UI
resources; they are not a planning strategy. If a host/model repeatedly calls
large discovery tools before obvious app-facing actions, tighten action names,
descriptions, `mcpApp` metadata, or compact-catalog filtering until the direct
path is obvious.

### 2. Add a `link` builder to an action

`defineAction` accepts an optional `link` builder. When set, every MCP/A2A
result for that tool auto-appends a markdown `[label →](absoluteUrl)` block and
a structured `_meta["agent-native/openLink"] = { label, view, webUrl,
desktopUrl, vscodeUrl }`; `tools/list` adds
`annotations["agent-native/producesOpenLink"]` plus a description suffix so the
external agent knows the tool yields an openable link.

Real example — mail's `manage-draft` (`templates/mail/actions/manage-draft.ts`):

```ts
import { buildDeepLink } from "@agent-native/core/server";

function composeDeepLink(draft: Record<string, string>): string {
  return buildDeepLink({
    app: "mail",
    view: "inbox",
    compose: encodeComposeDraft(draft), // base64url JSON → compose-<id> draft
  });
}

export default defineAction({
  // ...schema, run...
  link: ({ result }) => {
    if (!result || typeof result !== "object") return null;
    const draft = (result as { draft?: Record<string, string> }).draft;
    const id = (result as { id?: string }).id;
    if (!draft || !id) return null;
    return { url: composeDeepLink(draft), label: "Open draft in Mail", view: "inbox" };
  },
});
```

List/search actions point at a record-focused view the same way — mail's
`list-emails` returns
`{ url: buildDeepLink({ app: "mail", view: "inbox", params: { label, search } }), label: "Open list in Mail" }`.

**The `link` contract:** pure, synchronous, **no I/O, no awaits**. It runs
best-effort — a throw, `null`, or `undefined` is swallowed and **never** fails
the tool call. It only reads the call's `args` and `result`; it must not query
the DB, read app-state, or call other actions.

### 2a. Optional MCP Apps UI

For hosts that support the MCP Apps extension, an action can also advertise an
inline UI resource with `mcpApp`. This is a progressive enhancement for flows
where the external agent should hand the user an interactive surface instead of
only text — for example reviewing an email draft, editing a calendar invite, or
choosing between generated dashboard variants.

Use the real React app with `embedApp()` whenever the user needs UI. The mental
model is simple: the action's `link` target is also the MCP App embed target.
Expose the operation as a normal action/tool, return a focused deep link with
`link`, and add `mcpApp.resource = embedApp(...)` so capable hosts load that
same route inline instead of opening a new tab. Keep the `link` fallback even
when adding `mcpApp` — non-UI clients still need the "Open in … →" link.

```ts
import { embedApp } from "@agent-native/core";

export default defineAction({
  // ...schema, run, link...
  mcpApp: {
    resource: embedApp({
      title: "Review draft",
      description: "Open the generated draft in the real Mail compose UI.",
      iframeTitle: "Agent-Native Mail",
      openLabel: "Open in Mail",
    }),
  },
});
```

Do not hand-write one-off plain HTML MCP Apps for product UI; if the action
needs a custom surface, add or reuse a real app route/component first and embed
that route. For known first-party handoffs, prefer a direct action with
`mcpApp` (e.g. Mail `manage-draft`, Calendar `manage-event-draft`) over letting
the model hunt through screens; `open_app({ path, embed: true })` is the
generic escape hatch for full dashboards, filtered inboxes, analyses, or
extension pages.

The host bridges (Claude transplant vs. ChatGPT `window.openai`), embed start
tickets, extension-page `srcDoc` rendering inside chat embeds, host sizing
(`embedApp({ height })`), `sendToAgentChat`, `_meta.ui.domain` rules, and
ngrok/prod testing caveats are documented in
**`references/mcp-apps-embedding.md`**. Read it before changing the
`embedApp()` shell, the `ui://` resource, or any host-bridge behavior.

### 3. The `/_agent-native/open` route

`buildDeepLink(...)` returns the app-relative path
`/_agent-native/open?app=…&view=…&<recordId>=…`. The MCP layer turns that into
an absolute web URL (`toAbsoluteOpenUrl`, using the request origin), a
desktop `agentnative://open?…` URL (`toDesktopOpenUrl`), and a VS Code
extension URL (`toVsCodeOpenUrl`) for
`vscode://builderio.agent-native/open?url=…`. When the user clicks the web
link in any browser or inline webview, `GET /_agent-native/open`
(`createOpenRouteHandler`, mounted by the core routes plugin, gated by
`disableOpenRoute`, customizable via `resolveOpenPath`):

1. Resolves the **browser** session via `getSession` (the auth guard bypasses
   the exact path `/_agent-native/open`).
2. If unauthenticated, serves the configured login HTML **at the same URL**
   (`getConfiguredLoginHtml`); the form's success handler reloads
   `window.location`, re-entering the route authenticated — no `?next=`
   plumbing.
3. Writes the existing one-shot `navigate` application-state command (payload =
   every non-reserved query param + `view`) scoped to the browser session's
   email with `requestSource: "deep-link"`, and decodes a `compose` base64url
   draft into a `compose-<id>` key.
4. 302-redirects to a safe same-origin relative path (`to=`, else `/<view>`,
   else `resolveOpenPath`), forwarding `f_*` filter params so lists/dashboards
   open pre-filtered before the `navigate` command is even drained.

Cross-origin, scheme-relative `//host`, and control-char redirects are rejected
(open-redirect guard). **Identity rule:** the link carries no privileged
state — it is just `view` + record ids + filters. The record-focusing
`navigate` write is scoped to whoever is logged into the browser, never the
external agent's MCP token. See **context-awareness** for the
`navigate`/`application_state` contract this bridges to.

### 4. "Ingest" actions for external agents

An action an external agent reads to pull live app state into its own context
must be: `http: { method: "GET" }` + `readOnly: true` +
`publicAgent: { expose: true, readOnly: true, requiresAuth: true }`. GET +
`readOnly` keeps it side-effect-free and out of the screen-refresh change event;
`publicAgent` is the explicit opt-in (public web routes never imply public
MCP/A2A exposure). Design/content ingest actions MUST read **live** state
(e.g. the Yjs document) — not the stale DB snapshot column — so the external
agent sees what the user actually has on screen.

### 5. Advanced: local development & manual setup

The hosted `connect` flow above is the recommended path. For local dev, run
the app (`pnpm dev` / `pnpm exec agent-native dev`) then point a local agent at it:

```bash
pnpm exec agent-native mcp install --client claude-code|claude-code-cli|codex|cowork|cursor|opencode|github-copilot \
  [--app <id>] [--scope user|project]
```

It provisions a token (random `ACCESS_TOKEN` into the workspace `.env` for
local dev, or a `signA2AToken` JWT for a detected hosted origin) and writes an
idempotent stdio server entry — `.mcp.json` / `~/.claude.json` for Claude Code,
the `[mcp_servers.*]` block in `~/.codex/config.toml` for Codex,
`.cursor/mcp.json` / `~/.cursor/mcp.json` for Cursor, `opencode.json` /
`~/.config/opencode/opencode.json` for OpenCode, `.vscode/mcp.json` / VS Code
user `mcp.json` for GitHub Copilot / VS Code, and the Claude-Code JSON shape
for Cowork. The entry runs `pnpm exec agent-native mcp serve --app <id>`, by
default a **thin stdio proxy** to the running local app's
`/mcp` (live registry + HMR + correct deep links stay the single
source of truth; `--standalone` builds the registry in-process). Companion
subcommands: `mcp uninstall`, `mcp status`, `mcp token [--rotate]`. You can
also hand-write an `http` `.mcp.json` entry with a token you supply yourself —
the unmanaged equivalent of what `connect` writes.

**Dev vs production tool surface:** in plain local dev
(`NODE_ENV=development` and `AGENT_MODE !== "production"`) the MCP `tools/list`
deliberately exposes only the generic builtins plus actions with
`publicAgent.requiresAuth === false` — per-app ingest (`requiresAuth: true`)
and mutating actions are filtered out (`filterPublicAgentActions`). The full
surface appears when authenticated as a real caller: a deployed /
`AGENT_MODE=production` app, or a local app reached through `connect` /
`pnpm exec agent-native mcp install` (which provisions an identity-bearing token). A
sparse or empty `tools/list` is diagnostic, not proof of auth failure: check
OAuth scopes, compact-catalog filtering, and the client/server auth status
before telling the user they are unauthenticated.

## Do

- Do connect local/fallback clients to Dispatch with
  `npx @agent-native/core@latest connect https://dispatch.agent-native.com`;
  use `npx -y @agent-native/core@latest reconnect ...` for reauth without
  reinstalling; use a direct app URL only when the host should be isolated to
  one app.
- Do add a `link` builder to any action that produces or lists a navigable
  resource (draft, event, dashboard, document).
- Do add `mcpApp` when a UI-capable MCP host should render an inline review or
  edit surface, while keeping the `link` fallback.
- Do use `embedApp()` / `open_app({ embed: true })` when the right UI is the
  existing React app at a specific route, including full app routes and focused
  component routes like an Analytics chart embed.
- Do test real ChatGPT/Claude web behavior with a fresh inline render after any
  resource-shell or host-bridge change; old frames are not proof that a new
  shell is still broken.
- Do build the URL with `buildDeepLink(...)` — it is the single source of truth
  for the open-route format.
- Do keep `link` pure and synchronous; return `null` when there's nothing to
  open.
- Do keep `link` and `mcpApp` metadata pure and synchronous; use `embedApp()`
  so the user sees the shared React UI.
- Do make external-agent read/ingest actions GET + `readOnly` + `publicAgent`,
  and read live (Yjs) state, not the stale DB column.
- Do let the open route resolve the browser session; pass record ids as deep-
  link params and let the UI focus them via the polled `navigate` command.
- Do return `designSystem` on reads in visual apps (see the actions skill) and
  put `get-design-system` and `list-design-systems` in both `connectorCatalog`
  and `initialToolNames`; a description that points at a tool the connector
  cannot see is a dead end.

## Don't

- Don't copy a deployment's shared `ACCESS_TOKEN` / `A2A_SECRET` into a client
  config when `connect` can mint a per-user, revocable token instead.
- Don't hand-format the `/_agent-native/open` URL — always go through
  `buildDeepLink`.
- Don't do I/O, awaits, DB reads, or app-state reads inside a `link` builder.
- Don't replace deep links with MCP Apps; non-UI clients still need the link.
- Don't hand-write product UI in `mcpApp.resource.html`; use a real React
  route/component and embed it with `embedApp()`.
- Don't test Claude full-app embeds against raw Vite dev modules and conclude
  production is broken; use `pnpm exec agent-native start`, a preview deploy, or prod.
- Don't scope the `navigate` write to the agent token, or pass privileged
  state through the deep link — it's a pure pointer.
- Don't invent a new navigation mechanism; bridge to the existing
  `navigate`/`application_state` contract.
- Don't widen the public template allow-list when scaffolding an app from an
  external agent — the allow-list in `packages/shared-app-config/templates.ts`
  is authoritative and guarded.

## Related Skills

- **actions** — defining actions, `publicAgent`, GET/`readOnly`
- **context-awareness** — the `navigate` / `application_state` contract the
  open route bridges to
- **a2a-protocol** — the `ask-agent` meta-tool and JSON-RPC peer calls
- **adding-a-feature** — the four-area checklist (add a `link` builder when a
  feature produces a navigable resource)

## Blueprint installer

To add a whole new integration the agent-native way, `agent-native add <kind>
<name|url>` prints a curated Markdown blueprint to stdout — pipe it into the
external coding agent you connected (`agent-native add provider stripe |
claude`) and it applies the changes against the live repo. A URL emits a
generic research-and-integrate blueprint instead. Seeded kinds:
`provider` / `channel` / `sandbox` / `action`. Add your own by dropping a
`.md` in `packages/core/blueprints/<kind>/`. See the Blueprint Installer doc.