@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/pt-BR/external-agents.md

@@ -0,0 +1,619 @@
+---
+title: "Agentes Externos: Claude, ChatGPT, Codex, Cursor, Cowork"
+description: "Conecte Claude, ChatGPT, Codex, Cursor, Claude Cowork ou qualquer host compatível com MCP a um aplicativo nativo de agente hospedado e, em seguida, faça o retorno dos artefatos ao UI em execução com aplicativos MCP e links diretos."
+search: "Claude ChatGPT Claude Código Codex Cursor Claude Cowork MCP Aplicativos agente nativo conectar ferramentas de agente local agentes externos"
+---
+
+# Agentes Externos
+
+**Esta página: conecte um agente externo ou host MCP ao seu aplicativo.** Use-a quando Claude, ChatGPT, Codex, Cursor, Claude Cowork ou outro host compatível com MCP deve conduzir um aplicativo nativo de agente hospedado e retornar o resultado de volta ao UI em execução.
+
+| Se você quiser…                                                                                  | Ler                                |
+| ------------------------------------------------------------------------------------------------ | ---------------------------------- |
+| Conecte um agente/host externo ao seu aplicativo                                                 | **Esta página** — Agentes externos |
+| Dê mais ferramentas ao seu agente (consuma outros servidores MCP)                                | [MCP Clients](/docs/mcp-clients)   |
+| Crie UIs inline que sejam renderizados em Claude/ChatGPT                                         | [MCP Apps](/docs/mcp-apps)         |
+| Referência do servidor MCP de nível inferior (autenticação, ferramentas, montagem personalizada) | [MCP Protocol](/docs/mcp-protocol) |
+
+Um aplicativo nativo do agente pode ser acessado por qualquer host compatível com MCP — Claude, Claude Desktop, Claude Code, ChatGPT aplicativos MCP personalizados, Codex, Cursor, Claude Cowork, VS Code GitHub Copilot, Goose, Postman, MCPJam e futuros clientes que implementarem o padrão. Os agentes externos são ótimos na produção de artefatos (um rascunho, um evento, um painel), mas geralmente residem em um terminal ou outro aplicativo. Sem ponte, o usuário pega uma parede de JSON e tem que ir procurar a coisa.
+
+A ponte de agente externo fecha o loop. Primeiro, você conecta seu próprio agente a um aplicativo **hospedado**, colando o MCP URL remoto do aplicativo em um host de bate-papo como Claude ou ChatGPT ou executando o fluxo do desenvolvedor CLI para agentes de codificação locais. Em seguida, o agente faz o trabalho no MCP e entrega ao usuário um **MCP App** UI inline em hosts compatíveis ou um único link **"Abrir em <app> →"** que abre o aplicativo real focado exatamente no que foi produzido. Ele reutiliza o contrato `navigate`/`application_state` existente, o UI já drena a cada 2s (consulte [Context Awareness](/docs/context-awareness)) — não há segundo mecanismo de navegação.
+
+```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}"
+}
+```
+
+A regra de identidade é a dobradiça de segurança: o link é apenas `view` + ids de registro + filtros, e a gravação `navigate` com foco em registro tem como escopo quem está conectado ao **navegador** — nunca o token MCP do agente externo. É por isso que é seguro colar o link em um terminal ou transcrição de bate-papo.
+
+## Qual caminho de agente você precisa? {#which-agent-path}
+
+- **Host MCP externo:** use esta página quando Claude, ChatGPT, Codex, Cursor, OpenCode, GitHub Copilot / VS Code ou outro host compatível com MCP precisar chamar seu aplicativo nativo do agente hospedado.
+- **Seu próprio tempo de execução por trás do bate-papo Agent-Native:** veja [Agent Surfaces](/docs/agent-surfaces#byo-agent) e [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes) quando um agente criado com outra estrutura deve alimentar o `<AssistantChat runtime={...}>`.
+- **Seu aplicativo consome ferramentas MCP:** consulte [MCP Clients](/docs/mcp-clients) quando um aplicativo nativo do agente precisa chamar ferramentas expostas por outro servidor MCP.
+- **Outro aplicativo ou agente via A2A:** use [Agent Mentions](/docs/agent-mentions) e [A2A](/docs/a2a-protocol) quando aplicativos nativos de agente precisarem descobrir e delegar uns aos outros.
+- **Subagentes personalizados locais:** use [Workspace](/docs/workspace) quando desejar perfis de agentes personalizados dentro do próprio espaço de trabalho nativo do agente.
+
+## Configuração fácil {#easy-setup}
+
+Adicione um conector MCP remoto ao host onde você deseja usar Agent-Native.
+
+Para trabalho em espaço de trabalho ou entre aplicativos, use Dispatch:
+
+```text
+https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+Dispatch é o gateway único para Mail, Calendar, Analytics, Brain e seu
+aplicativos de espaço de trabalho. Na página **Agentes** do Dispatch, escolha se o gateway pode
+alcançar todos os aplicativos ou apenas aplicativos selecionados. O host conectado então obtém
+`list_apps`, `ask_app` e `open_app`, filtrados para esse conjunto concedido.
+
+Para um aplicativo intencionalmente isolado, use-o diretamente:
+
+```text
+https://mail.agent-native.com/_agent-native/mcp
+https://<your-app>.agent-native.com/_agent-native/mcp
+```
+
+Todo aplicativo hospedado também tem uma página auxiliar em
+`https://<app>/_agent-native/mcp/connect` com o URL copiável e
+guias específicas do host para Claude, ChatGPT, Cursor, Código Claude, Codex e Outros.
+
+### Claude e ChatGPT OAuth {#oauth}
+
+Claude / Claude Desktop: adicione um conector personalizado, cole o MCP URL, clique em
+**Conecte**, faça login com sua conta Agent-Native, aprove os escopos MCP,
+e habilite o conector em um chat. O código Claude usa o mesmo URL: adicione-o como
+servidor HTTP MCP remoto, execute `/mcp` e escolha **Autenticar**.
+
+ChatGPT: use um espaço de trabalho onde estejam conectores MCP personalizados ou aplicativos em modo de desenvolvedor
+ativado, crie um conector/aplicativo personalizado, cole o mesmo MCP URL, escolha OAuth,
+ferramentas de verificação/descoberta, login com Agent-Native, aprovação dos escopos e ativação
+o conector em um bate-papo.
+
+As concessões OAuth são por host e por usuário. O host armazena os tokens e
+media chamadas de ferramentas/recursos, para que as visualizações do aplicativo MCP in-line nunca recebam dados brutos
+Tokens OAuth. ChatGPT pode manter uma ferramenta de conector revisada ou publicada
+instantâneo até que você o atualize/revise novamente, então verifique novamente o conector após MCP
+alterações nos metadados da ferramenta ou do aplicativo MCP. Se você ainda tiver conectores por aplicativo antigos
+ativado junto com Dispatch, atualize ou reconecte cada conector obsoleto; atualizando
+O Dispatch não reescreve o calendário/correio/etc em cache de ChatGPT ou Claude.
+instantâneos. Os escopos são:
+
+| Escopo      | O que ele permite                                                |
+| ----------- | ---------------------------------------------------------------- |
+| `mcp:read`  | Ferramentas somente leitura e descoberta de ferramentas/recursos |
+| `mcp:write` | Esboço, atualização e outras mutações do actions                 |
+| `mcp:apps`  | Aplicativos MCP inline, gráficos, painéis, rascunhos e UIs       |
+
+Cursor, Goose, Postman, MCPJam e VS Code GitHub Copilot usam o mesmo controle remoto
+MCP URL por meio de seus próprios servidores MCP UIs quando sua compilação suporta OAuth remoto
+Servidores MCP.
+
+### Prompt de teste rápido {#quick-test}
+
+Depois de conectar, tente um destes:
+
+```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.
+```
+
+Em hosts que suportam aplicativos MCP, o Analytics pode renderizar painéis reais e rotas de análise inline, e o Mail pode renderizar a composição real UI inline para revisão de rascunho. Em hosts que não renderizam aplicativos MCP, a mesma chamada de ferramenta ainda retorna um link direto, como **Abrir rascunho no Mail →** ou **Abrir painel no Analytics →**.
+
+## Configuração avançada: agentes locais {#connect}
+
+Use este fluxo para clientes de agentes locais em sua máquina — Código Claude, Código Claude CLI, Codex, Claude Cowork, Cursor, OpenCode e GitHub Copilot/VS Code. Cursor e outros clientes nativos de OAuth também podem usar o fluxo paste-URL acima quando seu UI suporta MCP OAuth remoto.
+
+Execute o comando de conexão por meio de npm:
+
+```bash
+npx @agent-native/core@latest connect https://dispatch.agent-native.com
+```
+
+O comando pergunta quais clientes do agente local devem receber a configuração MCP. Todos os clientes são pré-selecionados na primeira vez; depois de escolher, a seleção é salva em `~/.agent-native/connect.json` para que a próxima execução possa reutilizá-la com Enter ou você possa editar os itens marcados.
+
+Para código Claude, código Claude CLI, Cursor, OpenCode e GitHub Copilot / VS Code, `connect` grava uma entrada HTTP MCP remota padrão sem cabeçalhos estáticos. Reinicie o cliente e autentique-se em seu MCP UI quando solicitado. Para Codex e Claude Cowork, `connect` usa o fluxo de código de dispositivo de compatibilidade: ele abre seu navegador no aplicativo, você clica em **Autorizar** uma vez e o comando grava uma entrada de token de portador com escopo definido. Se você escolher uma combinação de clientes, você fará as duas coisas.
+
+Mantenha o comando `connect` em execução até que a aprovação do navegador seja concluída. Se o
+o processo de espera é interrompido antecipadamente, a aprovação pode ser bem-sucedida no navegador, mas
+a configuração do cliente local não receberá o token.
+
+Se você conectou anteriormente o código Claude por meio do antigo fluxo de token de portador, basta executar o mesmo comando `npx @agent-native/core@latest connect ... --client claude-code` novamente. O CLI substitui os cabeçalhos `Authorization` herdados pela entrada OAuth somente URL e solicita que você se autentique novamente a partir de `/mcp`.
+
+| Cliente local                     | Configuração escrita por `connect`                         | Fluxo de autenticação                          |
+| --------------------------------- | ---------------------------------------------------------- | ---------------------------------------------- |
+| Código Claude / Código Claude CLI | `.mcp.json` ou `~/.claude.json`, dependendo de `--scope`   | MCP OAuth remoto padrão em `/mcp` UI de Claude |
+| Cursor                            | `.cursor/mcp.json` ou `~/.cursor/mcp.json`                 | MCP OAuth remoto padrão no MCP UI do Cursor    |
+| OpenCode                          | `opencode.json` ou `~/.config/opencode/opencode.json`      | MCP OAuth remoto padrão no MCP UI do OpenCode  |
+| Copiloto GitHub / Código VS       | Configuração do usuário `.vscode/mcp.json` ou VS Code MCP  | MCP OAuth remoto padrão no MCP UI do VS Code   |
+| Codex                             | `$CODEX_HOME/config.toml` ou `~/.codex/config.toml`        | Backup de portador autorizado pelo navegador   |
+| Cowork Claude                     | `~/.cowork/mcp.json` usando o formato do código Claude MCP | Backup de portador autorizado pelo navegador   |
+
+Reinicie o cliente agente após conectar-se para que ele pegue o novo servidor MCP; Os clientes nativos do OAuth podem então solicitar que você se autentique a partir do MCP UI.
+
+Ao solucionar problemas de configuração MCP local, edite `Authorization`, `http_headers`,
+e valores de token antes de compartilhar logs. Não use curl bruto como substituto de um
+host sessão MCP; após a conexão, use as ferramentas expostas ao host ou reinicie o
+cliente se o novo servidor ainda não estiver visível.
+
+Use `--client codex` (ou `--client claude-code`, `--client claude-code-cli`, `--client cursor`, `--client opencode`, `--client github-copilot`, `--client cowork`, `--client all`) para ignorar o seletor de scripts ou instalações únicas.
+
+O aplicativo original skills instala as instruções e o conector MCP hospedado junto com o Agent Native CLI:
+
+```bash
+npx @agent-native/core@latest skills add assets              # alias: image-generation
+```
+
+O caminho Vercel/open Skills CLI também está disponível quando você deseja apenas portátil
+instruções:
+
+```bash
+npx skills@latest add BuilderIO/agent-native --skill assets
+```
+
+O `skills` CLI bruto instala apenas arquivos `SKILL.md`; clientes MCP locais ainda
+precisa de um conector como `npx @agent-native/core@latest connect https://assets.agent-native.com`.
+
+| Habilidade | Alias              | Para                    |
+| ---------- | ------------------ | ----------------------- |
+| `assets`   | `image-generation` | geração de imagem/vídeo |
+
+A seleção de cliente padrão é composta por todos os clientes locais suportados; adicione `--client codex`, `--client claude-code` ou outro alvo específico para restringir a configuração. Hosts inline (bate-papo principal ChatGPT, Claude.ai, Claude Desktop) renderizam a grade do seletor/variante no bate-papo; Hosts CLI/somente link (Codex, Claude Code, guia "Código" do Claude Desktop) retornam um link "Abrir em… →" onde o usuário escolhe no navegador e cola um resumo de transferência de volta.
+
+Quando você realmente precisa de um aplicativo isolado em vez do gateway do espaço de trabalho do Dispatch,
+execute o mesmo comando com o host desse aplicativo:
+
+```bash
+npx @agent-native/core@latest connect https://mail.agent-native.com
+```
+
+`connect --all` ainda existe para configurações legadas de cliente por aplicativo, mas é novo
+as configurações do espaço de trabalho devem preferir o conector Dispatch único.
+
+A conexão é **por usuário, com escopo definido e revogável**. No caminho OAuth, o host armazena os tokens após a autenticação `/mcp`; no caminho alternativo, a sessão do navegador com a qual você autorizou é a identidade com a qual o agente atua. Nada expõe o segredo compartilhado da implantação.
+
+### Reautenticando após um 401 {#reconnect}
+
+Uma vez conectado, a autenticação deve persistir por longo prazo – os tokens de acesso duram 30 dias por padrão (substituir por `MCP_OAUTH_ACCESS_TOKEN_TTL` no servidor, por exemplo, `7d` ou `12h`) com uma janela de atualização deslizante de 365 dias, portanto, 401s aleatórios devem ser raros. Quando isso acontecer, use o comando leve de reconexão em vez de reinstalar:
+
+```bash
+npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex
+```
+
+`reconnect` encontra qualquer entrada de configuração MCP cujo URL termina em `/_agent-native/mcp` para o host fornecido e o cliente selecionado (correspondente a URL, independentemente do nome do conector) e, em seguida, atualiza ou substitui o material de autenticação sem tocar no skills instalado ou executar novamente o fluxo de instalação completo. Passe o aplicativo base URL (por exemplo, `https://plan.agent-native.com`) — o sufixo `/_agent-native/mcp` é inferido. A autenticação e o carregamento da ferramenta são por cliente, portanto, reinicie/recarregue esse cliente posteriormente; Codex precisa de uma nova sessão antes que as ferramentas recém-carregadas apareçam.
+
+No código Claude, o caminho UI equivalente é: execute `/mcp` e escolha **Autenticar** (ou **Reconectar**) para o conector relevante.
+
+Nunca reinstale a habilidade do zero apenas para consertar um 401 — `reconnect` é a ferramenta certa.
+
+### Conectar substituto de página {#connect-page-fallback}
+
+Para clientes MCP que não podem adicionar um OAuth URL remoto diretamente, abra o aplicativo em seu navegador e use seu recurso **Connect** (servido em `https://<app>/_agent-native/mcp/connect`). Enquanto estiver logado, clique em **Conectar/Autorizar**. A página fornece um link direto de um clique que configura um agente detectado ou um bloco `.mcp.json` pronto para colar:
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "mail": {
+      "type": "http",
+      "url": "https://mail.agent-native.com/_agent-native/mcp",
+      "headers": { "Authorization": "Bearer <minted-token>" },
+    },
+  },
+}
+```
+
+Reinicie o cliente do agente após conectar-se para que ele receba o novo servidor MCP.
+
+Use este bloco de portador manual para clientes MCP que não podem concluir o fluxo remoto padrão MCP OAuth ou para depuração única quando você deseja colar explicitamente um token.
+
+### Remoto padrão MCP OAuth {#standard-oauth}
+
+Os aplicativos nativos do agente hospedado também suportam o fluxo remoto padrão MCP OAuth. Para clientes que implementam MCP OAuth, adicione o servidor HTTP remoto URL sem cabeçalhos estáticos:
+
+```bash
+claude mcp add --transport http agent-native \
+  https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+Esta é a mesma entrada somente URL que `npx @agent-native/core@latest connect https://dispatch.agent-native.com --client claude-code` escreve para você. Em seguida, execute `/mcp` no código Claude e escolha **Autenticar**. O cliente descobre a autenticação do desafio `401 WWW-Authenticate` do servidor MCP, busca `/.well-known/oauth-protected-resource` e `/.well-known/oauth-authorization-server`, registra dinamicamente um cliente OAuth público, abre a página de autorização do aplicativo e armazena o token resultante com segurança. Os conectores de modo de desenvolvedor ChatGPT usam o mesmo servidor URL:
+
+```text
+https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+O fluxo OAuth é código de autorização + PKCE com rotação de token de atualização. Os tokens de acesso são vinculados ao público ao recurso MCP exato URL e carregam a identidade assinada do usuário/organização, portanto, as chamadas de ferramenta, `resources/read` e `tools/call` iniciado por iframe do aplicativo MCP são executados por meio do mesmo escopo de locatário `runWithRequestContext` que o caminho JWT criado por conexão existente. O iframe nunca recebe tokens OAuth brutos; o host medeia as chamadas por meio da conexão MCP autenticada.
+
+Os escopos atuais são:
+
+| Escopo      | Permite                                                                                     |
+| ----------- | ------------------------------------------------------------------------------------------- |
+| `mcp:read`  | MCP somente leitura actions e descoberta comum de ferramentas/recursos                      |
+| `mcp:write` | mutação de actions e da meta-ferramenta `ask-agent`                                         |
+| `mcp:apps`  | Listagem/leitura de recursos de aplicativos MCP e renderização UI in-line quando compatível |
+
+Quando o cliente não solicita nenhum escopo explícito, o aplicativo concede todos os três para que o conector se comporte como o fluxo do Connect autorizado pelo navegador. Mantenha a página Connect do token de portador e o substituto `npx @agent-native/core@latest connect --token <token>` para desenvolvedores locais, hosts substitutos e clientes onde você precisa de um bloco de configuração pronto para colar.
+
+## Níveis de catálogo {#catalog-tiers}
+
+Esta é a explicação canônica das camadas do catálogo MCP — links para outras páginas aqui.
+
+O servidor MCP fornece um **catálogo compacto por padrão para cada chamador** — conectores hospedados (ChatGPT, Claude), clientes de código (código Claude, Cursor, Codex) e o proxy local CLI/stdio. A superfície de ação completa é veiculada apenas com aceitação explícita. O catálogo nunca é inferido do nome do cliente ou do agente do usuário.
+
+```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}"
+}
+```
+
+### Camada compacta/conector (padrão) {#connector-tier}
+
+Por padrão, cada agente conectado vê um catálogo pequeno e selecionado (cerca de 20 a 30 ferramentas versus cerca de 105 na superfície completa):
+
+- **Aplicativo declarado por modelo actions** — a lista de permissões segura no nível do aplicativo. Para planos `create-visual-plan`, `get-visual-plan`, `share-resource`, `navigate`, `tool-search` e similares.
+- **Ferramentas integradas para vários aplicativos** — `list_apps`, `open_app`, `ask_app`, `create_embed_session`.
+- **`tool-search`** está sempre presente, então qualquer coisa fora da lista permanece acessível sob demanda (veja abaixo).
+
+Ferramentas fora da lista — por exemplo `db-exec`, `seed-*`, o conjunto de extensões, ferramentas de sessão de navegador e ferramentas de raio X de contexto — não são anunciadas e as chamadas para elas são rejeitadas com "Ferramenta desconhecida", a menos que o chamador tenha optado pelo catálogo completo. Isso mantém pequena a janela de contexto de cada agente conectado e remove armas de fogo que são seguras apenas para desenvolvimento local de locatário único. A camada do conector fica ativa **sempre que um modelo declara um `connectorCatalog`** — ele não está protegido por uma variável de ambiente.
+
+`tool-search` funciona de duas maneiras: chame-o com **sem consulta** para obter o menu completo de nomes de ferramentas mais descrições de uma linha (barato, sem esquemas) ou com uma consulta para correspondências classificadas com resumos de parâmetros. É assim que um cliente compactado descobre e carrega qualquer ferramenta de superfície completa quando precisa.
+
+### Nível completo (somente aceitação explícita) {#full-tier}
+
+A superfície de ação completa com cerca de 105 ferramentas é veiculada apenas com aceitação explícita, de duas maneiras:
+
+- **Por token** — cunhado com `--full-catalog`, que incorpora uma declaração `catalog_scope: "full"` no JWT. As solicitações subsequentes ignoram o filtro compacto desse token:
+
+  ```bash
+  npx @agent-native/core@latest connect https://plan.agent-native.com --client codex --full-catalog
+  ```
+
+- **Por implantação** — configure `AGENT_NATIVE_MCP_FULL_CATALOG=1` (ambiente de processo do servidor) para fornecer a superfície completa a todos os chamadores. Use-o para instâncias hospedadas de locatário único que desejam a superfície completa sem ativação por token.
+
+### Declaração de modelo {#catalog-declaration}
+
+Os modelos declaram seu catálogo de conectores nas opções `createAgentChatPlugin`:
+
+```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",
+  ],
+});
+```
+
+As ferramentas integradas para vários aplicativos (`list_apps`, `open_app`, `ask_app`,
+`create_embed_session`, `create_workspace_app`, `list_templates`) são sempre
+incluído independentemente da lista declarada.
+
+## O que você pode fazer quando estiver conectado {#what-you-can-do}
+
+Depois que seu agente estiver conectado, cada chamador receberá o catálogo compacto por padrão
+(veja [Catalog tiers](#catalog-tiers)) — clientes desenvolvedores de código/stdio, o local
+Proxy CLI e hosts de bate-papo como Claude e ChatGPT. Essa superfície é a
+aplicativo declarado por modelo actions mais os verbos integrados entre aplicativos (`list_apps`,
+`open_app`, `ask_app` e o auxiliar de incorporação somente de aplicativo). Use `ask_app` para rotear um
+tarefa em linguagem natural por meio de um agente de aplicativo (o mesmo ponto de entrada entre aplicativos
+[A2A](/docs/a2a-protocol) usa). `tool-search` está sempre presente, então qualquer ferramenta
+fora da lista compacta permanece acessível sob demanda. Para obter a ferramenta ~105 completa
+apareça antecipadamente, opte explicitamente por `--full-catalog` ou
+`AGENT_NATIVE_MCP_FULL_CATALOG=1`. Em todos os casos, peça ao agente para fazer um trabalho real
+e retorna um link direto para o aplicativo em execução:
+
+```
+> 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=…
+```
+
+Clique nesse link e o Mail será aberto com o rascunho restaurado - focado exatamente onde você, o usuário conectado, está. O agente nunca precisou conhecer sua sessão; apenas produziu o artefato.
+
+### Compatibilidade com aplicativos MCP {#mcp-apps-compatibility}
+
+Os aplicativos nativos do agente também falam a extensão oficial do MCP Apps. Quando qualquer ação
+declara `mcpApp`, o servidor anuncia
+`extensions["io.modelcontextprotocol/ui"]`, inclui `_meta.ui.resourceUri` /
+`_meta["ui/resourceUri"]` em `tools/list` e atende HTML UI até
+`resources/list` + `resources/read` como `text/html;profile=mcp-app`. Recurso
+metadados de segurança, como CSP e permissões de sandbox, residem no recurso
+entradas e conteúdo `resources/read`, não no descritor da ferramenta.
+
+Para hosts de aplicativos OAuth estilo ChatGPT/Claude, a superfície de descoberta é compacta por padrão: `tools/list` e `resources/list` anunciam o caminho de incorporação `open_app` genérico em vez de cada recurso de aplicativo MCP específico da ação (consulte [Catalog tiers](#catalog-tiers)). Marque uma ação individual com `mcpApp.compactCatalog: true` somente quando ela realmente precisar permanecer visível na descoberta do host do chat.
+
+Isso disponibiliza a mesma superfície de aplicativo para todos os hosts compatíveis, em vez de criar correções por cliente. Quais hosts renderizam aplicativos MCP inline (e a pegadinha do cache do conector após alterações de metadados) residem em [MCP Apps → Client support and caching](/docs/mcp-apps#client-support) - essa página é o único local para a matriz do cliente.
+
+Na prática, todo aplicativo nativo do agente deve ser criado com ambos: aplicativos MCP para revisão/edição in-line em hosts compatíveis e `link` para retorno universal ao aplicativo completo. Os clientes CLI/editor de código que não renderizam um iframe voltam para o link direto. As ferramentas de seleção humana podem adicionar uma etapa de colagem a esse substituto: por exemplo, o seletor de recursos abre a partir do link substituto, permite que o usuário escolha a mídia no navegador e, em seguida, copia um resumo da transferência que o usuário cola de volta no bate-papo.
+
+### Ponte de aplicativo MCP de primeira classe {#mcp-app-bridge}
+
+`embedApp()` inicia a partir do destino `link` da ação, cria uma sessão de incorporação de curta duração e inicia a rota do aplicativo assinada. A web Claude usa um caminho de transplante de quadro único; ChatGPT obtém um iframe de rota controlada com host `window.openai` APIs. Todos os caminhos renderizam a rota React normal. Rotas diretamente hidratadas chamam `ui/update-model-context`, `ui/message`, `ui/open-link` e `ui/request-display-mode` através da ponte host; o caminho ChatGPT retransmite as mesmas solicitações por meio de `agentNative.mcpHost.*` postMessage. O padrão `embedApp({ height })` é `560px` e os grampos são `320-900px`.
+
+Consulte [MCP Apps](/docs/mcp-apps) para obter todos os detalhes da ponte: transplante vs quadro controlado, modos de incorporação, tabelas `ui/*` e postMessage, `embedStartUrl`, regras CSP, incorporação de extensão `srcDoc`, fixação de altura e o cliente de ponte de host completo API.
+
+### Verbos genéricos entre aplicativos {#cross-app}
+
+Além das ferramentas por ação, o servidor MCP expõe um conjunto de verbos estável, para que um agente externo tenha uma superfície previsível sem adivinhar os nomes das ações por aplicativo:
+
+| Ferramenta                                         | Efeitos colaterais | Devoluções                                                                                                        |
+| -------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `list_apps`                                        | nenhum             | aplicativos de espaço de trabalho + seus URLs/estado de execução                                                  |
+| `open_app({ app, view?, path?, params?, embed? })` | nenhum             | um link direto ou rota de mesma origem; `embed: true` renderiza o aplicativo completo in-line onde houver suporte |
+| `ask_app({ app, message })`                        | loop de agente     | encaminha uma tarefa em linguagem natural para o agente no aplicativo desse aplicativo (delega para `ask-agent`)  |
+| `create_workspace_app({ name, template })`         | andaimes           | um novo aplicativo inicializado pelo caminho do espaço de trabalho, além de URL em execução + link direto         |
+| `list_templates`                                   | nenhum             | somente os modelos permitidos                                                                                     |
+
+`create_workspace_app` rejeita qualquer modelo não listado na lista de permissões — a lista de permissões de modelos públicos no `packages/shared-app-config/templates.ts` é oficial e protegida por CI; um agente externo não pode ampliá-lo. Uma ação de modelo com o mesmo nome substitui uma ação interna (precedência de modelo sobre núcleo). Desative todo o conjunto com `MCPConfig.builtinCrossAppTools: false`.
+
+Os catálogos de ferramentas e recursos para hosts de aplicativos são compactos por padrão — consulte [Catalog tiers](#catalog-tiers). `publicAgent.expose` continua sendo a opção para ferramentas seguras de leitura/ingestão fora desse catálogo compacto; defina `mcpApp.compactCatalog: true` apenas como uma rara exceção para actions que deve aparecer na descoberta do host do chat.
+
+Para transferências rápidas de ChatGPT/Claude, o caminho ideal é direto: chame a ação que cria ou abre o artefato e deixe o aplicativo MCP iniciar a rota. Uma solicitação de correio deve chamar `manage_draft` e renderizar a rota de composição real. Uma solicitação de painel deve chamar `open_app({ path, embed: true })` ou uma ação de painel com `mcpApp` e renderizar a rota completa do Analytics. Calendário, Formulários, Conteúdo, Slides, Design e Clipes devem seguir o mesmo padrão com seu rascunho/criação/pesquisa actions. `list_apps` é útil quando o modelo precisa escolher entre aplicativos concedidos; `resources/list` amplo, descoberta de catálogo completo ou delegação `ask_app` não devem ser o caminho normal para uma transferência óbvia de UI.
+
+### Tour por aplicativo {#tour}
+
+Cada modelo listado como permitido que produz ou lista um recurso navegável envia um construtor `link`, e os modelos pesados enviam uma ação GET + `publicAgent` para que um agente conectado possa extrair o estado ativo:
+
+- **Mail** — `manage-draft` retorna um link direto codificado em `compose`; clicar nele abre a caixa de entrada com o rascunho restaurado em um `compose-<id>`. `list-emails` / `search-emails` apontam para uma visualização filtrada da caixa de entrada.
+- **Calendário** — `manage-event-draft` retorna um link direto `calendarDraft` + `eventDraftId`; clicar nele abre um espaço reservado de rascunho visível no calendário com o editor de eventos nativo para revisão/envio. `create-event` ainda retorna `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })`; o clique chega ao calendário com o evento focado na data.
+- **Analytics** — `update-dashboard` / `save-analysis` retorna `buildDeepLink({ app: "analytics", view: "adhoc", params: { dashboardId } })`; o agente cria um painel em MCP e devolve "Abrir painel no Analytics".
+- **Design** — `get-design-snapshot` é a ação de ingestão GET + `publicAgent`: ela retorna o conteúdo do arquivo Yjs **ao vivo** mais os valores de ajuste resolvidos para que o agente continue a partir do design ajustado, não dos tokens originais. `apply-tweaks` volta com um link do editor "Design aberto".
+- **Conteúdo** — `pull-document` é a ação de ingestão GET + `publicAgent`: ele libera qualquer sessão colaborativa ao vivo aberta para SQL primeiro para que o agente externo ingira exatamente o que o usuário vê e, em seguida, exibe um link direto para o documento.
+- **Brain** — `ask-brain` / `search-everything` retornam uma resposta citada mais um link direto para o conhecimento/captura subjacente, de modo que a pesquisa de um agente terminal vincula diretamente à fonte no aplicativo em execução.
+
+## Autoria (para autores de modelos) {#authoring}
+
+Tudo acima é para **usuários finais** conectarem e usarem um aplicativo. O restante desta página é para **autores de modelos** que conectam um aplicativo para ser um bom cidadão de agente externo: o construtor `link`, os aplicativos MCP opcionais UI, a rota interna `/_agent-native/open` e a ingestão de actions.
+
+### O construtor `link` {#link-builder}
+
+`defineAction` aceita um construtor `link` opcional. Quando definido, cada resultado MCP/A2A dessa ferramenta anexa automaticamente um bloco `[label →](absoluteUrl)` de redução e um `_meta["agent-native/openLink"] = { label, view, webUrl, desktopUrl, vscodeUrl }` estruturado. `tools/list` adiciona `annotations["agent-native/producesOpenLink"]` e um sufixo de descrição para que o agente externo saiba que a ferramenta produz um link que pode ser aberto e deve exibi-lo.
+
+Construa o URL com `buildDeepLink(...)` — é a única fonte de verdade para o formato de rota aberta. Nunca formate manualmente o `/_agent-native/open` URL.
+
+Exemplo real — correio `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/pesquise o ponto actions em uma visualização focada em registro da mesma maneira - por exemplo, o `create-event` do calendário retorna `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })` com o rótulo `"Open event in Calendar"`. O rascunho do calendário actions usa o mesmo padrão: `manage-event-draft` retorna `buildDeepLink({ app: "calendar", view: "calendar", to: "/", params: { eventDraftId, calendarDraft, date } })` com o rótulo `"Review invite in Calendar"`, para que os agentes externos possam devolver um link direto de revisão do rascunho sem criar o evento primeiro.
+
+### Aplicativos MCP opcionais UI {#mcp-apps}
+
+Actions pode anunciar um recurso UI em linha com `mcpApp` para hosts que suportam a extensão de aplicativos MCP. Use `embedRoute({ title, openLabel, path })` como invólucro de conveniência ou atribua `embedApp(...)` a `mcpApp.resource` diretamente. Cada aplicativo MCP é uma rota React real, não um widget HTML simples separado. Sempre mantenha o construtor `link`: hosts somente CLI, clientes mais antigos e hosts não MCP-Apps usam-no como substituto.
+
+Consulte [MCP Apps](/docs/mcp-apps) para obter o guia de criação completo — `embedRoute` vs `embedApp`, o formato de configuração do `mcpApp`, CSP, altura, o caminho de incorporação do `sendToAgentChat()` e auxiliares de cliente da ponte de host.
+
+### O contrato `link` {#link-contract}
+
+O construtor `link` é **puro e síncrono — sem E/S, sem espera**. Ele executa o melhor esforço: um lançamento, `null` ou `undefined` é engolido e **nunca** falha na chamada da ferramenta. Ele lê apenas `args` e `result` da chamada; ele não deve consultar o banco de dados, ler o estado do aplicativo ou chamar outro actions. Devolva `null` quando não houver nada para abrir.
+
+`buildDeepLink({ app, view, params?, to?, compose? })` retorna o caminho relativo ao aplicativo `/_agent-native/open?app=…&view=…&<recordId>=…`. A camada MCP transforma isso em um URL web absoluto (`toAbsoluteOpenUrl`, usando a origem da solicitação), um desktop `agentnative://open?…` URL (`toDesktopOpenUrl`) e uma extensão VS Code URL (`toVsCodeOpenUrl`) para `vscode://builder.agent-native/open?url=…`; o link markdown usa o desktop URL quando o cliente sinaliza `target: "desktop"`.
+
+### A rota `/_agent-native/open` {#open-route}
+
+Quando o usuário clica no link em qualquer navegador ou webview in-line, `GET /_agent-native/open` (`createOpenRouteHandler`, montado pelo plug-in de rotas principais) executa as etapas abaixo.
+
+```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. Resolve a sessão do **navegador** via `getSession` (o protetor de autenticação ignora o caminho exato `/_agent-native/open`).
+2. Se não autenticado, atende o login configurado HTML **no mesmo URL**; o manipulador de sucesso do formulário recarrega `window.location`, inserindo novamente a rota autenticada - sem encanamento `?next=`.
+3. Grava o comando de estado do aplicativo `navigate` existente (carga útil = cada parâmetro de consulta não reservado + `view`) com escopo no e-mail da sessão do navegador com `requestSource: "deep-link"` e decodifica um rascunho de url base64 `compose` em uma chave `compose-<id>`.
+4. 302-redireciona para um caminho relativo seguro de mesma origem (`to=`, caso contrário, `/<view>`, caso contrário, um `resolveOpenPath` por modelo), encaminhando parâmetros de filtro `f_*` para que listas/paineles abram pré-filtrados antes mesmo que o comando `navigate` seja drenado.
+
+Os redirecionamentos de origem cruzada, `//host` relativos ao esquema e control-char são rejeitados (proteção de redirecionamento aberto). A rota pode ser desativada por aplicativo via `disableOpenRoute`.
+
+#### A regra de identidade da sessão do navegador {#identity-rule}
+
+O link não carrega **nenhum estado privilegiado** — é apenas `view` + IDs de registro + filtros. A gravação `navigate` com foco no registro tem como escopo quem está conectado ao **navegador**, nunca o token MCP do agente externo. Portanto, um agente autenticado como uma identidade pode entregar um link a um usuário e, quando esse usuário clica nele, o registro é aberto onde _o usuário_ está conectado. Isso é o que torna o link direto seguro para aparecer em um terminal ou transcrição de bate-papo. Consulte [Context Awareness](/docs/context-awareness) para obter o contrato `navigate`/`application_state` para o qual esta ponte é feita.
+
+### Ingerir actions {#ingest}
+
+Uma ação que um agente externo lê para extrair o estado do aplicativo ativo para seu próprio contexto deve ser:
+
+```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` mantém a ação livre de efeitos colaterais e fora do evento de alteração de atualização de tela. `publicAgent` é a **opção explícita** — uma rota pública da web nunca implica exposição pública de MCP/A2A; veja [Actions](/docs/actions). Ingestão de design/conteúdo actions MUST lê o estado **ao vivo** (o documento colaborativo Yjs, não a coluna obsoleta do snapshot do banco de dados) para que o agente externo veja o que o usuário realmente tem na tela. O `pull-document` do conteúdo libera primeiro qualquer sessão de colaboração ao vivo aberta para o SQL; o `get-design-snapshot` do design retorna o conteúdo do arquivo Yjs ativo mais os valores de ajuste resolvidos pelo usuário.
+
+## Avançado: desenvolvimento local e configuração manual {#advanced}
+
+O fluxo `connect` hospedado acima é o caminho recomendado. As opções abaixo são para desenvolvimento local e configurações manuais.
+
+### Desenvolvimento local {#local-dev}
+
+Execute seu aplicativo localmente (`pnpm dev` / `npx @agent-native/core@latest dev`) e aponte um agente local para ele com um comando:
+
+```bash
+npx @agent-native/core@latest mcp install --client claude-code|claude-code-cli|codex|cowork \
+  [--app <id>] [--scope user|project]
+```
+
+Ele provisiona um token (um `ACCESS_TOKEN` aleatório no espaço de trabalho `.env` para desenvolvedor local ou um JWT assinado se detectar uma origem hospedada) e grava uma entrada de servidor stdio idempotente:
+
+- **claude-code / claude-code-cli** — uma entrada `mcpServers` em `.mcp.json` (escopo do projeto, padrão) ou `~/.claude.json` (`--scope user`).
+- **cowork** — o mesmo formato do Código Claude JSON em `~/.cowork/mcp.json`.
+- **codex** — um bloco `[mcp_servers.<name>]` em `~/.codex/config.toml`.
+
+A entrada executa `npx @agent-native/core@latest mcp serve --app <id>`, que por padrão é um **proxy stdio fino** para o `/_agent-native/mcp` do aplicativo local em execução — portanto, o registro de ação ao vivo, HMR, e os links diretos corretos permanecem a única fonte da verdade. Passe `--standalone` para construir o registro em processo. Quando `npx @agent-native/core@latest mcp install` detecta uma origem hospedada (um `APP_URL` / `BETTER_AUTH_URL` / `AGENT_NATIVE_MCP_URL` não localhost no espaço de trabalho `.env`), ele grava uma entrada de cliente `http` apontando para `<origin>/_agent-native/mcp` com um `Bearer` JWT em vez de uma entrada stdio.
+
+Subcomandos complementares:
+
+| Comando                                                    | O que faz                                                                    |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `npx @agent-native/core@latest mcp serve [--app <id>]`     | Execute o transporte stdio MCP (quais configurações do cliente são geradas). |
+| `npx @agent-native/core@latest mcp install --client <c>`   | Provisione um token e grave a configuração MCP do cliente (idempotente).     |
+| `npx @agent-native/core@latest mcp uninstall --client <c>` | Remova a entrada MCP nomeada da configuração de um cliente (idempotente).    |
+| `npx @agent-native/core@latest mcp status`                 | Mostrar MCP URL/porta resolvido, estado do token e entradas por cliente.     |
+| `npx @agent-native/core@latest mcp token [--rotate]`       | Imprima (ou gire) o `ACCESS_TOKEN` local na área de trabalho `.env`.         |
+
+Reinicie o cliente após `install` para que ele pegue o novo servidor MCP.
+
+### Entrada manual `.mcp.json` HTTP {#manual-entry}
+
+Você também pode escrever a configuração do cliente MCP manualmente em qualquer endpoint implantado com um token fornecido por você mesmo (um `ACCESS_TOKEN` ou um `A2A_SECRET` assinado por JWT carregando o `sub` + `org_domain` do chamador para que a execução da ferramenta permaneça no escopo do locatário):
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "analytics": {
+      "type": "http",
+      "url": "https://analytics.agent-native.com/_agent-native/mcp",
+      "headers": { "Authorization": "Bearer <ACCESS_TOKEN-or-JWT>" },
+    },
+  },
+}
+```
+
+Este é o equivalente não gerenciado do que `connect` escreve para você. Consulte [MCP Protocol](/docs/mcp-protocol) para obter a matriz env-var de autenticação completa.
+
+### Superfície da ferramenta de desenvolvimento versus produção {#dev-vs-prod}
+
+No desenvolvimento local simples (`NODE_ENV=development` e `AGENT_MODE !== "production"`), o MCP `tools/list` expõe deliberadamente apenas os componentes genéricos mais actions com `publicAgent.requiresAuth === false` - a ingestão por aplicativo actions (`requiresAuth: true`) e actions mutante (sem `publicAgent`) são filtrados (`filterPublicAgentActions`). O catálogo compacto é o padrão para cada chamador após autenticação - clientes stdio/code usando o proxy `agent-native`, o CLI local e chamadores HTTP remotos no estilo de bate-papo - portanto, ChatGPT/Claude (ou qualquer cliente) não pode despejar um enorme catálogo de ações completo na conversa. O catálogo completo do desenvolvedor é servido apenas com aceitação explícita (token `--full-catalog` ou `AGENT_NATIVE_MCP_FULL_CATALOG=1`); Enquanto isso, `tool-search` mantém todas as ferramentas acessíveis.
+
+### Alternar aplicativos próprios entre produção e desenvolvimento {#dev-switch}
+
+Quando você já tiver aplicativos hospedados primários conectados e quiser testar alterações de estrutura local por meio do `pnpm dev:lazy`, use o alternador de desenvolvedor:
+
+```bash
+pnpm dev:lazy -- --apps mail,calendar,analytics
+
+npx @agent-native/core@latest connect dev --apps mail,calendar,analytics --client codex
+```
+
+`connect dev` reescreve os mesmos nomes de servidor MCP estáveis ​​(`agent-native-mail`, `agent-native-calendar`, etc.) para o gateway local dev-lazy, para que os nomes das ferramentas não sejam alterados. Ele faz backup das entradas de produção atuais em `~/.agent-native/connect-profiles.json` antes de gravar as entradas de desenvolvimento. O gateway padrão é `http://127.0.0.1:8080`; use `--gateway <url>` ou `--port <n>` se seu gateway foi movido.
+
+Voltar com:
+
+```bash
+npx @agent-native/core@latest connect prod --apps mail,calendar,analytics --client codex
+```
+
+Se `connect dev` não puder inferir sua identidade de proprietário local a partir de um JWT conectado existente, passe `--owner-email you@example.com`; isso mantém as ferramentas de desenvolvimento locais na superfície MCP totalmente autenticada, em vez da superfície de desenvolvimento esparsa e não autenticada.
+
+## Como funciona e segurança {#how-it-works}
+
+O caminho OAuth padrão nunca expõe tokens para aplicativos MCP: o host armazena tokens de acesso/atualização OAuth e medeia chamadas de ferramenta e `resources/read` pela conexão MCP autenticada. Os iframes incorporados recebem dados do aplicativo e resultados de ferramentas, e não segredos do portador.
+
+As incorporações completas do aplicativo também evitam entregar o token de portador MCP ao navegador. O chamador MCP cria um ticket de incorporação único em SQL; a rota de inicialização do iframe o consome e define um cookie de sessão do navegador seguro para iframe e de curta duração. O URL de destino carrega um parâmetro de consulta `__an_embed_token` temporário apenas por tempo suficiente para que o cliente o capture, remova-o da barra de endereço e anexe-o a chamadas `fetch` de mesma origem quando cookies de terceiros são bloqueados. As sessões incorporadas têm escopo de rota; as buscas de aplicativos incluem o destino incorporado atual e o servidor rejeita a reutilização de token fora da rota criada. As páginas do aplicativo intencionalmente não emitem `X-Frame-Options` ou CSP `frame-ancestors`, portanto, os hosts de aplicativos Builder, Design e MCP podem fazer iframe delas. As navegações iframe do navegador também optam por COEP/CORP quando necessário para hosts isolados de origem cruzada.
+
+O fluxo `connect` hospedado substituto nunca copia o segredo compartilhado da implantação. Em vez disso:
+
+- Uma sessão de navegador logada gera um token **por usuário, com escopo e revogável** — um JWT assinado por `A2A_SECRET` que transporta o `sub` + `org_domain` do chamador e um `jti` exclusivo, para que cada ferramenta executada permaneça no escopo do locatário via `runWithRequestContext`.
+- O endpoint `/_agent-native/mcp` existente aceita esse token como qualquer outro portador (consulte [MCP Protocol](/docs/mcp-protocol)) — sem novo endpoint, sem novo transporte.
+- A mesma página do Connect lista todos os tokens que você criou e permite **revogar** qualquer um deles por `jti`. Trate-os como tokens de acesso pessoal: um por cliente agente, revogue quando uma máquina for desativada.
+- O deep link que o agente devolve não carrega nenhum estado privilegiado. A gravação `navigate` com foco no registro sempre tem como escopo a sessão do **navegador**, nunca o token do agente. Portanto, é seguro colar um link em um terminal ou na transcrição do bate-papo.
+
+## Faça/Não faça {#do-dont}
+
+**Faça**
+
+- Conecte seu próprio agente ao Dispatch com `npx @agent-native/core@latest connect https://dispatch.agent-native.com`; use um aplicativo direto URL somente quando quiser um aplicativo isolado.
+- Adicione um construtor `link` a qualquer ação que produza ou liste um recurso navegável (rascunho, evento, painel, documento).
+- Construa o URL com `buildDeepLink(...)` — a única fonte de verdade para o formato de rota aberta.
+- Mantenha `link` puro e síncrono; retorne `null` quando não houver nada para abrir.
+- Faça com que o agente externo ingira actions GET + `readOnly` + `publicAgent` e leia o estado ativo (Yjs), não a coluna obsoleta do banco de dados.
+- Deixe a rota aberta resolver a sessão do navegador; passe os IDs de registro como parâmetros de link direto e deixe o UI focalizá-los por meio do comando `navigate` pesquisado.
+- Revogar um token de conexão criado por `jti` quando um cliente agente for desativado.
+- Teste os aplicativos MCP com os acessórios leves do `embedApp()` e
+  `McpAppRenderer`; eles cobrem CSP, contexto de host, inicialização de aplicativo e ponte
+  comportamento da mensagem sem a necessidade de um host externo real.
+- Ao validar a web ChatGPT ou Claude, acione uma nova chamada de ferramenta após o shell
+  alterações e medir o iframe visível. Quadros renderizados anteriormente no
+  a mesma conversa ainda pode mostrar a altura em cache ou o comportamento de inicialização.
+- Mantenha os catálogos de host de aplicativo ChatGPT/Claude compactos. Use Despacho e
+  `open_app({ embed: true })` para visualizações completas do aplicativo; marque apenas um específico
+  ação `mcpApp.compactCatalog: true` quando deve aparecer diretamente no
+  superfície compacta de descoberta de host.
+
+**Não**
+
+- Copie o `ACCESS_TOKEN`/`A2A_SECRET` compartilhado de uma implantação em uma configuração do cliente quando `connect` puder criar um token revogável por usuário.
+- Formate manualmente o `/_agent-native/open` URL — sempre passe por `buildDeepLink`.
+- Faça E/S, esperas, leituras de banco de dados ou leituras de estado do aplicativo dentro de um construtor `link`.
+- Escolha a gravação `navigate` no token do agente ou passe o estado privilegiado por meio do link direto — é um ponteiro puro.
+- Invente um novo mecanismo de navegação; ponte para o contrato `navigate`/`application_state` existente.
+- Amplie a lista de permissões de modelos públicos ao criar o scaffold de um aplicativo a partir de um agente externo — a lista de permissões é oficial e protegida.
+
+## Relacionado {#related}
+
+- [MCP Apps](/docs/mcp-apps) — criação de aplicativos MCP UIs, ponte incorporada e ponte de host API.
+- [MCP Protocol](/docs/mcp-protocol) — o servidor MCP montado automaticamente e a metaferramenta `ask-agent`.
+- [MCP Clients](/docs/mcp-clients) — a direção simétrica: seu aplicativo consumindo servidores MCP locais/remotos.
+- [A2A Protocol](/docs/a2a-protocol) — a metaferramenta `ask-agent` e chamadas de pares JSON-RPC.
+- [Actions](/docs/actions) — definindo actions, `publicAgent`, GET / `readOnly`.
+- [Context Awareness](/docs/context-awareness) — o `navigate` / `application_state` contrata as pontes de rota aberta para.