--- title: "External Agents: Claude, ChatGPT, Codex, Cursor, Cowork, Grok" description: "Connect Claude, ChatGPT, Codex, Cursor, Claude Cowork, Grok, or any MCP-compatible host to a hosted agent-native app — then round-trip artifacts back into the running UI with MCP Apps and deep links." search: "Claude Anthropic ChatGPT OpenAI Claude Code Codex Cursor Claude Cowork Grok xAI MCP Apps agent-native connect local agent tools external agents" --- # External Agents **This page: connect an external agent or MCP host to your app.** Use it when Claude, ChatGPT, Codex, Cursor, Claude Cowork, or another MCP-compatible host should drive a hosted agent-native app and round-trip the result back into the running UI. | If you want to… | Read | | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Connect an external agent/host to your app | **This page** — External Agents | | Look up catalog tiers, tool exposure, or the `link`/open-route internals | [External Agents — Catalog & Developer Reference](/docs/external-agents-catalog) | | Give your agent more tools (consume other MCP servers) | [MCP Clients](/docs/mcp-clients) | | Build inline UIs that render in Claude/ChatGPT | [MCP Apps](/docs/mcp-apps) | | Build generated inline UI inside Agent-Native chat | [Generative UI](/docs/generative-ui) | | Lower-level MCP server reference (auth, tools, custom mount) | [MCP Server](/docs/mcp-protocol) | | Make public routes crawlable/citable by any agent, no MCP connection needed | [Public Agent Web](/docs/agent-web-surfaces) | 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 — either by pasting the app's remote MCP URL into a chat host like Claude or ChatGPT, or by running the developer CLI flow for local coding agents. 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. ```html
External host
Claude · ChatGPT · Codex · Cursor
MCP tool calle.g. manage-draft
App produces artifact
+ Open in <app> → deep link / MCP App
User clicks link
/_agent-native/openresolves the browser session
Writes navigate app-state
UI focuses the artifact
``` ```css .xa-trip { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; } .xa-trip .center { display: flex; flex-direction: column; align-items: center; gap: 4px; } .xa-trip .diagram-arrow { font-size: 22px; line-height: 1; } .xa-trip code { font-size: 0.85em; } ``` The identity rule is the safety hinge: the link is just `view` + record ids + filters, and the record-focusing `navigate` write is scoped to whoever is logged into the **browser** — never the external agent's MCP token. That is why the link is safe to paste into a terminal or chat transcript. ## Which agent path do you need? {#which-agent-path} - **External MCP host:** use this page when Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot / VS Code, or another MCP-compatible host should call your hosted agent-native app. - **Your own runtime behind Agent-Native chat:** see [Agent Surfaces](/docs/agent-surfaces#byo-agent) and [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes) when an agent built with another framework should power ``. - **Your app consuming MCP tools:** see [MCP Clients](/docs/mcp-clients) when an agent-native app needs to call tools exposed by another MCP server. - **Another app or agent via A2A:** use [Agent Mentions](/docs/agent-mentions) and [A2A](/docs/a2a-protocol) when agent-native apps should discover and delegate to each other. - **Local custom sub-agents:** use [Agent Resources](/docs/agent-resources) when you want custom agent profiles inside the app's own agent resources. ## Easy setup {#easy-setup} Every Agent-Native app exposes one canonical MCP URL: ```text https://.agent-native.com/mcp ``` In the app, open **Settings → Connections → Integrations** and search for the host name you already know: Claude, Claude Cowork, Claude Code, Anthropic, ChatGPT, OpenAI, Codex, Grok, or xAI. The one external-host result opens **Settings → MCP server** with the closest guide selected. Copy the **MCP server URL** and paste it into the AI host. The URL is the deployed app base URL plus `/mcp`. For workspace or cross-app work, use Dispatch: ```text https://dispatch.agent-native.com/mcp ``` Dispatch is the single gateway for Mail, Calendar, Analytics, Brain, and your workspace apps. In Dispatch's **Agents** page, choose whether the gateway can reach all apps or only selected apps. The connected host then gets `list_apps`, `ask_app`, and `open_app`, filtered to that granted set. For one intentionally isolated app, use that app directly: ```text https://mail.agent-native.com/mcp https://.agent-native.com/mcp ``` Every hosted app also has a helper page at `https://<app>/mcp/connect` with the copyable URL and host-specific tabs for Claude, ChatGPT, Cursor, VS Code, Claude Code, Codex, Grok, and Other. ## Private Content links {#private-content-links} A private Content share link can identify the document without exposing its contents. Its agent-readable access information names two URLs on the same Content instance: ```text https:///mcp https:///mcp/connect ``` Add the `/mcp` URL as a remote MCP server in your agent, authenticate with your Agent-Native account, enable the connection or its tools, and retry the original document request. The `/mcp/connect` page provides setup choices and copyable configuration; opening that page alone does not install a connection in the agent. This flow is host-neutral. Claude, ChatGPT, Claude Code, Codex, Cursor, Antigravity, OpenCode, GitHub Copilot / VS Code, and other MCP-capable hosts all connect to the same instance URL, while their configuration screens and authentication prompts differ. Use the host-specific sections below or the host's current MCP documentation when a client is not listed. Antigravity, for example, manages remote servers from **Settings → Customizations → Installed MCP Servers** or its MCP configuration file; Agent-Native's `connect` command does not currently write Antigravity configuration. Authentication identifies the connected account; it does not broaden document permissions. A public document remains readable from its share page without MCP. A private document becomes readable through MCP only when that account already has access. If `get-document` returns "not found" after connection, that response does not distinguish missing permission from a stale, deleted, or invalid document ID. Verify the link and connected account's access before changing permissions. Reinstalling the connector or changing the public share link does not resolve a confirmed account permission denial. ### The in-app MCP setting {#mcp-settings} Settings includes an **MCP server** page in the app's group. It shows the app's canonical MCP URL, an A2A agent card when available, and the same client setup instructions used by the full connect page. Use **Settings → MCP server** as the in-app starting point, or open `/mcp/connect` directly for the full flow and static-token fallback. ### Claude and ChatGPT OAuth {#oauth} Claude / Claude Desktop: add a custom connector, paste the MCP URL, click **Connect**, sign in with your Agent-Native account, approve the MCP scopes, and enable the connector in a chat. Claude Code uses the same URL: add it as a remote HTTP MCP server, run `/mcp`, then choose **Authenticate**. ChatGPT: custom MCP apps require a supported ChatGPT web workspace. If you have access, open **Settings → Apps → Advanced settings**, enable developer mode when required, choose **Create app**, paste the same MCP URL, choose OAuth, scan the tools, sign in with Agent-Native, approve the requested scopes, and enable the app in a chat. Business, Enterprise, and Edu workspaces support full MCP, including write actions; Pro supports read and fetch in developer mode. If **Apps** or **Create app** is missing, your plan or workspace policy does not allow this setup. OAuth grants are per host and per user. The host stores the tokens and mediates tool/resource calls, so inline MCP App previews never receive raw OAuth tokens. ChatGPT can keep a reviewed or published connector's tool snapshot until you refresh/review it again, so rescan the connector after MCP tool or MCP App metadata changes. If you still have old per-app connectors enabled alongside Dispatch, refresh or reconnect each stale connector; updating Dispatch does not rewrite ChatGPT or Claude's cached Calendar/Mail/etc. snapshots. The `mcp:read` / `mcp:write` / `mcp:apps` / `offline_access` scopes are the same ones covered in [Standard remote MCP OAuth](#standard-oauth) below. ### Cursor, VS Code, and Codex {#install-links} The **Cursor** and **VS Code** tabs in **Settings → MCP server** and on `/mcp/connect` have install buttons. **Add to Cursor** opens Cursor's **Install MCP server?** prompt. **Add to VS Code** and **Add to VS Code Insiders** open a server page with an **Install** button. A link carries only the server name, the transport, and the MCP URL; it never carries a token, header, or account detail. The client runs its own OAuth sign-in the first time it connects. In VS Code, the tools then appear in the Chat view in Agent mode. For Codex, run `codex mcp add --url `, then `codex mcp login ` to sign in with OAuth. The **Codex** tab fills in both values. Goose, Postman, MCPJam, and other clients use the same remote MCP URL through their own MCP-server UIs when their build supports remote OAuth MCP servers. ### Server names {#server-names} The app names its MCP server, and every surface uses that name: the install links, the copyable commands, and `npx @agent-native/core@latest connect`. Production uses the bare name, such as `agent-native-mail`. Beta, preview, and local deployments put the environment first, such as `beta-agent-native-mail`, so one client can keep a production entry and a beta entry side by side. The prefixes are reserved: `mcp.serverName` cannot start with `beta-`, `preview-`, or `local-`, so a beta name never matches another app's production name. Scripts can read the name from `GET /mcp/connect/identity`, which needs no sign-in and returns the server name, app name, app URL, MCP URL, and environment, plus a `connect` flag that is `false` when `mcp.connect` is off. ### Quick test prompt {#quick-test} After connecting, try one of these: ```text Use Agent-Native Analytics to generate a weekly conversion-rate bar chart and show it inline. ``` ```text Use Agent-Native Mail to draft a short follow-up email to me, but do not send it. ``` In hosts that support MCP Apps, Analytics can render real dashboard and analysis routes inline, and Mail can render the real compose UI inline for draft review. In hosts that do not render MCP Apps, the same tool call still returns a deep link such as **Open draft in Mail →** or **Open dashboard in Analytics →**. ## Advanced setup: local agents {#connect} Use this flow for local agent clients on your machine — Claude Code, Claude Code CLI, Codex, Claude Cowork, Cursor, OpenCode, and GitHub Copilot / VS Code. Cursor and other OAuth-native clients can also use the paste-URL flow above when their UI supports remote MCP OAuth. Run the connect command through npm: ```bash npx @agent-native/core@latest connect https://dispatch.agent-native.com ``` 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. For Claude Code, Claude Code CLI, Cursor, OpenCode, and GitHub Copilot / VS Code, `connect` writes a standard remote HTTP MCP entry with no static headers. Restart the client and authenticate from its MCP UI when prompted. 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. Keep the `connect` command running until the browser approval completes. If the waiting process is stopped early, the approval can succeed in the browser but the local client config will not receive the token. If you previously connected Claude Code through the old bearer-token flow, just run the same `npx @agent-native/core@latest 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 | | Cursor | `.cursor/mcp.json` or `~/.cursor/mcp.json` | Standard remote MCP OAuth in Cursor's MCP UI | | OpenCode | `opencode.json` or `~/.config/opencode/opencode.json` | Standard remote MCP OAuth in OpenCode's MCP UI | | GitHub Copilot / VS Code | `.vscode/mcp.json` or VS Code user MCP config | Standard remote MCP OAuth in VS Code's MCP UI | | Codex | `$CODEX_HOME/config.toml` or `~/.codex/config.toml` | Browser-authorized bearer fallback | | Claude Cowork | `~/.cowork/mcp.json` using the Claude Code MCP shape | Browser-authorized bearer fallback | 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. When troubleshooting local MCP config, redact `Authorization`, `http_headers`, and token values before sharing logs. Do not use raw curl as a substitute for a host MCP session; after connecting, use the host-exposed tools or restart the client if the new server is not visible yet. Use `--client codex` (or `--client claude-code`, `--client claude-code-cli`, `--client cursor`, `--client opencode`, `--client github-copilot`, `--client cowork`, `--client all`) to skip the picker for scripts or one-off installs. First-party app skills install the instructions and the hosted MCP connector together with the Agent-Native CLI: ```bash npx @agent-native/core@latest skills add assets # alias: image-generation ``` The Vercel/open Skills CLI path is also available when you only want portable instructions: ```bash npx skills@latest add BuilderIO/agent-native --skill assets ``` The raw `skills` CLI installs `SKILL.md` files only; local MCP hosts still need a connector such as `npx @agent-native/core@latest connect https://assets.agent-native.com`. | Skill | Alias | For | | -------------- | -------------------- | ----------------------------------------------- | | `assets` | `image-generation` | image/video generation | | `content` | `docs` | editing docs, blogs, resources, and MDX content | | `rewind` | `screen-memory` | local Clips screen memory, transcripts, frames | | `design` | `design-exploration` | UI design exploration and prototypes | | `visual-plans` | `agent-native-plans` | visual plans, recaps, and repo-native docs | | `context-xray` | `xray` | local Codex/Claude Code context usage | The default client selection is all supported local clients; add `--client codex`, `--client claude-code`, or another specific target to narrow setup. Inline hosts (ChatGPT, Claude chat on web, desktop, and mobile, plus the Claude Desktop Code tab) render the picker / variant grid in chat; CLI/link-only hosts (Codex CLI, Claude Code terminal, Cowork, Code on claude.ai web) return an "Open in … →" link where the user picks in the browser and pastes a handoff summary back. [Cowork doesn't declare MCP Apps yet](https://github.com/anthropics/claude-code/issues/103924), and using it on the same connector can make inline apps disappear in Chat until you reconnect the connector. When you truly need an isolated app instead of Dispatch's workspace gateway, run the same command with that app's host: ```bash npx @agent-native/core@latest connect https://mail.agent-native.com ``` `connect --all` still exists for legacy per-app client setups, but new workspace setups should prefer the single Dispatch connector. 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. ### Re-authenticating after a 401 {#reconnect} The OAuth owner-binding update requires every existing OAuth connection to [reconnect once](/docs/external-agents#reconnect). Old OAuth access tokens are refused after rollout. Unbound legacy refresh tokens return `invalid_grant`, and pending old authorization codes must restart consent. Newly issued access tokens use their configured lifetime and live membership checks. Legacy A2A-format `mcp-connect` credentials and cross-app A2A tokens are unchanged by this cutover. Connections using old OAuth-format Connect tokens must reconnect too. Once connected, auth should persist long-term. Access tokens last 30 days by default (override with `MCP_OAUTH_ACCESS_TOKEN_TTL` on the server, e.g. `7d` or `12h`), and refresh grants have no fixed expiry, so random 401s should be rare while the user remains authorized. When one does happen, use the lightweight reconnect command rather than reinstalling: ```bash npx @agent-native/core@latest reconnect https://plan.agent-native.com --client codex ``` `reconnect` finds any MCP config entry whose URL ends in `/mcp` for the given host and selected client (matching by URL regardless of connector name), then refreshes or replaces the auth material without touching your installed skills or re-running the full install flow. Pass the base app URL (e.g. `https://plan.agent-native.com`) — the `/mcp` suffix is inferred. Auth and tool loading are per client, so restart/reload that client afterward; Codex needs a new session before newly loaded tools appear. In Claude Code, the equivalent UI path is: run `/mcp` and choose **Authenticate** (or **Reconnect**) for the relevant connector. Never reinstall the skill from scratch just to fix a 401 — `reconnect` is the right tool. ### Connect page fallback {#connect-page-fallback} For MCP hosts that cannot add a remote OAuth URL directly, open the app in your browser and use its **Connect** affordance (served at `https://<app>/mcp/connect`). While logged in, click **Connect / Authorize**. The page hands you either a one-click deep link that configures a detected agent, or a ready-to-paste `.mcp.json` block: ```jsonc // .mcp.json { "mcpServers": { "mail": { "type": "http", "url": "https://mail.agent-native.com/mcp", "headers": { "Authorization": "Bearer " }, }, }, } ``` Restart the agent client after connecting so it picks up the new MCP server. Use this manual bearer block for MCP hosts 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 \ https://dispatch.agent-native.com/mcp ``` This is the same URL-only entry that `npx @agent-native/core@latest connect https://dispatch.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://dispatch.agent-native.com/mcp ``` The OAuth flow is authorization-code + PKCE with refresh tokens, which are not rotated. 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 | | `offline_access` | refresh-token access so compatible hosts can stay connected | When the client requests no explicit scope, the app grants all four so the connector behaves like the browser-authorized Connect flow and can refresh access without another sign-in. Keep the bearer-token Connect page and `npx @agent-native/core@latest connect --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} Once your agent is connected, it sees the [compact catalog](/docs/external-agents-catalog#catalog-tiers) by default: template-declared app actions plus the builtin cross-app verbs (`list_apps`, `open_app`, `ask_app`, and the app-only embed helper). Use `ask_app` to route a natural-language task through an app agent (the same cross-app entry point [A2A](/docs/a2a-protocol) uses). Ask the agent to do real work and it hands back a link straight into the running app: ``` > draft an email to John about the Q3 report Claude Code calls: manage-draft(to: "john@example.com", subject: "Q3 Report", body: "…") → Open draft in Mail → https://mail.agent-native.com/_agent-native/open?app=mail&view=inbox&compose=… ``` Click that link and Mail opens with the draft restored — focused exactly where you, the logged-in user, are. The agent never had to know your session; it just produced the artifact. External agents get the app's real create/update tools — the same named actions the in-app agent calls — so when a user asks for new content (a design, a deck, a form, a document), author it directly and persist it with those tools instead of delegating the work through `ask_app`. Actions marked `endsTurn: true`, such as an in-app question form that waits for the user's answer in that app's own chat, are hidden from MCP, WebMCP, and A2A unless `mcpTool: true` — see [endsTurn in Defining Actions](/docs/actions-defining). Tool inputs and results carry up to 500,000 characters on WebMCP, so a whole screen, deck, or document fits in one write — see [WebMCP](/docs/webmcp). Page-local WebMCP calls carry the browser tab id (the same `getBrowserTabId()` value the UI uses — see [Context Awareness](/docs/context-awareness)), so per-tab navigation and selection resolve to the tab the agent is driving, even when hidden. ### First-class MCP App bridge {#mcp-app-bridge} `embedApp()` starts from the action's `link` target, creates a short-lived embed session, and launches that signed app route. Claude web uses a single-frame transplant path; ChatGPT gets a controlled route iframe with `window.openai` host APIs. All paths render the normal React route. Directly hydrated routes call `ui/update-model-context`, `ui/message`, `ui/open-link`, and `ui/request-display-mode` through the host bridge; the ChatGPT path relays the same requests over `agentNative.mcpHost.*` postMessage. `embedApp({ height })` defaults to `560px` and clamps to `320-900px`. See [MCP Apps](/docs/mcp-apps) for the full bridge details — transplant vs controlled-frame, embed modes, the `ui/*` and postMessage tables, `embedStartUrl`, CSP rules, extension `srcDoc` embedding, height clamping, and the complete host bridge client API. See the full tool catalog, MCP Apps compatibility matrix, generic cross-app verbs, and per-app tour in [External Agents — Catalog & Developer Reference](/docs/external-agents-catalog#tool-exposure). ## What's next {#whats-next} - [External Agents — Catalog & Developer Reference](/docs/external-agents-catalog) — catalog tiers, the `link` builder, the `/_agent-native/open` route, identity-resolution rules, and embed security - [MCP Apps](/docs/mcp-apps) — authoring MCP App UIs, the embed bridge, and host bridge API. - [WebMCP](/docs/webmcp) — page-local tools, the 500,000-character input/result limit, and the browser tab id header. - [MCP Server](/docs/mcp-protocol) — the auto-mounted MCP server and `ask-agent` meta-tool. - [MCP Clients](/docs/mcp-clients) — the symmetric direction: your app consuming local/remote MCP servers. - [A2A Protocol](/docs/a2a-protocol) — the `ask-agent` meta-tool and JSON-RPC peer calls. - [Actions](/docs/actions-overview) — defining actions, `publicAgent`, GET / `readOnly`. - [Context Awareness](/docs/context-awareness) — the `navigate` / `application_state` contract the open route bridges to.