@agent-native/core 0.92.12 → 0.94.0

package/corpus/core/docs/content/mcp-clients.mdx

@@ -5,14 +5,15 @@ description: "Connect your agent-native app to local MCP servers (claude-in-chro
 
 # MCP Clients
 
-**This page: give your agent more tools.** Point an agent-native app at MCP servers — local or remote — so their tools show up in the agent chat. This is the _client_ direction, the mirror image of [MCP Protocol](/docs/mcp-protocol) (which makes your app an MCP _server_).
+**This page: give your agent more tools.** Point an agent-native app at MCP servers — local or remote — so their tools show up in the agent chat. This is the _client_ direction, the mirror image of [MCP Server](/docs/mcp-protocol) (which makes your app an MCP _server_). Note the dual use of "client" here: this page is about your app acting as an MCP client of _other_ servers — a different sense from an "MCP host" like Claude or Cursor connecting to your app (see [MCP Server](/docs/mcp-protocol) for that direction).
 
 | If you want to…                                              | Read                                     |
 | ------------------------------------------------------------ | ---------------------------------------- |
 | Connect an external agent/host to your app                   | [External Agents](/docs/external-agents) |
 | Give your agent more tools (consume other MCP servers)       | **This page** — MCP Clients              |
 | Build inline UIs that render in Claude/ChatGPT               | [MCP Apps](/docs/mcp-apps)               |
-| Lower-level MCP server reference (auth, tools, custom mount) | [MCP Protocol](/docs/mcp-protocol)       |
+| 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)         |
 
 With one config file, every agent-native app in your workspace gains access to tools provided by MCP servers on your machine: `claude-in-chrome` for browser automation, `@modelcontextprotocol/server-filesystem` for reading files, `@playwright/mcp` for browser testing, and anything else that speaks MCP.
 
@@ -96,7 +97,7 @@ Every source resolves into one runtime **MCP manager**, and every tool it learns
 
 </Diagram>
 
-> The opposite direction — making _your_ app an MCP server that other hosts consume — lives in [MCP Protocol](/docs/mcp-protocol) and [External Agents](/docs/external-agents).
+> The opposite direction — making _your_ app an MCP server that other hosts consume — lives in [MCP Server](/docs/mcp-protocol) and [External Agents](/docs/external-agents).
 
 ## Built-in browser and computer-use capabilities {#built-in-capabilities}
 
@@ -309,9 +310,43 @@ Stdio servers are still a no-op outside Node runtimes, but remote HTTP MCP serve
 
 ## Shared MCP servers via a hub {#hub}
 
-If your workspace runs multiple agent-native apps (e.g. dispatch + mail + clips), you can configure **one** app as the hub and have the others pull its org-scope MCP servers automatically. No per-app copy-paste of URLs and bearer tokens. See [Multi-App Workspace](/docs/multi-app-workspace) for the canonical approach using Dispatch workspace MCP resources.
+If your workspace runs multiple agent-native apps (e.g. dispatch + mail + clips), share MCP servers across all of them without per-app copy-pasting of URLs and bearer tokens. See [Multi-App Workspace](/docs/multi-app-workspace) for the full deployment picture.
 
