@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/pt-BR/mcp-clients.md

@@ -0,0 +1,330 @@
+---
+title: "Clientes MCP"
+description: "Conecte seu aplicativo nativo do agente aos servidores MCP locais (claude-in-chrome, sistema de arquivos, dramaturgo, etc.) para que o agente obtenha suas ferramentas."
+---
+
+# Clientes MCP
+
+**Esta página: forneça mais ferramentas ao seu agente.** Aponte um aplicativo nativo do agente para os servidores MCP — locais ou remotos — para que suas ferramentas apareçam no bate-papo do agente. Esta é a direção _cliente_, a imagem espelhada de [MCP Protocol](/docs/mcp-protocol) (que torna seu aplicativo um _servidor_ MCP).
+
+| Se você quiser…                                                                                  | Ler                                      |
+| ------------------------------------------------------------------------------------------------ | ---------------------------------------- |
+| Conecte um agente/host externo ao seu aplicativo                                                 | [External Agents](/docs/external-agents) |
+| Dê mais ferramentas ao seu agente (consuma outros servidores MCP)                                | **Esta página** — Clientes MCP           |
+| Crie UIs in-line que renderizam 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)       |
+
+Com um arquivo de configuração, cada aplicativo nativo do agente em seu espaço de trabalho obtém acesso às ferramentas fornecidas pelos servidores MCP em sua máquina: `claude-in-chrome` para automação de navegador, `@modelcontextprotocol/server-filesystem` para leitura de arquivos, `@playwright/mcp` para teste de navegador e qualquer outra coisa que fale MCP.
+
+Você também pode [connect remote (HTTP) MCP servers at runtime](#remote-via-ui) — usuários individuais ou organizações inteiras — sem editar um arquivo de configuração.
+
+Cada fonte é resolvida em um **gerenciador MCP** de tempo de execução, e cada ferramenta que ela aprende chega ao registro de ferramentas do agente sob um prefixo `mcp__<server-id>__<tool>` à prova de colisão — pesquisável por intenção por meio de `tool-search`.
+
+```an-diagram title="Client direction: many sources, one tool registry" summary="Config files, env, and runtime UI all merge into the MCP manager; its tools appear prefixed and tool-searchable alongside your app's actions. This is the mirror of the server direction."
+{
+  "html": "<div class=\"mcp-merge\"><div class=\"diagram-col sources\"><div class=\"diagram-box\" data-rough>Workspace <code>mcp.config.json</code><br><small class=\"diagram-muted\">shared across apps</small></div><div class=\"diagram-box\" data-rough>App-root <code>mcp.config.json</code><br><small class=\"diagram-muted\">per-app override</small></div><div class=\"diagram-box\" data-rough><code>MCP_SERVERS</code> env<br><small class=\"diagram-muted\">CI / production</small></div><div class=\"diagram-box\" data-rough>Remote via settings UI<br><small class=\"diagram-muted\">personal &amp; org scope</small></div></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 manager</span><small class=\"diagram-muted\">merge &middot; hot-reload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col out\"><div class=\"diagram-node\">Agent tool registry<br><small class=\"diagram-muted\"><code>mcp__&lt;server-id&gt;__&lt;tool&gt;</code></small></div><div class=\"diagram-node\"><code>tool-search</code><br><small class=\"diagram-muted\">discover by intent</small></div></div></div>",
+  "css": ".mcp-merge{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mcp-merge .diagram-col{display:flex;flex-direction:column;gap:8px}.mcp-merge .center{display:flex;flex-direction:column;align-items:center;gap:4px}.mcp-merge .diagram-arrow{font-size:22px;line-height:1}.mcp-merge code{font-size:.85em}"
+}
+```
+
+> A direção oposta - tornar _seu_ aplicativo um servidor MCP que outros hosts consomem - reside em [MCP Protocol](/docs/mcp-protocol) e [External Agents](/docs/external-agents).
+
+## Navegador integrado e recursos de uso do computador {#built-in-capabilities}
+
+Agent-native inclui alternâncias de desenvolvimento local para servidores stdio MCP comuns.
+Eles estão desativados por padrão e podem ser ativados apenas por usuário ou por organização
+quando o aplicativo está sendo executado localmente. Os tempos de execução sem servidor hospedados e de produção são ignorados
+esses recursos integrados mesmo que existam linhas de configurações antigas e os Recursos do espaço de trabalho
+a árvore não os mostra como recursos `mcp-servers/*.json` padrão.
+
+| Capacidade                                 | ID do servidor    | Comando                                                                 |
+| ------------------------------------------ | ----------------- | ----------------------------------------------------------------------- |
+| Ferramentas para desenvolvedores do Chrome | `chrome-devtools` | `npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics` |
+| Navegador do dramaturgo                    | `playwright`      | `npx -y @playwright/mcp@latest`                                         |
+| Uso do computador                          | `computer-use`    | `npx -y computer-use-mcp@latest`                                        |
+
+Apenas um recurso de navegador pode ser ativado em um escopo por vez. A ativação do Chrome DevTools desativa o Playwright para o mesmo usuário ou organização, e a ativação do Playwright desativa o Chrome DevTools.
+
+O uso do computador é somente para macOS. Em outras plataformas, ele é listado como indisponível e é ignorado mesmo que uma linha de configuração antiga o contenha.
+
+O Chrome DevTools usa `--autoConnect` por padrão. Isso é anexado a uma instância qualificada do Chrome em execução; ele não cria um perfil de navegador isolado nem faz login no perfil normal do usuário para você. Requer Chrome 144+ com depuração remota habilitada. Uma configuração `browser-url` manual pode ser adicionada posteriormente quando uma implantação precisar de um endpoint de depuração específico.
+
+Os integrados são mantidos na tabela `settings` da estrutura em `u:<email>:mcp-builtin-capabilities` para alternâncias pessoais e `o:<orgId>:mcp-builtin-capabilities` para alternâncias de equipe. Quando ativados, eles se fundem no gerenciador de tempo de execução MCP com o mesmo formato de visibilidade de escopo dos servidores remotos, por exemplo, `mcp__user_<emailhash>_playwright__*` ou `mcp__org_<orgId>_chrome-devtools__*`.
+
+### Notas de configuração para o usuário
+
+Use uma cópia de configuração concisa e explícita para os recursos internos confidenciais:
+
+- **Chrome DevTools** é anexado a um destino de depuração do Chrome em execução. Informe aos usuários
+  destina-se a testes de navegador e verificação de login, e que
+  pode exigir a ativação da depuração remota do Chrome antes que as ferramentas apareçam.
+- **Playwright** inicia um navegador isolado. Recomendo para fins determinísticos
+  Controle de qualidade quando o perfil ativo do Chrome do usuário não é necessário.
+- **O uso do computador** pode operar aplicativos locais. Mantenha-o desativado por padrão, explique o
+  Avisos de gravação de tela e acessibilidade do macOS e pergunte antes de executar
+  actions sensíveis, como compras, alterações financeiras ou alterações de conta.
+
+### Endpoints integrados
+
+| Método | Rota                         | Propósito                                                                       |
+| ------ | ---------------------------- | ------------------------------------------------------------------------------- |
+| GET    | `/_agent-native/mcp/builtin` | Liste recursos integrados, escopos ativados, IDs mesclados e status ativo.      |
+| POST   | `/_agent-native/mcp/builtin` | Atualize um escopo. Corpo: `{ scope, enabledIds }` ou `{ scope, id, enabled }`. |
+
+## Adicionando um servidor MCP local {#adding-a-server}
+
+Crie `mcp.config.json` na raiz do seu espaço de trabalho (ou na raiz de um aplicativo individual — a raiz do espaço de trabalho vence quando ambas existirem):
+
+```jsonc
+{
+  "$schema": "https://agent-native.com/schema/mcp.config.json",
+  "servers": {
+    "claude-in-chrome": {
+      "command": "claude-in-chrome-mcp",
+      "args": [],
+      "env": { "LOG_LEVEL": "info" },
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem@latest",
+        "/Users/me/projects",
+      ],
+    },
+  },
+}
+```
+
+A forma é pequena: um mapa `servers` codificado por ID do servidor, onde cada entrada é um iniciador stdio (`command` + `args` + `env` opcional) ou uma entrada `{ "type": "http", "url", "headers" }` remota.
+
+```an-annotated-code title="mcp.config.json, annotated"
+{
+  "filename": "mcp.config.json",
+  "language": "jsonc",
+  "code": "{\n  \"$schema\": \"https://agent-native.com/schema/mcp.config.json\",\n  \"servers\": {\n    \"claude-in-chrome\": {\n      \"command\": \"claude-in-chrome-mcp\",\n      \"args\": [],\n      \"env\": { \"LOG_LEVEL\": \"info\" }\n    },\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem@latest\", \"/Users/me/projects\"]\n    }\n  }\n}",
+  "annotations": [
+    { "lines": "3", "label": "Server id", "note": "The key becomes the tool prefix: this server's tools surface as `mcp__claude-in-chrome__*` in the agent's registry, so they can't collide with your template's actions." },
+    { "lines": "4-6", "label": "stdio launcher", "note": "`command` + `args` spawn a local binary. Stdio servers are intended for **local development** — they are a no-op in edge runtimes." },
+    { "lines": "6", "label": "Process env", "note": "Optional `env` is passed to the spawned process. Keep secrets out of committed config; prefer `MCP_SERVERS` or the settings UI for tokens." }
+  ]
+}
+```
+
+Na próxima inicialização do aplicativo, você verá:
+
+```
+[mcp-client] loaded config from /path/to/mcp.config.json (3 server(s))
+[mcp-client] connected to claude-in-chrome: 12 tools
+[mcp-client] connected to playwright: 9 tools
+[mcp-client] connected to filesystem: 4 tools
+```
+
+As ferramentas são registradas no registro de ferramentas do agente com o prefixo `mcp__<server-id>__<tool-name>` para que não possam colidir com o actions do seu modelo. Eles também estão incluídos no `tool-search`, para que os agentes possam descobrir os recursos do MCP recém-conectados por intenção, em vez de precisar do nome prefixado exato antecipadamente.
+
+## Precedência de configuração {#precedence}
+
+A configuração MCP é resolvida nesta ordem, a primeira partida vence:
+
+1. **Raiz do espaço de trabalho `mcp.config.json`** — detectada via `agent-native.workspaceCore` em `package.json`. Compartilhado em todos os aplicativos no espaço de trabalho.
+2. **App-root `mcp.config.json`** — substituição por aplicativo se você não quiser um servidor MCP disponível em todos os aplicativos.
+3. **`MCP_SERVERS` env var** — string JSON com o mesmo formato, para CI/produção onde um arquivo não faz sentido.
+
+## Implantações de produção: `MCP_SERVERS` {#mcp-servers-env}
+
+Para implantações de produção, prefira servidores HTTP MCP remotos e defina a configuração completa
+forma (ou o mapa interno do servidor) como uma variável de ambiente:
+
+```bash
+MCP_SERVERS='{"servers":{"zapier":{"type":"http","url":"https://mcp.example.com/mcp","headers":{"Authorization":"Bearer paste-token-value-here"}}}}'
+```
+
+`MCP_SERVERS` é analisado como JSON, portanto, os espaços reservados `${...}` não são expandidos
+dentro da string. Se você armazenar o token em outro segredo, expanda-o antes
+escrever o valor final JSON.
+
+Os servidores Stdio MCP geram binários locais e são destinados ao desenvolvimento local.
+As ferramentas MCP são ativadas apenas em tempos de execução do Node — Cloudflare Workers e outras bordas
+os alvos ignoram MCP silenciosamente e continuam com o restante do aplicativo funcionando
+normalmente.
+
+## Detecção automática: `claude-in-chrome` {#autodetect}
+
+Se você **não** `mcp.config.json` e o binário `claude-in-chrome-mcp` estiver em `PATH` (ou no local de instalação conhecido `~/.claude-in-chrome/bin/claude-in-chrome-mcp`), o agente nativo o registrará automaticamente como um servidor MCP padrão. Defina `AGENT_NATIVE_DISABLE_MCP_AUTODETECT=1` para cancelar.
+
+Isso significa que os usuários que instalaram a extensão claude-in-chrome terão controle do navegador em todos os aplicativos nativos do agente que abrirem, sem alterações de configuração.
+
+## Servidores MCP remotos através das configurações UI {#remote-via-ui}
+
+Os servidores MCP (Model Context Protocol) oferecem novas habilidades ao seu agente, como conectar-se ao Zapier, Cloudflare, Composio ou às ferramentas internas da sua empresa. Uma vez conectado, o agente pode usar essas ferramentas exatamente como as integradas.
+
+### Como conectar um servidor MCP remoto
+
+1. **Nome do servidor** — um rótulo curto para sua própria referência (por exemplo, "zapier", "slack-tools").
+2. **URL** — o endpoint HTTPS que o provedor do servidor MCP lhe forneceu (por exemplo, `https://mcp.zapier.com/s/abc123/mcp`). Isso geralmente é encontrado no painel do provedor ou nos documentos de integração.
+3. **Descrição** (opcional) — uma observação sobre o que este servidor faz.
+4. **Headers** — credenciais de autenticação exigidas pelo servidor, uma por linha. A maioria dos servidores precisa de um cabeçalho `Authorization`. Exemplo: `Authorization: Bearer sk-your-key-here`. Os documentos do provedor dirão o que colocar aqui.
+
+Clique em **Testar** para verificar a conexão antes de salvar. Se tiver sucesso, você verá o número de ferramentas disponíveis. Clique em **Conectar** para adicioná-lo.
+
+### Escopo pessoal versus organizacional
+
+Dois escopos são suportados:
+
+- **Pessoal** — apenas o usuário conectado obtém as ferramentas. Armazenado como uma configuração de escopo do usuário.
+- **Equipe** — todos na organização ativa recebem as ferramentas. Proprietários e administradores podem adicionar; os membros veem a lista como somente leitura. Armazenado como uma configuração de escopo organizacional.
+
+Adiciona e remove hot-reload no gerenciador MCP em execução - sem reinicialização do processo e sem reinicialização do servidor. As novas ferramentas `mcp__<scope>-<name>__*` aparecem para o agente na próxima mensagem e podem ser pesquisadas via `tool-search`.
+
+HTTPS URLs são aceitos em todos os lugares; `http://` simples só é permitido para `localhost` durante o desenvolvimento. A autenticação opcional entra como um token de portador enviado via `Authorization: Bearer …` em cada solicitação.
+
+Nos bastidores, esses servidores são mantidos na tabela `settings` da estrutura sob a chave `u:<email>:mcp-servers-remote` (Pessoal) ou `o:<orgId>:mcp-servers-remote` (Equipe) e mesclados com `mcp.config.json` na inicialização.
+
+### Extremidades HTTP
+
+| Método | Rota                                                  | Propósito                                                                         |
+| ------ | ----------------------------------------------------- | --------------------------------------------------------------------------------- |
+| GET    | `/_agent-native/mcp/servers`                          | Liste os servidores pessoais + organizacionais do usuário atual com status ativo. |
+| POST   | `/_agent-native/mcp/servers`                          | Adicione um servidor. Corpo: `{ scope, name, url, headers?, description? }`.      |
+| DELETE | `/_agent-native/mcp/servers/:id?scope=user\|org`      | Remova um servidor e reconfigure o gerenciador.                                   |
+| POST   | `/_agent-native/mcp/servers/:id/test?scope=user\|org` | Execute as ferramentas de conexão + lista do servidor existente.                  |
+| POST   | `/_agent-native/mcp/servers/test`                     | Execute um URL arbitrário antes de persistir. Corpo: `{ url, headers? }`.         |
+
+Os servidores Stdio ainda não funcionam fora dos tempos de execução do Node, mas os servidores remotos HTTP MCP funcionam em qualquer ambiente com `fetch`, incluindo compilações de produção para desktop.
+
+## Servidores MCP compartilhados por meio de um hub {#hub}
+
+Se seu espaço de trabalho executa vários aplicativos nativos de agente (por exemplo, envio + e-mail + clipes), você pode configurar **um** aplicativo como hub e fazer com que os outros extraiam seus servidores MCP de escopo organizacional automaticamente. Não há cópia e colagem por aplicativo de URLs e tokens ao portador. Consulte [Multi-App Workspace](/docs/multi-app-workspace) para obter a abordagem canônica usando recursos MCP do espaço de trabalho do Dispatch.
+
+O Dispatch é o hub convencional: ele já coordena todos os aplicativos.
+
+```an-diagram title="Hub model: one app serves org-scope MCP servers" summary="Dispatch holds the org-scope MCP servers; consumer apps pull and merge them as mcp__hub_<orgId>_<name>__*. Only org-scope rows are shared — personal credentials stay put."
+{
+  "html": "<div class=\"mcp-hub\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Dispatch hub</span><small class=\"diagram-muted\">org-scope MCP servers</small><small class=\"diagram-muted\"><code>GET /mcp/hub/servers</code></small></div><div class=\"diagram-col arrows\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div></div><div class=\"diagram-col consumers\"><div class=\"diagram-box\" data-rough>Mail<br><small class=\"diagram-muted\"><code>mcp__hub_&lt;orgId&gt;_&lt;name&gt;__*</code></small></div><div class=\"diagram-box\" data-rough>Clips<br><small class=\"diagram-muted\">pull + merge each ~60s</small></div></div></div><p class=\"diagram-muted note\">Bearer-gated by <code>AGENT_NATIVE_MCP_HUB_TOKEN</code>. Personal (user-scope) servers are never re-exposed.</p>",
+  "css": ".mcp-hub{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mcp-hub .center{display:flex;flex-direction:column;align-items:center;gap:4px}.mcp-hub .diagram-col{display:flex;flex-direction:column;gap:10px}.mcp-hub .arrows .diagram-arrow{font-size:22px;line-height:1}.mcp-hub .note{margin:8px 0 0;font-size:.85em}.mcp-hub code{font-size:.85em}"
+}
+```
+
+Para novas configurações de espaço de trabalho, prefira **Enviar recursos MCP do espaço de trabalho** ao
+deseja o mesmo modelo de concessão para todos os aplicativos versus aplicativos selecionados usado pelo espaço de trabalho skills,
+instruções e recursos de referência. Adicione um recurso de espaço de trabalho com:
+
+```json
+{
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
+  },
+  "description": "Shared MCP tools for workspace apps"
+}
+```
+
+Salve-o em `mcp-servers/<name>.json` com o tipo `mcp-server`. Todos os aplicativos
+os recursos são carregados por todos os aplicativos de espaço de trabalho; os recursos selecionados são carregados apenas em
+aplicativos com uma concessão ativa do Dispatch. Espaços reservados secretos são resolvidos no aplicativo
+armazenamento secreto, então coloque tokens de portador brutos no Dispatch Vault e referencie-os
+com `${keys.NAME}` em vez de armazená-los no corpo do recurso.
+
+Os aplicativos atualizam a configuração MCP mesclada uma vez por minuto, portanto, recurso central
+edições, alterações de concessão e remoções entram em vigor sem implantação. Definir
+`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` para desativar a atualização em segundo plano ou
+defina-o com um valor de pelo menos `5000` milissegundos para ajustar o intervalo.
+
+O antigo modo de hub abaixo continua útil para “compartilhar todos os escopos organizacionais MCP
+servidor do Dispatch” e para implantações que já usam o MCP
+configura UI como a fonte da verdade.
+
+### 1. Habilite o hub-serve no aplicativo hub (despacho)
+
+Defina uma variável de ambiente na implantação do despacho:
+
+```bash
+AGENT_NATIVE_MCP_HUB_TOKEN=<a-long-random-secret>
+```
+
+O Dispatch agora monta o `GET /_agent-native/mcp/hub/servers`, que retorna todos os servidores MCP do escopo organizacional armazenados em sua tabela `settings`, com cabeçalhos URL + completos, autenticados pelo token.
+
+### 2. Aponte aplicativos de consumo no hub
+
+Definido para cada consumidor (e-mail, clipes, qualquer coisa):
+
+```bash
+AGENT_NATIVE_MCP_HUB_URL=https://dispatch.acme.com
+AGENT_NATIVE_MCP_HUB_TOKEN=<the-same-secret>
+```
+
+Na inicialização, cada consumidor extrai a lista de servidores do hub e a mescla em seu próprio gerenciador MCP. As ferramentas aparecem para o agente como `mcp__hub_<orgId>_<name>__*`, distintas do `mcp__org_…` local do próprio consumidor, portanto não há colisão.
+
+### 3. O que é compartilhado
+
+Somente servidores **org-scope** são compartilhados. Os servidores de escopo de usuário (pessoais) permanecem com o usuário que os adicionou. O hub nunca expõe novamente as credenciais pessoais nos aplicativos.
+
+As respostas do hub incluem os cabeçalhos de autenticação completos (tokens de portador, etc.). O transporte é HTTPS, o endpoint requer o segredo compartilhado e retorna apenas linhas do escopo organizacional. Trate o hub URL + token como uma credencial de banco de dados.
+
+### 4. Recarga a quente vs reinicialização
+
+O UI local adiciona recarga a quente em cada aplicativo via `McpClientManager.reconfigure()` - sem reinicialização. Os servidores originados no hub são captados pela mesma atualização periódica em segundo plano (aproximadamente 60 s, ajustável ou desativada via `AGENT_NATIVE_MCP_CONFIG_REFRESH_MS`) que o caminho do recurso do espaço de trabalho usa, de modo que as alterações feitas no Dispatch se propagam para todos os aplicativos do consumidor em cerca de um minuto, sem reinicialização. Além disso, qualquer mutação local em um app de consumo aciona imediatamente uma reconfiguração desse app.
+
+### Resumo de endpoints
+
+| Método | Rota                             | Propósito                                                                                                                                                                |
+| ------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| GET    | `/_agent-native/mcp/hub/servers` | Serve todos os servidores de escopo organizacional com credenciais completas (com acesso ao portador, montado apenas quando `AGENT_NATIVE_MCP_HUB_TOKEN` está definido). |
+| GET    | `/_agent-native/mcp/hub/status`  | Retorna `{ serving, consuming, hubUrl }` para as configurações do cartão UI.                                                                                             |
+
+## Rota de status {#status-route}
+
+Cada aplicativo expõe `GET /_agent-native/mcp/status` para ferramentas e integração:
+
+```an-api
+{
+  "method": "GET",
+  "path": "/_agent-native/mcp/status",
+  "summary": "MCP client status for tooling and onboarding",
+  "description": "Reports which configured servers connected, the total live tool count, the merged prefixed tool list, and any per-server connection errors. Use it to build \"detected — your agent can now drive X\" hints or to debug connection problems.",
+  "responses": [
+    {
+      "status": "200",
+      "description": "Configured vs connected servers, tool inventory, and per-server errors.",
+      "example": "{\n  \"configuredServers\": [\"claude-in-chrome\", \"playwright\"],\n  \"connectedServers\": [\"claude-in-chrome\", \"playwright\"],\n  \"totalTools\": 21,\n  \"tools\": [\n    {\n      \"source\": \"claude-in-chrome\",\n      \"name\": \"mcp__claude-in-chrome__navigate\",\n      \"description\": \"Navigate the browser to a URL\"\n    }\n  ],\n  \"errors\": {}\n}"
+    }
+  ]
+}
+```
+
+```json
+{
+  "configuredServers": ["claude-in-chrome", "playwright"],
+  "connectedServers": ["claude-in-chrome", "playwright"],
+  "totalTools": 21,
+  "tools": [
+    {
+      "source": "claude-in-chrome",
+      "name": "mcp__claude-in-chrome__navigate",
+      "description": "Navigate the browser to a URL"
+    }
+  ],
+  "errors": {}
+}
+```
+
+Use isso para criar dicas de integração "claude-in-chrome detectadas — seu agente agora pode conduzir o Chrome" ou depurar problemas de conexão MCP.
+
+## Modos de falha {#failures}
+
+Falhas individuais do servidor MCP nunca desativam o agente:
+
+- Um `command` configurado incorretamente → o servidor é ignorado, seu erro aparece em `/mcp/status` em `errors.<server-id>` e todos os outros servidores continuam funcionando.
+- O MCP SDK está faltando no `node_modules` → todas as funcionalidades do MCP são ignoradas com um aviso; o bate-papo do agente continua funcionando sem nenhuma ferramenta MCP.
+- Executando em um tempo de execução de borda → O cliente MCP é autônomo.
+
+O agente nativo sempre inicializará; configuração MCP quebrada significa apenas menos ferramentas.
+
+## Segurança {#security}
+
+As ferramentas MCP são executadas em sua máquina com quaisquer permissões que o processo gerado tenha. Trate `mcp.config.json` como qualquer outra lista de executáveis ​​que você deseja deixar o agente dirigir. As ferramentas dos servidores MCP aparecem no loop de uso de ferramentas do agente, assim como o actions do próprio modelo, portanto, confie em todos os servidores configurados.

package/corpus/core/docs/content/locales/pt-BR/mcp-protocol.md

@@ -0,0 +1,279 @@
+---
+title: "Protocolo MCP"
+description: "Exponha seu aplicativo nativo do agente como um servidor MCP remoto para que Claude, ChatGPT, código Claude, cursor e outras ferramentas de IA possam chamar o actions do seu aplicativo diretamente."
+---
+
+# Protocolo MCP
+
+**Esta página: a referência do servidor MCP de nível inferior.** Como cada aplicativo nativo do agente expõe seu actions sobre MCP — o endpoint montado automaticamente, modos de autenticação, a superfície `tools/call`/`ask-agent` e montagem personalizada. Procure-o quando precisar de recursos internos do servidor; para conectar um host, comece com [External Agents](/docs/external-agents).
+
+| Se você quiser…                                                                                  | Ler                                      |
+| ------------------------------------------------------------------------------------------------ | ---------------------------------------- |
+| Conecte um agente/host externo ao seu aplicativo                                                 | [External Agents](/docs/external-agents) |
+| Dê mais ferramentas ao seu agente (consuma outros servidores MCP)                                | [MCP Clients](/docs/mcp-clients)         |
+| Crie UIs embutidos que renderizam em Claude/ChatGPT                                              | [MCP Apps](/docs/mcp-apps)               |
+| Referência do servidor MCP de nível inferior (autenticação, ferramentas, montagem personalizada) | **Esta página** — Protocolo MCP          |
+
+Cada aplicativo nativo do agente expõe automaticamente um servidor MCP (Model Context Protocol) remoto, para que ferramentas externas de IA como Claude, aplicativos MCP personalizados ChatGPT, código Claude, Cursor, Codex e VS Code GitHub Copilot possam descobrir e chamar o actions do seu aplicativo diretamente, sem necessidade de código extra. Se seu objetivo é _conectar_ um desses hosts a um aplicativo hospedado, [External Agents](/docs/external-agents) abrange o conector de despacho único recomendado, URLs por aplicativo, OAuth, MCP aplicativos UIs em linha e links diretos. Esta página documenta o que está por baixo disso.
+
+## Visão geral {#overview}
+
+MCP é o protocolo padrão para conectar ferramentas de IA a recursos externos. Quando você implanta um aplicativo nativo do agente, ele monta automaticamente um endpoint MCP junto com o endpoint A2A existente. Qualquer cliente compatível com MCP pode se conectar e usar as ferramentas do seu aplicativo.
+
+Conceitos principais:
+
+- **Montado automaticamente** — todos os aplicativos recebem `/_agent-native/mcp` gratuitamente, sem necessidade de configuração
+- **Streamable HTTP** — usa o transporte MCP moderno sobre o HTTP padrão (POST + SSE)
+- **Mesmo actions** — exatamente o mesmo registro de ação que alimenta o chat do agente e o A2A
+- **Ferramenta `ask-agent`** — uma metaferramenta que delega tarefas complexas ao loop completo do agente
+- **Aplicativos MCP** — actions pode anunciar recursos UI interativos por meio da extensão `io.modelcontextprotocol/ui` oficial
+- **MCP remoto padrão OAuth** — descoberta OAuth 2.1, registro dinâmico de cliente, código de autorização + PKCE, rotação de token de atualização
+- **Bearer auth fallback** — usa `ACCESS_TOKEN`, `ACCESS_TOKENS` ou JWTs criados por conexão para clientes que não podem executar OAuth
+
+```an-diagram title="Your app as an MCP server" summary="External hosts connect over Streamable HTTP. Each action is one tool; ask-agent delegates to the full agent loop."
+{
+  "html": "<div class=\"diagram-mcp\"><div class=\"diagram-col\"><div class=\"diagram-node\">Claude</div><div class=\"diagram-node\">ChatGPT</div><div class=\"diagram-node\">Cursor · Codex</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill accent\">POST /_agent-native/mcp</span><small class=\"diagram-muted\">Streamable HTTP</small><small class=\"diagram-muted\">initialize &rarr; tools/list &rarr; tools/call</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\" data-rough>each action<br><small class=\"diagram-muted\">= one tool</small></div><div class=\"diagram-box\" data-rough>ask-agent<br><small class=\"diagram-muted\">&rarr; full agent loop</small></div></div></div>",
+  "css": ".diagram-mcp{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-mcp .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-mcp .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-mcp .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+## MCP versus A2A {#mcp-vs-a2a}
+
+Ambos os protocolos são montados automaticamente. Use o que for mais adequado ao seu caso de uso:
+
+|                               | MCP                                                                    | A2A                                                |
+| ----------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------- |
+| **Melhor para**               | Ferramentas externas que chamam seu aplicativo                         | Comunicação entre agentes                          |
+| **Protocolo**                 | MCP HTTP transmitível                                                  | JSON-RPC 2.0                                       |
+| **Descoberta de ferramentas** | `tools/list`                                                           | Cartão de agente em `/.well-known/agent-card.json` |
+| **Ponto final**               | `/_agent-native/mcp`                                                   | `/_agent-native/a2a`                               |
+| **Apoiado por**               | Claude, ChatGPT, Claude Code, Cursor, Codex, Cowork e outros hosts MCP | Outros aplicativos nativos do agente               |
+| **Execução**                  | Chamadas diretas de ferramenta (sem LLM extra)                         | Loop completo do agente (raciocínio LLM)           |
+
+Você também pode usar a ferramenta `ask-agent` MCP para obter o melhor dos dois mundos: chame-a do código Claude e deixe o agente do seu aplicativo raciocinar através de tarefas complexas.
+
+## Configuração manual do cliente MCP {#manual-config}
+
+Para a configuração recomendada de um comando, use [External Agents](/docs/external-agents). Se você estiver escrevendo à mão a configuração MCP para um cliente compatível com OAuth, adicione seu aplicativo como um servidor MCP remoto sem cabeçalhos estáticos:
+
+```bash
+claude mcp add --transport http mail https://mail.example.com/_agent-native/mcp
+```
+
+Ou escreva a entrada manualmente em `.mcp.json` (escopo do projeto) ou `~/.claude.json` (escopo do usuário):
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "mail": {
+      "type": "http",
+      "url": "https://mail.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+Em seguida, execute `/mcp` no código Claude e escolha **Autenticar**. Para clientes que não podem executar MCP OAuth remoto, use a página Conectar ou uma entrada de token de portador estático com `headers.Authorization`. Depois de autenticado, você poderá usar as ferramentas do seu aplicativo naturalmente:
+
+```
+> draft an email to John about the Q3 report
+
+Claude Code calls: draft-email(to: "john@example.com", subject: "Q3 Report", body: "...")
+```
+
+## Conectando-se de outros clientes MCP {#other-clients}
+
+Qualquer cliente MCP que suporte o transporte Streamable HTTP pode se conectar. O ponto final é:
+
+```
+POST https://your-app.example.com/_agent-native/mcp
+```
+
+O servidor suporta o handshake MCP padrão: `initialize` → `initialized` → `tools/list` → `tools/call`.
+
+```an-api title="MCP endpoint" summary="The auto-mounted Streamable HTTP endpoint every agent-native app exposes."
+{
+  "method": "POST",
+  "path": "/_agent-native/mcp",
+  "summary": "MCP Streamable HTTP endpoint",
+  "description": "Auto-mounted on every app. Speaks the standard MCP handshake (`initialize` → `initialized` → `tools/list` → `tools/call`) plus `resources/list`, `resources/templates/list`, and `resources/read` when an action declares `mcpApp`. Each action maps to one tool; `ask-agent` delegates to the full agent loop.",
+  "auth": "Standard remote MCP OAuth (Bearer access token), connect-minted JWT, or static ACCESS_TOKEN/ACCESS_TOKENS",
+  "params": [
+    { "name": "Authorization", "in": "header", "type": "string", "required": false, "description": "Bearer access token. Required except for loopback local-dev probes." },
+    { "name": "method", "in": "body", "type": "string", "required": true, "description": "MCP method, e.g. initialize, tools/list, tools/call." }
+  ],
+  "request": {
+    "contentType": "application/json",
+    "example": "{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"ask-agent\",\n    \"arguments\": { \"message\": \"Summarize Q3 signups by source\" }\n  }\n}"
+  },
+  "responses": [
+    { "status": "200", "description": "MCP result (POST + SSE)." },
+    { "status": "401", "description": "Unauthenticated — responds with a WWW-Authenticate header pointing at OAuth discovery." }
+  ]
+}
+```
+
+Se uma ação declarar `mcpApp`, o servidor também anunciará a extensão oficial de aplicativos MCP (`io.modelcontextprotocol/ui`) e oferecerá suporte a `resources/list`, `resources/templates/list` e `resources/read` para o recurso do aplicativo. Hosts que renderizam aplicativos MCP podem mostrar o UI inline; hosts que não o fazem ainda podem chamar a ferramenta e usar o fallback de link direto. Os produtos UIs devem usar `embedApp()` para que a superfície inline seja a rota real do aplicativo React ou uma rota focada que renderize um componente React compartilhado, como um gráfico do Analytics, e não uma implementação HTML simples e separada. O servidor emite metadados de aplicativos MCP padrão e metadados de compatibilidade de aplicativos ChatGPT SDK para que hosts compatíveis com aplicativos possam encontrar o mesmo recurso `ui://`. A matriz de extensão oficial atual inclui Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT e Cursor; o suporte do host varia de acordo com a versão e o plano, portanto, use o [External Agents MCP Apps notes](/docs/external-agents#mcp-apps-compatibility) para orientação ao usuário.
+
+### Ponte incorporada do aplicativo MCP {#mcp-app-embed-bridge}
+
+`embedApp()` é o URL-primeiro ajudante de aplicativo MCP de baixo nível: ele inicia um aplicativo assinado
+rota em linha por meio de transplante (Claude), quadro controlado (ChatGPT) ou direto
+navegação, medeia o host actions pela ponte `ui/*` JSON-RPC (e o
+`agentNative.mcpHost.*` retransmissão postMessage para o caminho do quadro controlado) e
+fixa a altura do shell de recursos para que uma rota de aplicativo completo não seja renderizada como
+artefato de bate-papo enorme.
+
+Consulte [MCP Apps](/docs/mcp-apps#mcp-app-bridge) para obter detalhes completos da ponte incorporada: transplante vs quadro controlado, as tabelas `ui/*` e postMessage, `create_embed_session` / `embedStartUrl`, CSP e regras de domínio, incorporação de extensão `srcDoc`, fixação de altura e o cliente de ponte de host API.
+
+## Ferramentas {#tools}
+
+Cada chamador recebe um **catálogo compacto por padrão** (aplicativo declarado por modelo actions mais os recursos integrados entre aplicativos), com a superfície de ação completa exibida apenas com aceitação explícita e `tool-search` sempre disponível para alcançar o restante. Consulte [External Agents → Catalog tiers](/docs/external-agents#catalog-tiers) para obter a explicação completa.
+
+Cada ação é mapeada diretamente para uma ferramenta MCP:
+
+| Propriedade da ação | Propriedade da ferramenta MCP |
+| ------------------- | ----------------------------- |
+| `tool.description`  | `description`                 |
+| `tool.parameters`   | `inputSchema`                 |
+| Nome da ação        | Nome da ferramenta            |
+
+Quando `mcpApp` está presente, a entrada da ferramenta também inclui `_meta.ui.resourceUri`, `_meta["ui/resourceUri"]` e `_meta["openai/outputTemplate"]`, e o recurso `ui://` correspondente é retornado como `text/html;profile=mcp-app`.
+
+### A ferramenta `ask-agent` {#ask-agent}
+
+Além das ferramentas de ação individuais, cada servidor MCP inclui uma meta-ferramenta `ask-agent`. Isso envia uma mensagem em linguagem natural ao agente de IA do aplicativo e retorna a resposta.
+
+Use `ask-agent` para tarefas complexas que se beneficiam do raciocínio e do contexto do agente:
+
+```json
+{
+  "name": "ask-agent",
+  "arguments": {
+    "message": "Draft a follow-up email to the Q3 planning thread with John, summarizing the action items we discussed"
+  }
+}
+```
+
+O agente executa o mesmo loop que o bate-papo interativo: ele pode chamar diversas ferramentas, raciocinar sobre o contexto e produzir uma resposta cuidadosa.
+
+## Autenticação {#authentication}
+
+O endpoint MCP suporta MCP remoto padrão OAuth mais o substituto de token de portador existente:
+
+| Modo                                  | Como funciona                                                                                                                  |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Padrão MCP OAuth                      | O cliente descobre a autenticação de `WWW-Authenticate`, registra, executa PKCE e envia `Authorization: Bearer <access-token>` |
+| JWT conectado-cunhado                 | `npx @agent-native/core@latest connect` / a página Connect cria um JWT revogável por usuário                                   |
+| `ACCESS_TOKEN`                        | Token de portador estático — cliente envia `Authorization: Bearer <token>`                                                     |
+| `ACCESS_TOKENS`                       | Lista separada por vírgula de tokens de portador estáticos válidos                                                             |
+| `A2A_SECRET`                          | Autenticação baseada em JWT — os tokens são verificados criptograficamente                                                     |
+| _(nenhum definido, somente loopback)_ | Não é necessária autenticação para testes de desenvolvimento local                                                             |
+
+Para hosts MCP compatíveis com OAuth, configure o servidor remoto URL sem cabeçalhos estáticos:
+
+```bash
+claude mcp add --transport http agent-native https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+A primeira solicitação MCP não autenticada recebe:
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://dispatch.agent-native.com/.well-known/oauth-protected-resource", scope="mcp:read mcp:write mcp:apps"
+```
+
+Endpoints de descoberta:
+
+| Ponto final                               | Propósito                                                  |
+| ----------------------------------------- | ---------------------------------------------------------- |
+| `/.well-known/oauth-protected-resource`   | Metadados de recursos protegidos RFC 9728                  |
+| `/.well-known/oauth-authorization-server` | Metadados do servidor de autorização OAuth                 |
+| `/_agent-native/mcp/oauth/register`       | Registro dinâmico de cliente público                       |
+| `/_agent-native/mcp/oauth/authorize`      | Autorização + consentimento do navegador                   |
+| `/_agent-native/mcp/oauth/token`          | Concessões de código de autorização e token de atualização |
+
+```an-diagram title="OAuth discovery flow" summary="A 401 kicks off discovery, registration, and a PKCE authorize → token exchange. The Bearer token is audience-bound and scoped."
+{
+  "html": "<div class=\"diagram-oauth\"><div class=\"diagram-box\" data-rough>first request<br><small class=\"diagram-muted\">no token</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill warn\">401 · WWW-Authenticate</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill\">/.well-known/oauth-protected-resource</span><span class=\"diagram-pill\">/.well-known/oauth-authorization-server</span><small class=\"diagram-muted\">discover</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill\">register</div><div class=\"diagram-pill\">authorize (PKCE)</div><div class=\"diagram-pill\">token</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Bearer access token<br><small class=\"diagram-muted\">audience-bound · mcp:read / write / apps</small></div></div>",
+  "css": ".diagram-oauth{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-oauth .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-oauth .diagram-col{display:flex;flex-direction:column;gap:6px}.diagram-oauth .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+Tokens de acesso são JWTs assinados cujo público é exatamente o recurso MCP URL. O servidor aceita apenas tokens emitidos para si mesmo e aplica escopos antes de listar/chamar ferramentas:
+
+| Escopo      | Permite                                             |
+| ----------- | --------------------------------------------------- |
+| `mcp:read`  | actions somente leitura                             |
+| `mcp:write` | mutação de actions e `ask-agent`                    |
+| `mcp:apps`  | Recursos de aplicativos MCP (recursos `ui://` HTML) |
+
+Os tokens de atualização são armazenados apenas como hashes e são alternados a cada atualização. `npx @agent-native/core@latest connect` grava esta entrada OAuth somente URL para clientes de código Claude por padrão; mantenha a página Connect, `npx @agent-native/core@latest connect --token <token>` e a configuração do portador estático para proxy stdio local, clientes mais antigos e fluxos de emergência/depuração.
+
+## Configuração MCP personalizada {#custom-setup}
+
+O servidor MCP é montado automaticamente pelo plugin de chat do agente. Para a maioria dos aplicativos, nenhuma configuração é necessária. Se precisar de um comportamento personalizado, você pode montá-lo manualmente em um plugin de servidor:
+
+```ts
+// server/plugins/mcp.ts
+import { mountMCP } from "@agent-native/core/mcp";
+import { autoDiscoverActions } from "@agent-native/core/server";
+
+export default defineNitroPlugin(async (nitro) => {
+  const actions = await autoDiscoverActions(import.meta.url);
+
+  mountMCP(nitro, {
+    name: "My App",
+    description: "Custom MCP server",
+    actions,
+    // Optional: provide ask-agent handler
+    askAgent: async (message) => {
+      // Your custom agent logic
+      return "Response";
+    },
+    // Optional: override the route prefix (default "/_agent-native")
+    // routePrefix: "/_agent-native",
+  });
+});
+```
+
+## Exemplo: análises do código Claude {#example}
+
+Você tem um aplicativo de análise implantado em `analytics.example.com`. Do código Claude:
+
+```bash
+claude mcp add --transport http analytics https://analytics.example.com/_agent-native/mcp
+```
+
+Ou adicione manualmente em `.mcp.json`:
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "analytics": {
+      "type": "http",
+      "url": "https://analytics.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+Agora no código Claude:
+
+```
+> How many signups did we get last week?
+
+Claude Code calls: run-query(sql: "SELECT count(*) FROM signups WHERE created_at > now() - interval '7 days'")
+→ "1,247 signups last week"
+```
+
+Para análises mais complexas:
+
+```
+> Ask the analytics agent to prepare a full breakdown of Q3 signups by source, with trends
+
+Claude Code calls: ask-agent(message: "Prepare a full breakdown of Q3 signups by source, with trends")
+→ The analytics agent runs multiple queries, reasons about the data, and returns a formatted report
+```