External AgentsCAUTION

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: external-agents
description: >-
  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.
scope: dev
metadata:
  internal: true
---

# 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-

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: External Agents](https://modelsatlas.com/skills/builderio/external-agents/badge.svg)](https://modelsatlas.com/skills/builderio/external-agents/)

Not your listing, or something out of date? Claim or update your listing.