-Dispatch is the conventional hub — it already coordinates across apps.
+### Recommended: Dispatch workspace MCP resources {#hub-recommended}
+
+For new workspace setups, prefer **Dispatch workspace MCP resources** — the
+same All-app vs selected-app grant model used by workspace skills,
+instructions, and reference resources. Add a workspace resource with:
+
+```json
+{
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
+  },
+  "description": "Shared MCP tools for workspace apps"
+}
+```
+
+Save it under `mcp-servers/<name>.json` with kind `mcp-server`. All-app
+resources are loaded by every workspace app; selected resources load only in
+apps with an active Dispatch grant. Secret placeholders resolve from the app
+secret store, so put raw bearer tokens in Dispatch Vault and reference them
+with `${keys.NAME}` instead of storing them in the resource body.
+
+Apps refresh their merged MCP config about once a minute, so central resource
+edits, grant changes, and removals take effect without a deploy. Set
+`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` to disable that background refresh, or
+set it to a value of at least `5000` milliseconds to tune the interval.
+
+### Legacy: self-hosted hub mode {#hub-legacy}
+
+The mode below remains useful for coarse "share every org-scope MCP server
+from Dispatch" setups and for deployments that already use the MCP settings UI
+as the source of truth. You configure **one** app as the hub and the others
+pull its org-scope MCP servers automatically. Dispatch is the conventional hub
+— it already coordinates across apps.
 
 <Diagram id="doc-block-1dnioze" title="Hub model: one app serves org-scope MCP servers" summary={"Dispatch holds the org-scope MCP servers; consumer apps pull and merge them as mcp__hub_<orgId>_<name>__*. Only org-scope rows are shared — personal credentials stay put."}>
 
@@ -376,36 +411,6 @@ Dispatch is the conventional hub — it already coordinates across apps.
 
 </Diagram>
 
-For new workspace setups, prefer **Dispatch workspace MCP resources** when you
-want the same All-app vs selected-app grant model used by workspace skills,
-instructions, and reference resources. Add a workspace resource with:
-
-```json
-{
-  "type": "http",
-  "url": "https://example.com/mcp",
-  "headers": {
-    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
-  },
-  "description": "Shared MCP tools for workspace apps"
-}
-```
-
-Save it under `mcp-servers/<name>.json` with kind `mcp-server`. All-app
-resources are loaded by every workspace app; selected resources load only in
-apps with an active Dispatch grant. Secret placeholders resolve from the app
-secret store, so put raw bearer tokens in Dispatch Vault and reference them
-with `${keys.NAME}` instead of storing them in the resource body.
-
-Apps refresh their merged MCP config about once a minute, so central resource
-edits, grant changes, and removals take effect without a deploy. Set
-`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` to disable that background refresh, or
-set it to a value of at least `5000` milliseconds to tune the interval.
-
-The older hub mode below remains useful for coarse “share every org-scope MCP
-server from Dispatch” setups and for deployments that already use the MCP
-settings UI as the source of truth.
-
 ### 1. Enable hub-serve on the hub app (dispatch)
 
 Set an env var in dispatch's deployment:
@@ -456,28 +461,10 @@ Every app exposes `GET /_agent-native/mcp/status` for tooling and onboarding:
   }
 ]}>
 
-Reports which configured servers connected, the total live tool count, the merged prefixed tool list, and any per-server connection errors. Use it to build "detected — your agent can now drive X" hints or to debug connection problems.
+Reports which configured servers connected, the total live tool count, the merged prefixed tool list, and any per-server connection errors. Use it to build "detected — your agent can now drive X" hints (e.g. "claude-in-chrome detected — your agent can now drive Chrome") or to debug connection problems.
 
 </Endpoint>
 
-```json
-{
-  "configuredServers": ["claude-in-chrome", "playwright"],
-  "connectedServers": ["claude-in-chrome", "playwright"],
-  "totalTools": 21,
-  "tools": [
-    {
-      "source": "claude-in-chrome",
-      "name": "mcp__claude-in-chrome__navigate",
-      "description": "Navigate the browser to a URL"
-    }
-  ],
-  "errors": {}
-}
-```
-
-Use this to build "claude-in-chrome detected — your agent can now drive Chrome" onboarding hints, or debug MCP connection problems.
-
 ## Failure modes {#failures}
 
 Individual MCP server failures never take down the agent:
@@ -491,3 +478,10 @@ Agent-native will always boot; broken MCP configuration just means fewer tools.
 ## Security {#security}
 
 MCP tools run on your machine with whatever permissions the spawned process has. Treat `mcp.config.json` like any other list of executables you're willing to let the agent drive. Tools from MCP servers appear in the agent's tool-use loop just like your template's own actions, so make sure you trust every server you configure.
