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