@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/de-DE/external-agents.md

@@ -0,0 +1,619 @@
+---
+title: "Externe Agenten: Claude, ChatGPT, Codex, Cursor, Cowork"
+description: "Verbinden Sie Claude, ChatGPT, Codex, Cursor, Claude Cowork oder einen beliebigen MCP-kompatiblen Host mit einer gehosteten agentennativen App – und leiten Sie Artefakte dann mit MCP Apps und Deep Links zurück in das laufende UI."
+search: "Claude ChatGPT Claude Code Codex Cursor Claude Cowork MCP Apps Agent-nativ Verbindung lokaler Agent Tools externe Agenten"
+---
+
+# Externe Agenten
+
+**Diese Seite: Verbinden Sie einen externen Agenten oder MCP-Host mit Ihrer App.** Verwenden Sie es, wenn Claude, ChatGPT, Codex, Cursor, Claude Cowork oder ein anderer MCP-kompatibler Host eine gehostete agentennative App steuern und das Ergebnis zurück in den laufenden UI zurückleiten soll.
+
+| Wenn Sie möchten...                                                                                    | Lesen                              |
+| ------------------------------------------------------------------------------------------------------ | ---------------------------------- |
+| Verbinden Sie einen externen Agenten/Host mit Ihrer App                                                | **Diese Seite** – Externe Agenten  |
+| Geben Sie Ihrem Agent mehr Tools (nutzen Sie andere MCP-Server)                                        | [MCP Clients](/docs/mcp-clients)   |
+| Erstellen Sie Inline-UIs, die in Claude/ChatGPT rendern                                                | [MCP Apps](/docs/mcp-apps)         |
+| MCP-Serverreferenz auf niedrigerer Ebene (Authentifizierung, Tools, benutzerdefinierte Bereitstellung) | [MCP Protocol](/docs/mcp-protocol) |
+
+Eine agentennative App ist von jedem MCP-kompatiblen Host erreichbar – Claude, Claude Desktop, Claude Code, ChatGPT benutzerdefinierte MCP-Apps, Codex, Cursor, Claude Cowork, VS Code GitHub Copilot, Goose, Postman, MCPJam und zukünftige Clients, die den Standard implementieren. Externe Agenten sind hervorragend darin, Artefakte (einen Entwurf, ein Ereignis, ein Dashboard) zu erstellen, sie befinden sich jedoch oft in einem Terminal oder einer anderen App. Ohne Brücke erhält der Benutzer eine Wand aus JSON und muss das Ding suchen.
+
+Die externe Agentenbrücke schließt den Kreis. Zuerst verbinden Sie Ihren eigenen Agenten mit einer **gehosteten** App – entweder indem Sie den Remote-MCP URL der App in einen Chat-Host wie Claude oder ChatGPT einfügen oder indem Sie den Entwickler-Flow CLI für lokale Codierungsagenten ausführen. Dann erledigt der Agent die Arbeit über MCP und übergibt dem Benutzer entweder eine Inline-**MCP-App** UI in kompatiblen Hosts oder einen einzelnen **„Öffnen in <App> →“**-Link, der die echte App öffnet, die sich genau auf das konzentriert, was produziert wurde. Es verwendet den vorhandenen `navigate`/`application_state`-Vertrag, den der UI bereits alle 2 Sekunden entlädt (siehe [Context Awareness](/docs/context-awareness)) – es gibt keinen zweiten Navigationsmechanismus.
+
+```an-diagram title="The external-agent round-trip" summary="An external host calls a tool over MCP; the app returns an artifact plus an Open link. Clicking it resolves the browser session and focuses the artifact in the running UI — the link carries no privileged state."
+{
+  "html": "<div class=\"xa-trip\"><div class=\"diagram-box\" data-rough>External host<br><small class=\"diagram-muted\">Claude &middot; ChatGPT &middot; Codex &middot; Cursor</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">MCP tool call</span><small class=\"diagram-muted\">e.g. <code>manage-draft</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>App produces artifact<br><small class=\"diagram-muted\">+ <code>Open in &lt;app&gt; &rarr;</code> deep link / MCP App</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>User clicks link</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill ok\"><code>/_agent-native/open</code></span><small class=\"diagram-muted\">resolves the <strong>browser</strong> session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Writes <code>navigate</code> app-state<br><small class=\"diagram-muted\">UI focuses the artifact</small></div></div>",
+  "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:.85em}"
+}
+```
+
+Die Identitätsregel ist das Sicherheitsscharnier: Der Link besteht nur aus `view` + Datensatz-IDs + Filter, und der auf den Datensatz fokussierte `navigate`-Schreibvorgang ist auf denjenigen beschränkt, der im **Browser** angemeldet ist – niemals auf das MCP-Token des externen Agenten. Aus diesem Grund kann der Link sicher in ein Terminal- oder Chat-Protokoll eingefügt werden.
+
+## Welchen Agentenpfad benötigen Sie? {#which-agent-path}
+
+- **Externer MCP-Host:** Verwenden Sie diese Seite, wenn Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot/VS Code oder ein anderer MCP-kompatibler Host Ihre gehostete agentennative App aufrufen soll.
+- **Ihre eigene Laufzeit hinter dem Agent-Native-Chat:** siehe [Agent Surfaces](/docs/agent-surfaces#byo-agent) und [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes), wenn ein Agent, der mit einem anderen Framework erstellt wurde, `<AssistantChat runtime={...}>` unterstützen soll.
+- **Ihre App nutzt MCP-Tools:** Sehen Sie sich [MCP Clients](/docs/mcp-clients) an, wenn eine agentennative App Tools aufrufen muss, die von einem anderen MCP-Server bereitgestellt werden.
+- **Eine andere App oder ein Agent über A2A:** Verwenden Sie [Agent Mentions](/docs/agent-mentions) und [A2A](/docs/a2a-protocol), wenn agentennative Apps einander erkennen und delegieren sollen.
+- **Lokale benutzerdefinierte Unteragenten:** verwenden Sie [Workspace](/docs/workspace), wenn Sie benutzerdefinierte Agentenprofile innerhalb des agentennativen Arbeitsbereichs selbst wünschen.
+
+## Einfache Einrichtung {#easy-setup}
+
+Fügen Sie einen Remote-MCP-Connector zum Host hinzu, auf dem Sie Agent-Native verwenden möchten.
+
+Für arbeitsplatz- oder app-übergreifendes Arbeiten verwenden Sie Dispatch:
+
+```text
+https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+Dispatch ist das einzige Gateway für Mail, Kalender, Analytics, Brain und Ihr
+Workspace-Apps. Wählen Sie auf der Seite **Agents** von Dispatch aus, ob das Gateway dies kann
+Erreichen Sie alle Apps oder nur ausgewählte Apps. Der verbundene Host erhält dann
+`list_apps`, `ask_app` und `open_app`, gefiltert nach diesem gewährten Satz.
+
+Für eine absichtlich isolierte App verwenden Sie diese App direkt:
+
+```text
+https://mail.agent-native.com/_agent-native/mcp
+https://<your-app>.agent-native.com/_agent-native/mcp
+```
+
+Jede gehostete App verfügt auch über eine Hilfsseite unter
+`https://<app>/_agent-native/mcp/connect` mit dem kopierbaren URL und
+hostspezifische Registerkarten für Claude, ChatGPT, Cursor, Claude-Code, Codex und Andere.
+
+### Claude und ChatGPT OAuth {#oauth}
+
+Claude / Claude Desktop: Fügen Sie einen benutzerdefinierten Connector hinzu, fügen Sie MCP URL ein und klicken Sie auf
+**Verbinden**, melden Sie sich mit Ihrem Agent-Native-Konto an, genehmigen Sie die MCP-Bereiche,
+und aktivieren Sie den Connector in einem Chat. Der Claude-Code verwendet denselben URL: Fügen Sie ihn als
+Remote-HTTP MCP-Server, führen Sie `/mcp` aus und wählen Sie dann **Authentifizieren**.
+
+ChatGPT: Verwenden Sie einen Arbeitsbereich, in dem sich benutzerdefinierte MCP-Konnektoren oder Entwicklermodus-Apps befinden
+aktiviert, erstellen Sie einen benutzerdefinierten Connector/eine benutzerdefinierte App, fügen Sie denselben MCP URL ein, wählen Sie OAuth,
+Tools scannen/entdecken, sich mit Agent-Native anmelden, die Bereiche genehmigen und aktivieren
+der Connector in einem Chat.
+
+OAuth-Zuschüsse gelten pro Host und pro Benutzer. Der Host speichert die Token und
+vermittelt Tool-/Ressourcenaufrufe, sodass Inline-MCP-App-Vorschauen niemals Rohdaten erhalten
+OAuth-Token. ChatGPT kann das Tool eines überprüften oder veröffentlichten Connectors behalten
+Snapshot, bis Sie ihn erneut aktualisieren/überprüfen, also scannen Sie den Connector nach MCP erneut
+Tool- oder MCP-App-Metadatenänderungen. Wenn Sie noch alte Pro-App-Konnektoren haben
+neben Dispatch aktiviert, jeden veralteten Connector aktualisieren oder erneut verbinden; Aktualisierung
+Dispatch schreibt den zwischengespeicherten Kalender/Mail/usw. von ChatGPT oder Claude nicht neu.
+Schnappschüsse. Die Bereiche sind:
+
+| Geltungsbereich | Was es ermöglicht                                        |
+| --------------- | -------------------------------------------------------- |
+| `mcp:read`      | Schreibgeschützte Tools und Tool-/Ressourcenerkennung    |
+| `mcp:write`     | Entwurf, Aktualisierung und andere Änderungen actions    |
+| `mcp:apps`      | Inline-MCP-Apps, Diagramme, Dashboards, Entwürfe und UIs |
+
+Cursor, Goose, Postman, MCPJam und VS Code GitHub Copilot verwenden dieselbe Fernbedienung
+MCP URL über ihre eigenen MCP-Server UIs, wenn ihr Build Remote-OAuth unterstützt
+MCP-Server.
+
+### Schnelltestaufforderung {#quick-test}
+
+Versuchen Sie nach dem Herstellen einer Verbindung Folgendes:
+
+```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.
+```
+
+Auf Hosts, die MCP-Apps unterstützen, kann Analytics echte Dashboard- und Analyserouten inline rendern, und Mail kann den echten Inhalt UI inline für die Entwurfsprüfung rendern. Auf Hosts, die keine MCP-Apps rendern, gibt derselbe Tool-Aufruf immer noch einen Deep-Link zurück, z. B. **Entwurf in Mail öffnen →** oder **Dashboard in Analytics öffnen →**.
+
+## Erweiterte Einrichtung: lokale Agenten {#connect}
+
+Verwenden Sie diesen Ablauf für lokale Agent-Clients auf Ihrem Computer – Claude-Code, Claude-Code CLI, Codex, Claude Cowork, Cursor, OpenCode und GitHub Copilot/VS-Code. Cursor und andere OAuth-native Clients können auch den obigen Paste-URL-Ablauf verwenden, wenn ihr UI Remote-MCP OAuth unterstützt.
+
+Führen Sie den Verbindungsbefehl über npm aus:
+
+```bash
+npx @agent-native/core@latest connect https://dispatch.agent-native.com
+```
+
+Der Befehl fragt, welche lokalen Agent-Clients die MCP-Konfiguration erhalten sollen. Beim ersten Mal werden alle Clients vorausgewählt; Nach der Auswahl wird die Auswahl in `~/.agent-native/connect.json` gespeichert, sodass Sie sie beim nächsten Durchlauf mit der Eingabetaste wiederverwenden oder die markierten Elemente bearbeiten können.
+
+Für Claude-Code, Claude-Code, CLI, Cursor, OpenCode und GitHub Copilot/VS-Code schreibt `connect` einen Standard-Remote-HTTP MCP-Eintrag ohne statische Header. Starten Sie den Client neu und authentifizieren Sie sich über seinen MCP UI, wenn Sie dazu aufgefordert werden. Für Codex und Claude Cowork verwendet `connect` den Kompatibilitätsgerätecode-Ablauf: Es öffnet Ihren Browser in der App, Sie klicken einmal auf **Autorisieren** und der Befehl schreibt einen bereichsbezogenen Bearer-Token-Eintrag. Wenn Sie eine Mischung aus Clients wählen, wird beides erreicht.
+
+Lassen Sie den Befehl `connect` laufen, bis die Browsergenehmigung abgeschlossen ist. Wenn die
+Wartevorgang wird vorzeitig gestoppt, die Genehmigung kann im Browser jedoch erfolgreich sein
+Die lokale Client-Konfiguration erhält das Token nicht.
+
+Wenn Sie den Claude-Code zuvor über den alten Bearer-Token-Fluss verbunden haben, führen Sie einfach denselben `npx @agent-native/core@latest connect ... --client claude-code`-Befehl erneut aus. Der CLI ersetzt die alten `Authorization`-Header durch den nur für URL gültigen OAuth-Eintrag und fordert Sie auf, sich erneut über `/mcp` zu authentifizieren.
+
+| Lokaler Kunde                 | Konfiguration geschrieben von `connect`                        | Authentifizierungsablauf                            |
+| ----------------------------- | -------------------------------------------------------------- | --------------------------------------------------- |
+| Claude-Code / Claude-Code CLI | `.mcp.json` oder `~/.claude.json`, je nach `--scope`           | Standardfernbedienung MCP OAuth im Claude `/mcp` UI |
+| Cursor                        | `.cursor/mcp.json` oder `~/.cursor/mcp.json`                   | Standardfernbedienung MCP OAuth in Cursors MCP UI   |
+| OpenCode                      | `opencode.json` oder `~/.config/opencode/opencode.json`        | Standard-Remote MCP OAuth in OpenCodes MCP UI       |
+| GitHub Copilot/VS-Code        | `.vscode/mcp.json`- oder VS-Code-Benutzer-MCP-Konfiguration    | Standard-Remote MCP OAuth in VS Codes MCP UI        |
+| Codex                         | `$CODEX_HOME/config.toml` oder `~/.codex/config.toml`          | Browser-autorisierter Bearer-Fallback               |
+| Claude Cowork                 | `~/.cowork/mcp.json` unter Verwendung der Form Claude Code MCP | Browser-autorisierter Bearer-Fallback               |
+
+Starten Sie den Agent-Client nach der Verbindung neu, damit er den neuen MCP-Server aufnimmt. OAuth-native Clients fordern Sie dann möglicherweise auf, sich von ihrem MCP UI aus zu authentifizieren.
+
+Bei der Fehlerbehebung in der lokalen MCP-Konfiguration müssen `Authorization`, `http_headers` usw. geschwärzt werden.
+und Tokenwerte, bevor Sie Protokolle freigeben. Verwenden Sie rohe Locken nicht als Ersatz für ein
+MCP-Sitzung hosten; Verwenden Sie nach dem Herstellen der Verbindung die vom Host bereitgestellten Tools oder starten Sie den
+Client, wenn der neue Server noch nicht sichtbar ist.
+
+Verwenden Sie `--client codex` (oder `--client claude-code`, `--client claude-code-cli`, `--client cursor`, `--client opencode`, `--client github-copilot`, `--client cowork`, `--client all`), um die Auswahl für Skripts oder einmalige Installationen zu überspringen.
+
+Die Erstanbieter-App skills installiert die Anweisungen und den gehosteten MCP-Connector zusammen mit dem Agent Native CLI:
+
+```bash
+npx @agent-native/core@latest skills add assets              # alias: image-generation
+```
+
+Der Vercel/open Skills CLI-Pfad ist auch verfügbar, wenn Sie nur portabel möchten
+Anweisungen:
+
+```bash
+npx skills@latest add BuilderIO/agent-native --skill assets
+```
+
+Der rohe `skills` CLI installiert nur `SKILL.md`-Dateien; lokale MCP-Clients noch
+benötigen einen Anschluss wie `npx @agent-native/core@latest connect https://assets.agent-native.com`.
+
+| Fähigkeit | Alias              | Für                    |
+| --------- | ------------------ | ---------------------- |
+| `assets`  | `image-generation` | Bild-/Videogenerierung |
+
+Die Standard-Clientauswahl umfasst alle unterstützten lokalen Clients. Fügen Sie `--client codex`, `--client claude-code` oder ein anderes spezifisches Ziel hinzu, um das Setup einzugrenzen. Inline-Hosts (ChatGPT, Claude.ai, Claude Desktop-Hauptchat) rendern das Auswahl-/Variantenraster im Chat; CLI/Link-only-Hosts (Codex, Claude Code, Claude Desktop-Registerkarte „Code“) geben einen Link „Öffnen in … →“ zurück, den der Benutzer im Browser auswählt und eine Übergabezusammenfassung zurück einfügt.
+
+Wenn Sie wirklich eine isolierte App anstelle des Workspace-Gateways von Dispatch benötigen
+Führen Sie denselben Befehl mit dem Host dieser App aus:
+
+```bash
+npx @agent-native/core@latest connect https://mail.agent-native.com
+```
+
+`connect --all` existiert weiterhin für ältere Pro-App-Client-Setups, ist aber neu
+Workspace-Setups sollten den einzelnen Dispatch-Connector bevorzugen.
+
+Die Verbindung ist **pro Benutzer, bereichsbezogen und widerrufbar**. Im OAuth-Pfad speichert der Host die Token nach der `/mcp`-Authentifizierung; Im Fallback-Pfad ist die von Ihnen autorisierte Browsersitzung die Identität, als die der Agent fungiert. Das gemeinsame Geheimnis der Bereitstellung wird durch nichts preisgegeben.
+
+### Erneute Authentifizierung nach einem 401 {#reconnect}
+
+Sobald die Verbindung hergestellt ist, sollte die Authentifizierung langfristig bestehen bleiben – Zugriffstokens sind standardmäßig 30 Tage gültig (Überschreibung durch `MCP_OAUTH_ACCESS_TOKEN_TTL` auf dem Server, z. B. `7d` oder `12h`) mit einem gleitenden Aktualisierungsfenster von 365 Tagen, sodass zufällige 401-Fehler selten sein sollten. Wenn einer auftritt, verwenden Sie den einfachen Befehl zum erneuten Verbinden, anstatt eine Neuinstallation durchzuführen:
+
+```bash
+npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex
+```
+
+`reconnect` findet jeden MCP-Konfigurationseintrag, dessen URL auf `/_agent-native/mcp` für den angegebenen Host und ausgewählten Client endet (Übereinstimmung mit URL unabhängig vom Connector-Namen), und aktualisiert oder ersetzt dann das Authentifizierungsmaterial, ohne Ihren installierten skills zu berühren oder den vollständigen Installationsablauf erneut auszuführen. Übergeben Sie die Basis-App URL (z. B. `https://plan.agent-native.com`) – das Suffix `/_agent-native/mcp` wird abgeleitet. Authentifizierung und Tool-Laden erfolgen pro Client. Starten Sie diesen Client daher anschließend neu bzw. laden Sie ihn neu. Codex benötigt eine neue Sitzung, bevor neu geladene Tools angezeigt werden.
+
+Im Claude-Code lautet der entsprechende UI-Pfad: Führen Sie `/mcp` aus und wählen Sie **Authentifizieren** (oder **Erneut verbinden**) für den relevanten Connector.
+
+Installieren Sie den Skill niemals von Grund auf neu, nur um einen 401 zu beheben – `reconnect` ist das richtige Werkzeug.
+
+### Connect-Seiten-Fallback {#connect-page-fallback}
+
+Für MCP-Clients, die keinen Remote-OAuth URL direkt hinzufügen können, öffnen Sie die App in Ihrem Browser und nutzen Sie das **Connect**-Angebot (bereitgestellt unter `https://<app>/_agent-native/mcp/connect`). Klicken Sie im angemeldeten Zustand auf **Verbinden / Autorisieren**. Auf der Seite erhalten Sie entweder einen One-Click-Deep-Link, der einen erkannten Agenten konfiguriert, oder einen zum Einfügen bereiten `.mcp.json`-Block:
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "mail": {
+      "type": "http",
+      "url": "https://mail.agent-native.com/_agent-native/mcp",
+      "headers": { "Authorization": "Bearer <minted-token>" },
+    },
+  },
+}
+```
+
+Starten Sie den Agent-Client nach der Verbindung neu, damit er den neuen MCP-Server aufnimmt.
+
+Verwenden Sie diesen manuellen Trägerblock für MCP-Clients, die den standardmäßigen Remote-MCP OAuth-Fluss nicht abschließen können, oder für einmaliges Debuggen, wenn Sie explizit ein Token einfügen möchten.
+
+### Standardfernbedienung MCP OAuth {#standard-oauth}
+
+Gehostete agentennative Apps unterstützen auch den Standard-Remote-Flow MCP OAuth. Für Clients, die MCP OAuth implementieren, fügen Sie den Remote-HTTP-Server URL ohne statische Header hinzu:
+
+```bash
+claude mcp add --transport http agent-native \
+  https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+Dies ist derselbe Nur-URL-Eintrag, den `npx @agent-native/core@latest connect https://dispatch.agent-native.com --client claude-code` für Sie schreibt. Führen Sie dann `/mcp` im Claude-Code aus und wählen Sie **Authentifizieren**. Der Client erkennt die Authentifizierung anhand der `401 WWW-Authenticate`-Challenge des MCP-Servers, ruft `/.well-known/oauth-protected-resource` und `/.well-known/oauth-authorization-server` ab, registriert dynamisch einen öffentlichen OAuth-Client, öffnet die Autorisierungsseite der App und speichert das resultierende Token sicher. ChatGPT-Entwicklermodus-Konnektoren verwenden denselben Server URL:
+
+```text
+https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+Der OAuth-Fluss besteht aus Autorisierungscode + PKCE mit Aktualisierungstokenrotation. Zugriffstoken sind an die genaue MCP-Ressource URL zielgruppengebunden und tragen die signierte Benutzer-/Organisationsidentität, sodass Toolaufrufe, `resources/read` und MCP App-Iframe-initiiertes `tools/call` alle denselben `runWithRequestContext`-Mandantenbereich durchlaufen wie der vorhandene Connect-Minted-JWT-Pfad. Der Iframe empfängt niemals rohe OAuth-Token; Der Host vermittelt Anrufe über die authentifizierte MCP-Verbindung.
+
+Aktuelle Bereiche sind:
+
+| Geltungsbereich | Erlaubt                                                                             |
+| --------------- | ----------------------------------------------------------------------------------- |
+| `mcp:read`      | schreibgeschützt MCP actions und normale Tool-/Ressourcenerkennung                  |
+| `mcp:write`     | Mutation von actions und dem Meta-Tool `ask-agent`                                  |
+| `mcp:apps`      | MCP Auflisten/Lesen von Apps-Ressourcen und Inline-UI-Rendering, sofern unterstützt |
+
+Wenn der Client keinen expliziten Bereich anfordert, gewährt die App alle drei, sodass sich der Connector wie der vom Browser autorisierte Connect-Flow verhält. Behalten Sie die Bearer-Token-Connect-Seite und den `npx @agent-native/core@latest connect --token <token>`-Fallback für lokale Entwickler, Fallback-Hosts und Clients bei, bei denen Sie einen sofort einfügbaren Konfigurationsblock benötigen.
+
+## Katalogstufen {#catalog-tiers}
+
+Dies ist die kanonische Erklärung der MCP-Katalogebenen – andere Seiten verlinken hier.
+
+Der MCP-Server stellt jedem Aufrufer standardmäßig einen kompakten Katalog bereit\*\* – gehostete Connectors (ChatGPT, Claude), Code-Clients (Claude Code, Cursor, Codex) und den lokalen CLI/stdio-Proxy gleichermaßen. Die vollständige Aktionsoberfläche wird nur bei ausdrücklicher Einwilligung bereitgestellt. Der Katalog wird niemals aus dem Clientnamen oder dem Benutzeragenten abgeleitet.
+
+```an-diagram title="Two catalog tiers" summary="Every caller gets the compact tier by default; the full ~105-tool surface is opt-in only. tool-search bridges the gap so nothing is ever truly hidden."
+{
+  "html": "<div class=\"xa-tiers\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill ok\">Compact / connector tier &middot; default</span><strong>~20&ndash;30 tools</strong><small class=\"diagram-muted\">Template-declared app actions + cross-app builtins (<code>list_apps</code>, <code>open_app</code>, <code>ask_app</code>, <code>create_embed_session</code>) + always-present <code>tool-search</code>.</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Full tier &middot; opt-in</span><strong>~105 tools</strong><small class=\"diagram-muted\">Explicit opt-in only: <code>--full-catalog</code> token or <code>AGENT_NATIVE_MCP_FULL_CATALOG=1</code>.</small></div></div><p class=\"diagram-muted note\"><code>tool-search</code> reaches any full-tier tool on demand &mdash; so the compact default keeps context small without hiding capability.</p>",
+  "css": ".xa-tiers{display:flex;align-items:stretch;gap:14px;flex-wrap:wrap}.xa-tiers .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;flex:1;min-width:240px}.xa-tiers .diagram-arrow{align-self:center;font-size:24px;line-height:1}.xa-tiers .note{flex-basis:100%;margin:4px 0 0;font-size:.85em}.xa-tiers code{font-size:.85em}"
+}
+```
+
+### Kompakt-/Connector-Stufe (Standard) {#connector-tier}
+
+Standardmäßig sieht jeder verbundene Agent einen kleinen, kuratierten Katalog (ca. 20–30 Tools gegenüber ca. 105 in der gesamten Oberfläche):
+
+- **Von der Vorlage deklarierte App actions** – die sichere Zulassungsliste auf App-Ebene. Für den Plan sind das `create-visual-plan`, `get-visual-plan`, `share-resource`, `navigate`, `tool-search` und ähnliche.
+- **Integrierte App-übergreifende Tools** – `list_apps`, `open_app`, `ask_app`, `create_embed_session`.
+- **`tool-search`** ist immer vorhanden, sodass alles außerhalb der Liste bei Bedarf erreichbar bleibt (siehe unten).
+
+Tools außerhalb der Liste – zum Beispiel `db-exec`, `seed-*`, die Erweiterungssuite, Browser-Sitzungstools und Kontext-Röntgentools – werden nicht angekündigt und Aufrufe an sie werden mit „Unbekanntes Tool“ abgelehnt, es sei denn, der Aufrufer hat sich für den vollständigen Katalog entschieden. Dies hält das Kontextfenster jedes verbundenen Agenten klein und entfernt Fußfeuerwaffen, die nur für die lokale Entwicklung mit einem Mandanten sicher sind. Die Connector-Ebene ist aktiv, **immer wenn eine Vorlage ein `connectorCatalog` deklariert** – sie ist nicht hinter einer Umgebungsvariablen geschützt.
+
+`tool-search` funktioniert auf zwei Arten: Aufruf mit **keine Abfrage** für das vollständige Menü der Werkzeugnamen plus einzeilige Beschreibungen (günstig, keine Schemata) oder mit einer Abfrage für Rangfolgeübereinstimmungen mit Parameterzusammenfassungen. Auf diese Weise erkennt und lädt ein kompakter Client jedes vollflächige Werkzeug, wenn er eines benötigt.
+
+### Vollständige Stufe (nur explizites Opt-in) {#full-tier}
+
+Die vollständige ~105-Tool-Aktionsoberfläche wird nur bei expliziter Einwilligung bereitgestellt, und zwar auf zwei Arten:
+
+- **Pro Token** – neu mit `--full-catalog`, das einen `catalog_scope: "full"`-Anspruch in den JWT einbettet. Nachfolgende Anfragen umgehen den Kompaktfilter für dieses Token:
+
+  ```bash
+  npx @agent-native/core@latest connect https://plan.agent-native.com --client codex --full-catalog
+  ```
+
+- **Pro Bereitstellung** – Legen Sie `AGENT_NATIVE_MCP_FULL_CATALOG=1` (Serverprozessumgebung) fest, um allen Aufrufern die gesamte Oberfläche bereitzustellen. Verwenden Sie es für Single-Tenant-gehostete Instanzen, die die volle Oberfläche ohne Opt-up pro Token wünschen.
+
+### Vorlagendeklaration {#catalog-declaration}
+
+Vorlagen deklarieren ihren Connector-Katalog in den `createAgentChatPlugin`-Optionen:
+
+```ts
+export default createAgentChatPlugin({
+  appId: "plan",
+  actions: loadActionsFromStaticRegistry(actionsRegistry),
+  connectorCatalog: [
+    "create-visual-plan",
+    "get-visual-plan",
+    "list-visual-plans",
+    "update-visual-plan",
+    // … other safe app-level actions
+    "set-resource-visibility",
+    "share-resource",
+    "upload-image",
+    "navigate",
+    "view-screen",
+    "manage-automations",
+    "tool-search",
+  ],
+});
+```
+
+Die integrierten App-übergreifenden Tools (`list_apps`, `open_app`, `ask_app`,
+`create_embed_session`, `create_workspace_app`, `list_templates`) sind immer
+unabhängig von der deklarierten Liste enthalten.
+
+## Was Sie tun können, sobald die Verbindung hergestellt ist {#what-you-can-do}
+
+Sobald Ihr Agent verbunden ist, erhält jeder Anrufer standardmäßig den kompakten Katalog
+(siehe [Catalog tiers](#catalog-tiers)) – Code-/STDIO-Entwickler-Clients, die lokalen
+CLI-Proxy und Chat-Hosts wie Claude und ChatGPT gleichermaßen. Diese Oberfläche ist die
+Vorlagendeklarierte App actions plus die integrierten App-übergreifenden Verben (`list_apps`,
+`open_app`, `ask_app` und der Nur-App-Einbettungshelfer). Verwenden Sie `ask_app`, um ein
+Aufgabe in natürlicher Sprache über einen App-Agenten (derselbe app-übergreifende Einstiegspunkt
+[A2A](/docs/a2a-protocol) verwendet). `tool-search` ist immer vorhanden, also jedes Werkzeug
+außerhalb der kompakten Liste bleibt bei Bedarf erreichbar. Um das vollständige ~105-Tool zu erhalten
+im Vordergrund auftauchen, explizit mit `--full-catalog` oder
+`AGENT_NATIVE_MCP_FULL_CATALOG=1`. Bitten Sie den Agenten in jedem Fall um echte Arbeit
+und es gibt einen Link direkt an die laufende App zurück:
+
+```
+> 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=…
+```
+
+Klicken Sie auf diesen Link und Mail wird mit dem wiederhergestellten Entwurf geöffnet – genau dort, wo Sie, der angemeldete Benutzer, sind. Der Agent musste Ihre Sitzung nie kennen; Es hat gerade das Artefakt erzeugt.
+
+### MCP Apps-Kompatibilität {#mcp-apps-compatibility}
+
+Agent-native Apps sprechen auch die offizielle MCP Apps-Erweiterung. Bei jeder Aktion
+deklariert `mcpApp`, der Server kündigt an
+`extensions["io.modelcontextprotocol/ui"]`, beinhaltet `_meta.ui.resourceUri` /
+`_meta["ui/resourceUri"]` in `tools/list` und bedient die HTML UI bis
+`resources/list` + `resources/read` als `text/html;profile=mcp-app`. Ressource
+Sicherheitsmetadaten wie CSP und Sandbox-Berechtigungen befinden sich auf der Ressource
+Einträge und `resources/read`-Inhalte, nicht im Tool-Deskriptor.
+
+Für ChatGPT/Claude-App-Hosts im OAuth-Stil ist die Erkennungsoberfläche standardmäßig kompakt: `tools/list` und `resources/list` geben den generischen `open_app`-Einbettungspfad anstelle jeder aktionsspezifischen MCP-App-Ressource bekannt (siehe [Catalog tiers](#catalog-tiers)). Markieren Sie eine einzelne Aktion nur dann mit `mcpApp.compactCatalog: true`, wenn sie wirklich bei der Chat-Host-Erkennung sichtbar bleiben muss.
+
+Dadurch steht jedem kompatiblen Host die gleiche App-Oberfläche zur Verfügung, anstatt Shims pro Client zu erstellen. Welche Hosts MCP-Apps inline rendern (und das Connector-Cache-Problem nach Metadatenänderungen), liegt in [MCP Apps → Client support and caching](/docs/mcp-apps#client-support) – diese Seite ist das einzige Zuhause für die Client-Matrix.
+
+In der Praxis sollte jede agentennative App mit beidem erstellt werden: MCP Apps für die Inline-Überprüfung/-Bearbeitung in fähigen Hosts und `link` für universelles Round-Trip zurück zur vollständigen App. CLI/Code-Editor-Clients, die keinen Iframe rendern, greifen auf den Deep Link zurück. Tools zur menschlichen Auswahl können diesem Fallback einen Einfügeschritt hinzufügen: Beispielsweise öffnet sich die Assets-Auswahl über den Fallback-Link, lässt den Benutzer Medien im Browser auswählen und kopiert dann eine Übergabezusammenfassung, die der Benutzer wieder in den Chat einfügt.
+
+### Erstklassige MCP App Bridge {#mcp-app-bridge}
+
+`embedApp()` startet vom `link`-Ziel der Aktion, erstellt eine kurzlebige Einbettungssitzung und startet die signierte App-Route. Das Claude-Web verwendet einen Single-Frame-Transplantationspfad. ChatGPT erhält einen kontrollierten Routen-Iframe mit `window.openai`-Host-ZxQ24QXZs. Alle Pfade rendern die normale React-Route. Direkt hydrierte Routen rufen `ui/update-model-context`, `ui/message`, `ui/open-link` und `ui/request-display-mode` über die Host-Brücke auf; Der ChatGPT-Pfad leitet dieselben Anforderungen über `agentNative.mcpHost.*` postMessage weiter. `embedApp({ height })` ist standardmäßig `560px` und wird auf `320-900px` geklemmt.
+
+Siehe [MCP Apps](/docs/mcp-apps) für die vollständigen Bridge-Details – Transplant vs. Controlled-Frame, Einbettungsmodi, die `ui/*`- und PostMessage-Tabellen, `embedStartUrl`-, CSP-Regeln, Einbettung der Erweiterung `srcDoc`, Höhenklemmung und den vollständigen Host-Bridge-Client API.
+
+### Generische Cross-App-Verben {#cross-app}
+
+Zusätzlich zu den Tools pro Aktion stellt der MCP-Server einen stabilen Verbsatz bereit, sodass ein externer Agent eine vorhersehbare Oberfläche hat, ohne die Aktionsnamen pro App erraten zu müssen:
+
+| Werkzeug                                           | Nebenwirkungen  | Retouren                                                                                                                              |
+| -------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_apps`                                        | keine           | Workspace-Apps + ihre URLs/Ausführungsstatus                                                                                          |
+| `open_app({ app, view?, path?, params?, embed? })` | keine           | ein Deep Link oder eine Route mit demselben Ursprung; `embed: true` rendert die vollständige App inline, sofern dies unterstützt wird |
+| `ask_app({ app, message })`                        | Agentenschleife | leitet eine Aufgabe in natürlicher Sprache an den In-App-Agenten dieser App weiter (delegiert an `ask-agent`)                         |
+| `create_workspace_app({ name, template })`         | Gerüste         | Eine neue App, die über den Workspace-Pfad gestartet wurde, plus die Ausführung von URL + Deep Link                                   |
+| `list_templates`                                   | keine           | Nur die auf der Zulassungsliste aufgeführten Vorlagen                                                                                 |
+
+`create_workspace_app` lehnt alle nicht auf der Zulassungsliste aufgeführten Vorlagen ab – die öffentliche Zulassungsliste für Vorlagen in `packages/shared-app-config/templates.ts` ist maßgeblich und CI-geschützt; ein externer Agent kann es nicht erweitern. Eine gleichnamige Vorlagenaktion überschreibt eine integrierte Aktion (Vorrang der Vorlage vor dem Kern). Deaktivieren Sie das gesamte Set mit `MCPConfig.builtinCrossAppTools: false`.
+
+Die Tool- und Ressourcenkataloge für App-Hosts sind standardmäßig kompakt – siehe [Catalog tiers](#catalog-tiers). `publicAgent.expose` bleibt die Option für sichere Lese-/Ingest-Tools außerhalb dieses kompakten Katalogs; Legen Sie `mcpApp.compactCatalog: true` nur als seltene Ausnahme für actions fest, das in der Chat-Host-Erkennung erscheinen muss.
+
+Für schnelle ChatGPT/Claude-Übergaben ist der ideale Pfad direkt: Rufen Sie die Aktion auf, die das Artefakt erstellt oder öffnet, und lassen Sie dann die MCP-App die Route starten. Eine Mail-Anfrage sollte `manage_draft` aufrufen und die tatsächliche Compose-Route rendern. Eine Dashboard-Anfrage sollte `open_app({ path, embed: true })` oder eine Dashboard-Aktion mit `mcpApp` aufrufen und die vollständige Analytics-Route rendern. Kalender, Formulare, Inhalte, Folien, Design und Clips sollten beim Entwerfen/Erstellen/Suchen dem gleichen Muster folgen actions. `list_apps` ist nützlich, wenn das Modell zwischen verfügbaren Apps wählen muss; Breites `resources/list`, vollständige Katalogerkennung oder `ask_app`-Delegierung sollten nicht der normale Weg für eine offensichtliche UI-Übergabe sein.
+
+### Tour pro App {#tour}
+
+Jede Vorlage auf der Zulassungsliste, die eine navigierbare Ressource erstellt oder auflistet, liefert einen `link`-Builder, und die aufnahmeintensiven Vorlagen liefern eine GET + `publicAgent`-Aktion, damit ein verbundener Agent den Live-Status abrufen kann:
+
+- **Mail** – `manage-draft` gibt einen `compose`-codierten Deep Link zurück; Wenn Sie darauf klicken, wird der Posteingang mit dem wiederhergestellten Entwurf in einem `compose-<id>` geöffnet. `list-emails` / `search-emails` zeigen auf eine gefilterte Posteingangsansicht.
+- **Kalender** – `manage-event-draft` gibt einen `calendarDraft` + `eventDraftId` Deep Link zurück; Wenn Sie darauf klicken, wird im Kalender ein sichtbarer Entwurfsplatzhalter mit dem nativen Ereigniseditor zum Überprüfen/Versenden geöffnet. `create-event` gibt immer noch `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })` zurück; Der Klick landet im Kalender, wobei sich das Ereignis auf sein Datum konzentriert.
+- **Analytics** – `update-dashboard` / `save-analysis` return `buildDeepLink({ app: "analytics", view: "adhoc", params: { dashboardId } })`; Der Agent erstellt über MCP ein Dashboard und gibt „Dashboard in Analytics öffnen“ zurück.
+- **Design** – `get-design-snapshot` ist die Aufnahmeaktion GET + `publicAgent`: Sie gibt den **Live**-Inhalt der Yjs-Datei plus die aufgelösten Optimierungswerte zurück, sodass der Agent mit dem optimierten Design fortfährt, nicht mit den ursprünglichen Tokens. `apply-tweaks` kehrt mit einem Editor-Link „Design öffnen“ zurück.
+- **Inhalt** – `pull-document` ist die Aufnahmeaktion GET + `publicAgent`: Sie leitet alle offenen Live-Zusammenarbeitssitzungen zuerst an SQL weiter, sodass der externe Agent genau das aufnimmt, was der Benutzer sieht, und dann einen Deep-Link zum Dokument anzeigt.
+- **Brain** – `ask-brain` / `search-everything` geben eine zitierte Antwort sowie einen Deep-Link zum zugrunde liegenden Wissen/Erfassung zurück, sodass die Suche eines Terminalagenten direkt zurück zur Quelle in der laufenden App führt.
+
+## Authoring (für Vorlagenautoren) {#authoring}
+
+Alles oben Genannte gilt für **Endbenutzer**, die eine App verbinden und verwenden. Der Rest dieser Seite richtet sich an **Vorlagenautoren**, die eine App zu einem guten externen Agenten verknüpfen: den `link`-Builder, die optionalen MCP-Apps UI, die `/_agent-native/open`-Routeninterna und die Aufnahme von actions.
+
+### Der `link`-Builder {#link-builder}
+
+`defineAction` akzeptiert einen optionalen `link`-Builder. Wenn diese Option festgelegt ist, fügt jedes MCP/A2A-Ergebnis für dieses Tool automatisch einen Markdown-`[label →](absoluteUrl)`-Block und einen strukturierten `_meta["agent-native/openLink"] = { label, view, webUrl, desktopUrl, vscodeUrl }` hinzu. `tools/list` fügt `annotations["agent-native/producesOpenLink"]` und ein Beschreibungssuffix hinzu, damit der externe Agent weiß, dass das Tool einen öffenbaren Link liefert und ihn anzeigen sollte.
+
+Erstellen Sie URL mit `buildDeepLink(...)` – es ist die einzige Quelle der Wahrheit für das Open-Route-Format. Formatieren Sie den `/_agent-native/open` URL niemals von Hand.
+
+Echtes Beispiel – E-Mails `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",
+    };
+  },
+});
+```
+
+Liste/Suche actions zeigt auf die gleiche Weise auf eine datensatzorientierte Ansicht – z. B. Der Kalender `create-event` gibt `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })` mit der Bezeichnung `"Open event in Calendar"` zurück. Der Kalenderentwurf actions verwendet dasselbe Muster: `manage-event-draft` gibt `buildDeepLink({ app: "calendar", view: "calendar", to: "/", params: { eventDraftId, calendarDraft, date } })` mit der Bezeichnung `"Review invite in Calendar"` zurück, sodass externe Agenten einen direkten Link zur Entwurfsüberprüfung zurückgeben können, ohne zuerst das Ereignis zu erstellen.
+
+### Optionale MCP Apps UI {#mcp-apps}
+
+Actions kann eine Inline-UI-Ressource mit `mcpApp` für Hosts ankündigen, die die MCP Apps-Erweiterung unterstützen. Verwenden Sie `embedRoute({ title, openLabel, path })` als praktischen Wrapper oder weisen Sie `embedApp(...)` direkt `mcpApp.resource` zu. Jede MCP-App ist eine echte React-Route und kein separates einfaches HTML-Widget. Behalten Sie immer den `link`-Builder bei – Nur-CLI-Hosts, ältere Clients und Nicht-MCP-Apps-Hosts verwenden ihn als Fallback.
+
+Siehe [MCP Apps](/docs/mcp-apps) für den vollständigen Authoring-Leitfaden – `embedRoute` vs. `embedApp`, die `mcpApp`-Konfigurationsform, CSP, Höhe, den `sendToAgentChat()`-Einbettungspfad und Host-Bridge-Client-Helfer.
+
+### Der `link`-Vertrag {#link-contract}
+
+Der `link`-Builder ist **rein und synchron – keine E/A, keine Wartezeiten**. Es läuft nach besten Kräften: Ein Wurf, `null` oder `undefined` wird verschluckt und der Tool-Aufruf schlägt **niemals** fehl. Es werden nur die Werte `args` und `result` des Anrufs gelesen. Es darf nicht die Datenbank abfragen, den App-Status lesen oder andere actions aufrufen. Geben Sie `null` zurück, wenn nichts zu öffnen ist.
+
+`buildDeepLink({ app, view, params?, to?, compose? })` gibt den App-relativen Pfad `/_agent-native/open?app=…&view=…&<recordId>=…` zurück. Die MCP-Ebene verwandelt dies in einen absoluten Web-URL (`toAbsoluteOpenUrl`, unter Verwendung des Anforderungsursprungs), einen Desktop-`agentnative://open?…` URL (`toDesktopOpenUrl`) und eine VS-Code-Erweiterung URL (`toVsCodeOpenUrl`) für `vscode://builder.agent-native/open?url=…`; Der Markdown-Link verwendet den Desktop URL, wenn der Client `target: "desktop"` signalisiert.
+
+### Die `/_agent-native/open`-Route {#open-route}
+
+Wenn der Benutzer in einem beliebigen Browser oder in einer Inline-Webansicht auf den Link klickt, führt `GET /_agent-native/open` (`createOpenRouteHandler`, bereitgestellt durch das Kernrouten-Plugin) die folgenden Schritte aus.
+
+```an-api
+{
+  "method": "GET",
+  "path": "/_agent-native/open",
+  "summary": "Deep-link open route — focuses the browser UI on a record",
+  "description": "Resolves the browser session, writes a one-shot `navigate` application-state command scoped to that session, and 302-redirects to a safe same-origin path. Always build the URL with `buildDeepLink(...)`; never hand-format it. Can be disabled per app with `disableOpenRoute`.",
+  "auth": "Browser session via `getSession`. The auth guard bypasses this exact path; if unauthenticated it serves login HTML at the same URL, and the form reload re-enters authenticated (no `?next=` plumbing).",
+  "params": [
+    { "name": "app", "in": "query", "type": "string", "description": "Target app id (e.g. `mail`)." },
+    { "name": "view", "in": "query", "type": "string", "description": "View to focus; also folded into the `navigate` payload." },
+    { "name": "to", "in": "query", "type": "string", "description": "Optional explicit same-origin relative redirect target. Falls back to `/<view>`, then a per-template `resolveOpenPath`." },
+    { "name": "compose", "in": "query", "type": "string", "description": "base64url-encoded draft, decoded into a `compose-<id>` application-state key." },
+    { "name": "f_*", "in": "query", "type": "string", "description": "Filter params forwarded to the redirect so lists/dashboards open pre-filtered." }
+  ],
+  "responses": [
+    { "status": "302", "description": "Redirect to a safe same-origin relative path. Cross-origin, scheme-relative `//host`, and control-char redirects are rejected (open-redirect guard)." },
+    { "status": "200", "description": "Login HTML served at the same URL when the browser session is unauthenticated." }
+  ]
+}
+```
+
+1. Löst die **Browsersitzung** über `getSession` auf (der Authentifizierungsschutz umgeht den genauen Pfad `/_agent-native/open`).
+2. Wenn nicht authentifiziert, wird das konfigurierte Login HTML **zugleich URL** bereitgestellt; Der Erfolgshandler des Formulars lädt `window.location` neu und gibt die authentifizierte Route erneut ein – kein `?next=`-Klempner.
+3. Schreibt den vorhandenen einmaligen `navigate`-Anwendungsstatusbefehl (Nutzlast = jeder nicht reservierte Abfrageparameter + `view`), der auf die E-Mail der Browsersitzung mit `requestSource: "deep-link"` beschränkt ist, und dekodiert einen `compose`-Base64-URL-Entwurf in einen `compose-<id>`-Schlüssel.
+4. 302-Weiterleitung zu einem sicheren relativen Pfad gleichen Ursprungs (`to=`, sonst `/<view>`, sonst ein vorlagenbasierter `resolveOpenPath`) und Weiterleiten von `f_*`-Filterparametern, sodass Listen/Dashboards vorgefiltert geöffnet werden, bevor der Befehl `navigate` überhaupt gelöscht wird.
+
+Cross-Origin-, Schema-relative `//host`- und Control-Char-Weiterleitungen werden abgelehnt (Open-Redirect-Guard). Die Route kann per App über `disableOpenRoute` deaktiviert werden.
+
+#### Die Browser-Sitzungsidentitätsregel {#identity-rule}
+
+Der Link trägt **keinen privilegierten Status** – er besteht nur aus `view` + Datensatz-IDs + Filtern. Der auf Datensätze fokussierte `navigate`-Schreibvorgang ist auf denjenigen beschränkt, der im **Browser** angemeldet ist, niemals auf das MCP-Token des externen Agenten. So kann ein Agent, der als eine Identität authentifiziert ist, einem Benutzer einen Link übergeben, und wenn dieser Benutzer darauf klickt, wird der Datensatz geöffnet, in dem _der Benutzer_ angemeldet ist. Dadurch kann der Deep-Link sicher in einem Terminal- oder Chat-Transkript angezeigt werden. Siehe [Context Awareness](/docs/context-awareness) für den `navigate`/`application_state`-Vertrag, zu dem diese Brücke geschaltet wird.
+
+### actions aufnehmen {#ingest}
+
+Eine Aktion, die ein externer Agent liest, um den Live-App-Status in seinen eigenen Kontext zu ziehen, muss sein:
+
+```ts
+export default defineAction({
+  description: "…",
+  schema: z.object({ id: z.string() }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async ({ id }) => {
+    /* read LIVE state, not the stale DB snapshot column */
+  },
+});
+```
+
+`GET` + `readOnly` hält die Aktion ohne Nebenwirkungen und außerhalb des Bildschirmaktualisierungs-Änderungsereignisses. `publicAgent` ist das **explizite Opt-in** – eine öffentliche Webroute impliziert niemals eine öffentliche MCP/A2A-Exposition; siehe [Actions](/docs/actions). Design/Inhaltsaufnahme actions MUST liest den **Live**-Status (das Yjs-Gemeinschaftsdokument, nicht die veraltete DB-Snapshot-Spalte), damit der externe Agent sieht, was der Benutzer tatsächlich auf dem Bildschirm hat. `pull-document` von Content leitet alle offenen Live-Zusammenarbeitssitzungen zuerst an SQL weiter. Der `get-design-snapshot` von design gibt den Inhalt der Live-Yjs-Datei sowie die vom Benutzer aufgelösten Optimierungswerte zurück.
+
+## Erweitert: lokale Entwicklung und manuelle Einrichtung {#advanced}
+
+Der oben gehostete `connect`-Flow ist der empfohlene Pfad. Die folgenden Optionen gelten für die lokale Entwicklung und manuell erstellte Setups.
+
+### Lokale Entwicklung {#local-dev}
+
+Führen Sie Ihre App lokal aus (`pnpm dev` / `npx @agent-native/core@latest dev`) und richten Sie dann mit einem Befehl einen lokalen Agenten darauf:
+
+```bash
+npx @agent-native/core@latest mcp install --client claude-code|claude-code-cli|codex|cowork \
+  [--app <id>] [--scope user|project]
+```
+
+Es stellt ein Token bereit (ein zufälliges `ACCESS_TOKEN` im Arbeitsbereich `.env` für lokale Entwickler oder ein signiertes JWT, wenn es einen gehosteten Ursprung erkennt) und schreibt einen idempotenten stdio-Servereintrag:
+
+- **claude-code / claude-code-cli** – ein `mcpServers`-Eintrag in `.mcp.json` (Projektumfang, Standard) oder `~/.claude.json` (`--scope user`).
+- **cowork** – die gleiche Form des Claude-Codes JSON in `~/.cowork/mcp.json`.
+- **codex** – ein `[mcp_servers.<name>]`-Block in `~/.codex/config.toml`.
+
+Der Eintrag führt `npx @agent-native/core@latest mcp serve --app <id>` aus, der standardmäßig ein **Thin-Stdio-Proxy** für den `/_agent-native/mcp` der laufenden lokalen App ist – daher bleiben die Live-Action-Registrierung HMR und korrekte Deep-Links die einzige Quelle der Wahrheit. Übergeben Sie stattdessen `--standalone`, um die Registrierung im Prozess zu erstellen. Wenn `npx @agent-native/core@latest mcp install` einen gehosteten Ursprung erkennt (einen nicht-lokalen Host `APP_URL` / `BETTER_AUTH_URL` / `AGENT_NATIVE_MCP_URL` im Arbeitsbereich `.env`), schreibt es einen `http`-Clienteintrag, der auf `<origin>/_agent-native/mcp` zeigt, mit einem `Bearer` JWT anstelle eines stdio-Eintrags.
+
+Companion-Unterbefehle:
+
+| Befehl                                                     | Was es tut                                                                                     |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `npx @agent-native/core@latest mcp serve [--app <id>]`     | Führen Sie den MCP stdio-Transport aus (welche Client-Konfigurationen entstehen).              |
+| `npx @agent-native/core@latest mcp install --client <c>`   | Stellen Sie ein Token bereit und schreiben Sie die MCP-Konfiguration des Clients (idempotent). |
+| `npx @agent-native/core@latest mcp uninstall --client <c>` | Entfernen Sie den benannten MCP-Eintrag aus der Konfiguration eines Clients (idempotent).      |
+| `npx @agent-native/core@latest mcp status`                 | Aufgelöste MCP URL/Port-, Token-Status- und Client-Einträge anzeigen.                          |
+| `npx @agent-native/core@latest mcp token [--rotate]`       | Drucken (oder drehen) Sie das lokale `ACCESS_TOKEN` im Arbeitsbereich `.env`.                  |
+
+Starten Sie den Client nach `install` neu, damit er den neuen MCP-Server aufnimmt.
+
+### Manueller Eintrag `.mcp.json` HTTP {#manual-entry}
+
+Sie können die MCP-Clientkonfiguration auch manuell für jeden bereitgestellten Endpunkt mit einem Token schreiben, den Sie selbst bereitstellen (einen `ACCESS_TOKEN` oder einen mit `A2A_SECRET` signierten JWT, der den `sub` + `org_domain` des Aufrufers trägt, sodass Tool-Ausführungen mandantenabhängig bleiben):
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "analytics": {
+      "type": "http",
+      "url": "https://analytics.agent-native.com/_agent-native/mcp",
+      "headers": { "Authorization": "Bearer <ACCESS_TOKEN-or-JWT>" },
+    },
+  },
+}
+```
+
+Dies ist das nicht verwaltete Äquivalent dessen, was `connect` für Sie schreibt. Die vollständige Authentifizierungs-Env-Var-Matrix finden Sie unter [MCP Protocol](/docs/mcp-protocol).
+
+### Entwicklung vs. Produktionswerkzeugoberfläche {#dev-vs-prod}
+
+In einfacher lokaler Entwicklung (`NODE_ENV=development` und `AGENT_MODE !== "production"`) stellt der MCP `tools/list` absichtlich nur die generischen integrierten Funktionen plus actions mit `publicAgent.requiresAuth === false` zur Verfügung – der pro App aufgenommene actions (`requiresAuth: true`) und der mutierende actions (kein `publicAgent`) werden herausgefiltert (`filterPublicAgentActions`). Der kompakte Katalog ist die Standardeinstellung für jeden Anrufer nach der Authentifizierung – Standard-/Code-Clients, die den `agent-native`-Proxy verwenden, den lokalen CLI und Remote-HTTP-Anrufer im Chat-Stil gleichermaßen –, sodass ChatGPT/Claude (oder ein beliebiger Client) keinen riesigen vollständigen Aktionskatalog in die Konversation einbinden kann. Der vollständige Entwicklerkatalog wird nur mit expliziter Einwilligung bereitgestellt (`--full-catalog`-Token oder `AGENT_NATIVE_MCP_FULL_CATALOG=1`); Mit `tool-search` bleibt jedes Werkzeug in der Zwischenzeit erreichbar.
+
+### Erstanbieter-Apps zwischen Produktion und Entwicklung wechseln {#dev-switch}
+
+Wenn Sie bereits gehostete Erstanbieter-Apps verbunden haben und lokale Framework-Änderungen über `pnpm dev:lazy` testen möchten, verwenden Sie den Entwickler-Umschalter:
+
+```bash
+pnpm dev:lazy -- --apps mail,calendar,analytics
+
+npx @agent-native/core@latest connect dev --apps mail,calendar,analytics --client codex
+```
+
+`connect dev` schreibt die gleichen stabilen MCP-Servernamen (`agent-native-mail`, `agent-native-calendar` usw.) in das lokale Dev-Lazy-Gateway um, sodass sich die Toolnamen nicht ändern. Es sichert die aktuellen Produktionseinträge in `~/.agent-native/connect-profiles.json`, bevor Entwicklungseinträge geschrieben werden. Das Standard-Gateway ist `http://127.0.0.1:8080`; Verwenden Sie `--gateway <url>` oder `--port <n>`, wenn Ihr Gateway umgezogen ist.
+
+Zurückschalten mit:
+
+```bash
+npx @agent-native/core@latest connect prod --apps mail,calendar,analytics --client codex
+```
+
+Wenn `connect dev` Ihre lokale Eigentümeridentität nicht aus einem vorhandenen verbundenen JWT ableiten kann, übergeben Sie `--owner-email you@example.com`. Dadurch bleiben lokale Entwicklungstools auf der vollständig authentifizierten MCP-Oberfläche statt auf der spärlichen, nicht authentifizierten Entwicklungsoberfläche.
+
+## Funktionsweise und Sicherheit {#how-it-works}
+
+Der Standard-OAuth-Pfad stellt niemals Token für MCP-Apps bereit: Der Host speichert OAuth-Zugriffs-/Aktualisierungstoken und vermittelt Toolaufrufe und `resources/read` über die authentifizierte MCP-Verbindung. Eingebettete Iframes empfangen App-Daten und Tool-Ergebnisse, keine Trägergeheimnisse.
+
+Vollständige App-Einbettungen vermeiden außerdem die Übergabe des MCP-Bearer-Tokens an den Browser. Der MCP-Anrufer prägt ein einmaliges Einbettungsticket in SQL; Die Iframe-Startroute verbraucht es und setzt ein kurzlebiges, iframe-sicheres Browser-Sitzungscookie. Der Ziel-URL trägt einen temporären `__an_embed_token`-Abfrageparameter nur so lange, dass der Client ihn erfassen, aus der Adressleiste entfernen und an `fetch`-Aufrufe gleichen Ursprungs anhängen kann, wenn Cookies von Drittanbietern blockiert sind. Einbettungssitzungen sind routenbezogen; App-Abrufe umfassen das aktuelle eingebettete Ziel und der Server lehnt die Wiederverwendung von Token außerhalb der geprägten Route ab. App-Seiten geben absichtlich kein `X-Frame-Options` oder CSP `frame-ancestors` aus, sodass Builder-, Design- und MCP-App-Hosts sie iframen können. Browser-Iframe-Navigationen aktivieren bei Bedarf auch COEP/CORP für isolierte Cross-Origin-Hosts.
+
+Der als Fallback gehostete `connect`-Fluss kopiert niemals das gemeinsame Geheimnis der Bereitstellung. Stattdessen:
+
+- Eine angemeldete Browsersitzung prägt ein **pro Benutzer gültiges, widerrufbares** Token – ein `A2A_SECRET`-signiertes JWT mit dem `sub` + `org_domain` des Aufrufers und einem eindeutigen `jti`, sodass jede Tool-Ausführung über `runWithRequestContext` mandantenabhängig bleibt.
+- Der vorhandene `/_agent-native/mcp`-Endpunkt akzeptiert dieses Token wie jeder andere Träger (siehe [MCP Protocol](/docs/mcp-protocol)) – kein neuer Endpunkt, kein neuer Transport.
+- Auf der gleichen Connect-Seite werden alle von Ihnen geprägten Token aufgelistet und Sie können diese bis `jti` **widerrufen**. Behandeln Sie sie wie persönliche Zugriffstoken: eines pro Agent-Client, widerrufen, wenn eine Maschine außer Betrieb genommen wird.
+- Der Deep Link, den der Agent zurückgibt, weist keinen privilegierten Status auf. Der datensatzfokussierende `navigate`-Schreibvorgang ist immer auf die **Browsersitzung** beschränkt, niemals auf das Token des Agenten – ein Link kann also sicher in ein Terminal oder ein Chat-Transkript eingefügt werden.
+
+## Tun/Nicht {#do-dont}
+
+**Tun**
+
+- Verbinden Sie Ihren eigenen Agenten mit Dispatch mit `npx @agent-native/core@latest connect https://dispatch.agent-native.com`; Verwenden Sie eine direkte App URL nur, wenn Sie eine isolierte App wünschen.
+- Fügen Sie einen `link`-Builder zu jeder Aktion hinzu, die eine navigierbare Ressource (Entwurf, Ereignis, Dashboard, Dokument) erstellt oder auflistet.
+- Erstellen Sie den URL mit `buildDeepLink(...)` – der Single Source of Truth für das Open-Route-Format.
+- `link` rein und synchron halten; Geben Sie `null` zurück, wenn nichts zu öffnen ist.
+- Führen Sie die Aufnahme von actions GET + `readOnly` + `publicAgent` durch den externen Agent durch und lesen Sie den Live-Status (Yjs), nicht die veraltete DB-Spalte.
+- Lassen Sie die offene Route die Browsersitzung auflösen; Übergeben Sie Datensatz-IDs als Deep-Link-Parameter und lassen Sie sie vom UI über den abgefragten `navigate`-Befehl fokussieren.
+- Widerrufen eines geprägten Verbindungstokens durch `jti`, wenn ein Agent-Client außer Betrieb genommen wird.
+- Testen Sie MCP-Apps mit den leichten Vorrichtungen rund um `embedApp()` und
+  `McpAppRenderer`; Sie umfassen CSP, Hostkontext, App-Start und Bridge
+  Nachrichtenverhalten, ohne dass ein echter externer Host erforderlich ist.
+- Wenn Sie ChatGPT oder Claude Web validieren, lösen Sie nach der Shell einen neuen Tool-Aufruf aus
+  Änderungen und Messung des sichtbaren Iframes. Zuvor gerenderte Frames im
+  In derselben Konversation wird möglicherweise weiterhin die zwischengespeicherte Höhe oder das Startverhalten angezeigt.
+- Halten Sie die App-Host-Kataloge ChatGPT/Claude kompakt. Verwenden Sie Versand und
+  `open_app({ embed: true })` für vollständige App-Vorschauen; Markieren Sie nur eine bestimmte
+  Aktion `mcpApp.compactCatalog: true`, wenn sie direkt im
+  Kompakte Host-Erkennungsoberfläche.
+
+**Nicht**
+
+- Kopieren Sie den freigegebenen `ACCESS_TOKEN`/`A2A_SECRET` einer Bereitstellung in eine Client-Konfiguration, wenn `connect` stattdessen ein widerrufliches Token pro Benutzer prägen kann.
+- Formatieren Sie `/_agent-native/open` URL von Hand – gehen Sie immer über `buildDeepLink`.
+- Führen Sie E/A, Wartevorgänge, DB-Lesevorgänge oder App-Status-Lesevorgänge innerhalb eines `link`-Builders aus.
+- Erweitern Sie den `navigate`-Schreibzugriff auf das Agent-Token oder übergeben Sie den privilegierten Status über den Deep Link – es handelt sich um einen reinen Zeiger.
+- Erfinden Sie einen neuen Navigationsmechanismus; Brücke zum bestehenden `navigate` / `application_state`-Vertrag.
+- Erweitern Sie die Zulassungsliste für öffentliche Vorlagen, wenn Sie eine App von einem externen Agenten aufbauen – die Zulassungsliste ist maßgeblich und geschützt.
+
+## Verwandt {#related}
+
+- [MCP Apps](/docs/mcp-apps) – Erstellen von MCP-Apps, UIs, der Embed-Bridge und der Host-Bridge API.
+- [MCP Protocol](/docs/mcp-protocol) – der automatisch gemountete MCP-Server und das `ask-agent`-Meta-Tool.
+- [MCP Clients](/docs/mcp-clients) – die symmetrische Richtung: Ihre App nutzt lokale/remote MCP-Server.
+- [A2A Protocol](/docs/a2a-protocol) – das `ask-agent`-Metatool und JSON-RPC-Peer-Aufrufe.
+- [Actions](/docs/actions) – Definition von actions, `publicAgent`, GET / `readOnly`.
+- [Context Awareness](/docs/context-awareness) – der `navigate` / `application_state` vertraglich die offenen Routenbrücken an.