+
+## What's next {#whats-next}
+
+- [**MCP Server**](/docs/mcp-protocol) — the opposite direction: making your app an MCP server other hosts consume
+- [**External Agents**](/docs/external-agents) — connecting Claude, Cursor, and other hosts to your app
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — the shared-resource model behind Dispatch workspace MCP resources
+- [**Actions**](/docs/actions) — how your own actions show up alongside MCP tools in the agent's registry

package/corpus/core/docs/content/mcp-protocol.mdx

@@ -1,9 +1,9 @@
 ---
-title: "MCP Protocol"
+title: "MCP Server"
 description: "Expose your agent-native app as a remote MCP server so Claude, ChatGPT, Claude Code, Cursor, and other AI tools can call your app's actions directly."
 ---
 
-# MCP Protocol
+# MCP Server
 
 **This page: the lower-level MCP server reference.** How every agent-native app exposes its actions over MCP — the auto-mounted endpoint, auth modes, the `tools/call` / `ask-agent` surface, and custom mounting. Reach for it when you need server internals; for connecting a host, start with [External Agents](/docs/external-agents).
 
@@ -12,13 +12,14 @@ description: "Expose your agent-native app as a remote MCP server so Claude, Cha
 | Connect an external agent/host to your app                   | [External Agents](/docs/external-agents) |
 | 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)               |
-| Lower-level MCP server reference (auth, tools, custom mount) | **This page** — MCP Protocol             |
+| Build generated inline UI inside Agent-Native chat           | [Generative UI](/docs/generative-ui)     |
+| Lower-level MCP server reference (auth, tools, custom mount) | **This page** — MCP Server               |
 
 Every agent-native app automatically exposes a remote MCP (Model Context Protocol) server, so external AI tools like Claude, ChatGPT custom MCP apps, Claude Code, Cursor, Codex, and VS Code GitHub Copilot can discover and call your app's actions directly — no extra code needed. If your goal is to _connect_ one of those hosts to a hosted app, [External Agents](/docs/external-agents) covers the recommended single Dispatch connector, per-app URLs, OAuth, MCP Apps inline UIs, and deep links. This page documents what sits underneath that.
 
 ## Overview {#overview}
 
-MCP is the standard protocol for connecting AI tools to external capabilities. When you deploy an agent-native app, it auto-mounts an MCP endpoint alongside the existing A2A endpoint. Any MCP-compatible client can connect and use your app's tools.
+MCP is the standard protocol for connecting AI tools to external capabilities. When you deploy an agent-native app, it auto-mounts an MCP endpoint alongside the existing A2A endpoint. Any MCP-compatible host can connect and use your app's tools.
 
 Key concepts:
 
@@ -100,9 +101,9 @@ Both protocols are auto-mounted. Use whichever fits your use case:
 
 You can also use the `ask-agent` MCP tool to get the best of both worlds — call it from Claude Code and let your app's agent reason through complex tasks.
 
-## Manual MCP client config {#manual-config}
+## Manual MCP host config {#manual-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:
+For the recommended one-command setup, use [External Agents](/docs/external-agents). If you are hand-writing MCP config for an OAuth-capable host, add your app as a remote MCP server with no static headers:
 
 ```bash
 claude mcp add --transport http mail https://mail.example.com/_agent-native/mcp
@@ -130,9 +131,9 @@ Then run `/mcp` in Claude Code and choose **Authenticate**. For clients that can
 Claude Code calls: draft-email(to: "john@example.com", subject: "Q3 Report", body: "...")
 ```
 
-## Connecting from other MCP clients {#other-clients}
+## Connecting from other MCP hosts {#other-clients}
 
-Any MCP client that supports Streamable HTTP transport can connect. The endpoint is:
+Any MCP host that supports Streamable HTTP transport can connect. The endpoint is:
 
 ```
 POST https://your-app.example.com/_agent-native/mcp
@@ -140,7 +141,7 @@ POST https://your-app.example.com/_agent-native/mcp
 
 The server supports the standard MCP handshake: `initialize` → `initialized` → `tools/list` → `tools/call`.
 
-<Endpoint id="doc-block-86ic5g" title="MCP endpoint" summary="The auto-mounted Streamable HTTP endpoint every agent-native app exposes." method="POST" path="/_agent-native/mcp" summary="MCP Streamable HTTP endpoint" auth="Standard remote MCP OAuth (Bearer access token), connect-minted JWT, or static ACCESS_TOKEN/ACCESS_TOKENS" params={[
+<Endpoint id="doc-block-86ic5g" title="MCP endpoint" summary="The auto-mounted Streamable HTTP endpoint every agent-native app exposes." method="POST" path="/_agent-native/mcp" auth="Standard remote MCP OAuth (Bearer access token), connect-minted JWT, or static ACCESS_TOKEN/ACCESS_TOKENS" params={[
   {
     "name": "Authorization",
     "in": "header",
@@ -173,7 +174,13 @@ Auto-mounted on every app. Speaks the standard MCP handshake (`initialize` → `
 
 </Endpoint>
 
-If an action declares `mcpApp`, the server also advertises the official MCP Apps extension (`io.modelcontextprotocol/ui`) and supports `resources/list`, `resources/templates/list`, and `resources/read` for the app resource. Hosts that render MCP Apps can show the UI inline; hosts that do not can still call the tool and use the deep-link fallback. Product UIs should use `embedApp()` so the inline surface is the real React app route, or a focused route that renders a shared React component such as an Analytics chart, not a separate plain HTML implementation. The server emits both standard MCP Apps metadata and ChatGPT Apps SDK compatibility metadata so app-capable hosts can find the same `ui://` resource. The current official extension matrix includes Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT, and Cursor; host support varies by version and plan, so use the [External Agents MCP Apps notes](/docs/external-agents#mcp-apps-compatibility) for the user-facing guidance.
+If an action declares `mcpApp`, the server advertises the official MCP Apps extension and supports the resource routes needed to render it inline:
+
+- Advertises `io.modelcontextprotocol/ui` and supports `resources/list`, `resources/templates/list`, and `resources/read` for the app resource.
+- Hosts that render MCP Apps show the UI inline; hosts that don't can still call the tool and use the deep-link fallback.
+- Product UIs should use `embedApp()` so the inline surface is the real React app route, or a focused route that renders a shared React component such as an Analytics chart — never a separate plain-HTML implementation.
+- The server emits both standard MCP Apps metadata and ChatGPT Apps SDK compatibility metadata so app-capable hosts find the same `ui://` resource.
+- The current official extension matrix includes Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT, and Cursor. Host support varies by version and plan — see the [External Agents MCP Apps notes](/docs/external-agents#mcp-apps-compatibility) for the user-facing guidance.
 
 ### MCP App embed bridge {#mcp-app-embed-bridge}
 
@@ -385,3 +392,11 @@ For more complex analysis:
 Claude Code calls: ask-agent(message: "Prepare a full breakdown of Q3 signups by source, with trends")
 → The analytics agent runs multiple queries, reasons about the data, and returns a formatted report
 ```
+
+## What's next {#whats-next}
+
+- [**External Agents**](/docs/external-agents) — the recommended connect flow, catalog tiers, and per-host setup
+- [**MCP Apps**](/docs/mcp-apps) — inline UI resources for hosts that render them
+- [**MCP Clients**](/docs/mcp-clients) — the other direction: your app consuming external MCP servers
+- [**A2A Protocol**](/docs/a2a-protocol) — the sibling protocol for agent-to-agent calls
+- [**Actions**](/docs/actions) — how an action becomes an MCP tool