@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/es-ES/mcp-clients.md

@@ -0,0 +1,330 @@
+---
+title: "Clientes MCP"
+description: "Conecte la aplicación nativa de su agente a servidores MCP locales (claude-in-chrome, sistema de archivos, dramaturgo, etc.) para que el agente obtenga sus herramientas."
+---
+
+# Clientes MCP
+
+**Esta página: brinde a su agente más herramientas.** Apunte una aplicación nativa del agente a los servidores MCP (locales o remotos) para que sus herramientas aparezcan en el chat del agente. Esta es la dirección _cliente_, la imagen reflejada de [MCP Protocol](/docs/mcp-protocol) (que convierte su aplicación en un _servidor_ MCP).
+
+| Si quieres…                                                                                        | Leer                                     |
+| -------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Conecta un agente/host externo a tu aplicación                                                     | [External Agents](/docs/external-agents) |
+| Dale a tu agente más herramientas (consume otros servidores MCP)                                   | **Esta página** — Clientes de MCP        |
+| Crea UI en línea que se rendericen en Claude/ChatGPT                                               | [MCP Apps](/docs/mcp-apps)               |
+| Referencia del servidor MCP de nivel inferior (autenticación, herramientas, montaje personalizado) | [MCP Protocol](/docs/mcp-protocol)       |
+
+Con un archivo de configuración, cada aplicación nativa del agente en su espacio de trabajo obtiene acceso a las herramientas proporcionadas por los servidores MCP en su máquina: `claude-in-chrome` para la automatización del navegador, `@modelcontextprotocol/server-filesystem` para leer archivos, `@playwright/mcp` para pruebas del navegador y cualquier otra cosa que diga MCP.
+
+También puedes [connect remote (HTTP) MCP servers at runtime](#remote-via-ui) (usuarios individuales u organizaciones enteras) sin editar un archivo de configuración.
+
+Cada fuente se resuelve en un **administrador MCP** en tiempo de ejecución, y cada herramienta que aprende aterriza en el registro de herramientas del agente bajo un prefijo `mcp__<server-id>__<tool>` a prueba de colisiones, que se puede buscar por intención a través 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}"
+}
+```
+
+> La dirección opuesta (convertir _tu_ aplicación en un servidor MCP que otros hosts consumen) se encuentra en [MCP Protocol](/docs/mcp-protocol) y [External Agents](/docs/external-agents).
+
+## Explorador integrado y capacidades de uso de computadora {#built-in-capabilities}
+
+El agente nativo incluye opciones de desarrollo local para servidores stdio MCP comunes.
+Están desactivados de forma predeterminada y se pueden habilitar por usuario o solo por organización
+cuando la aplicación se ejecuta localmente. Se omiten los tiempos de ejecución alojados y de producción sin servidor
+estos elementos integrados incluso si existen filas de configuración antiguas y los recursos del espacio de trabajo
+El árbol no los muestra como recursos `mcp-servers/*.json` predeterminados.
+
+| Capacidad                            | Identificación del servidor | Comando                                                                 |
+| ------------------------------------ | --------------------------- | ----------------------------------------------------------------------- |
+| Herramientas de desarrollo de Chrome | `chrome-devtools`           | `npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics` |
+| Navegador de dramaturgos             | `playwright`                | `npx -y @playwright/mcp@latest`                                         |
+| Uso de la computadora                | `computer-use`              | `npx -y computer-use-mcp@latest`                                        |
+
+Solo se puede habilitar una capacidad del navegador en un ámbito a la vez. Al habilitar Chrome DevTools se deshabilita Playwright para ese mismo usuario u organización, y al habilitar Playwright se deshabilita Chrome DevTools.
+
+El uso de la computadora es solo para macOS. En otras plataformas, aparece como no disponible y se omite incluso si una fila de configuración anterior lo contiene.
+
+Chrome DevTools usa `--autoConnect` de forma predeterminada. Eso se adjunta a una instancia de Chrome en ejecución elegible; no crea un perfil de navegador aislado ni inicia sesión en el perfil habitual del usuario por usted. Requiere Chrome 144+ con la depuración remota habilitada. Se puede agregar una configuración manual de `browser-url` más adelante cuando una implementación necesite un punto final de depuración específico.
+
+Las funciones integradas se conservan en la tabla `settings` del marco en `u:<email>:mcp-builtin-capabilities` para alternancias personales y `o:<orgId>:mcp-builtin-capabilities` para alternancias de equipo. Cuando están habilitados, se fusionan en el administrador de tiempo de ejecución MCP con el mismo formato de visibilidad de alcance que los servidores remotos, por ejemplo, `mcp__user_<emailhash>_playwright__*` o `mcp__org_<orgId>_chrome-devtools__*`.
+
+### Notas de configuración para el usuario
+
+Utilice una copia de configuración explícita y concisa para las funciones integradas sensibles:
+
+- **Chrome DevTools** se adjunta a un destino de depuración de Chrome en ejecución. Informar a los usuarios
+  está destinado a pruebas de navegador y verificación de inicio de sesión, y que
+  Es posible que sea necesario habilitar la depuración remota de Chrome antes de que aparezcan las herramientas.
+- **Dramaturgo** inicia un navegador aislado. Lo recomiendo para determinista
+  Control de calidad cuando no se requiere el perfil activo de Chrome del usuario.
+- **Uso de computadora** puede operar aplicaciones locales. Manténgalo desactivado de forma predeterminada, explique el
+  Indicaciones de accesibilidad y grabación de pantalla de macOS, y pregunte antes de tomar
+  actions sensibles como compras, cambios financieros o cambios de cuenta.
+
+### Puntos finales integrados
+
+| Método | Ruta                         | Propósito                                                                                                       |
+| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| GET    | `/_agent-native/mcp/builtin` | Enumere las capacidades integradas, los ámbitos habilitados, los identificadores combinados y el estado activo. |
+| POST   | `/_agent-native/mcp/builtin` | Actualizar un alcance. Cuerpo: `{ scope, enabledIds }` o `{ scope, id, enabled }`.                              |
+
+## Agregar un servidor MCP local {#adding-a-server}
+
+Cree `mcp.config.json` en la raíz de su espacio de trabajo (o en la raíz de una aplicación individual; la raíz del espacio de trabajo gana cuando ambas existen):
+
+```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",
+      ],
+    },
+  },
+}
+```
+
+La forma es pequeña: un mapa `servers` codificado por ID de servidor, donde cada entrada es un iniciador estándar (`command` + `args` + `env` opcional) o una entrada remota `{ "type": "http", "url", "headers" }`.
+
+```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." }
+  ]
+}
+```
+
+En el siguiente inicio de la aplicación verás:
+
+```
+[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
+```
+
+Las herramientas están registradas en el registro de herramientas del agente con el prefijo `mcp__<server-id>__<tool-name>` para que no puedan colisionar con el actions de su plantilla. También se incluyen en `tool-search`, por lo que los agentes pueden descubrir capacidades MCP recién conectadas por intención en lugar de necesitar el nombre exacto con el prefijo por adelantado.
+
+## Precedencia de configuración {#precedence}
+
+La configuración MCP se resuelve en este orden, el primer partido gana:
+
+1. **Raíz del espacio de trabajo `mcp.config.json`**: detectado a través de `agent-native.workspaceCore` en `package.json`. Compartido en todas las aplicaciones del espacio de trabajo.
+2. **App-root `mcp.config.json`**: anulación por aplicación si no desea que haya un servidor MCP disponible en cada aplicación.
+3. **`MCP_SERVERS` env var**: cadena JSON con la misma forma, para CI/producción donde un archivo no tiene sentido.
+
+## Implementaciones de producción: `MCP_SERVERS` {#mcp-servers-env}
+
+Para implementaciones de producción, prefiera servidores HTTP MCP remotos y configure la configuración completa
+forma (o el mapa del servidor interno) como una variable de entorno:
+
+```bash
+MCP_SERVERS='{"servers":{"zapier":{"type":"http","url":"https://mcp.example.com/mcp","headers":{"Authorization":"Bearer paste-token-value-here"}}}}'
+```
+
+`MCP_SERVERS` se analiza como JSON, por lo que los marcadores de posición `${...}` no se expanden
+dentro de la cadena. Si almacena el token en otro secreto, expándalo antes
+escribiendo el valor final de JSON.
+
+Los servidores Stdio MCP generan archivos binarios locales y están pensados para el desarrollo local.
+Las herramientas MCP solo se activan en tiempos de ejecución de Node: Cloudflare Workers y otras ventajas
+Los objetivos omiten silenciosamente MCP y continúan con el resto de la aplicación funcionando
+normalmente.
+
+## Detección automática: `claude-in-chrome` {#autodetect}
+
+Si **no** tiene `mcp.config.json` y el binario `claude-in-chrome-mcp` está en `PATH` (o en la conocida ubicación de instalación `~/.claude-in-chrome/bin/claude-in-chrome-mcp`), el agente nativo lo registra automáticamente como servidor MCP predeterminado. Configure `AGENT_NATIVE_DISABLE_MCP_AUTODETECT=1` para excluirse.
+
+Esto significa que los usuarios que han instalado la extensión claude-in-chrome obtienen control del navegador en cada aplicación nativa del agente que abren sin cambios de configuración.
+
+## Servidores MCP remotos a través de la configuración UI {#remote-via-ui}
+
+Los servidores MCP (Protocolo de contexto modelo) le brindan a su agente nuevas capacidades, como conectarse a Zapier, Cloudflare, Composio o las herramientas internas de su empresa. Una vez conectado, el agente puede utilizar esas herramientas al igual que las integradas.
+
+### Cómo conectar un servidor MCP remoto
+
+1. **Nombre del servidor**: una etiqueta breve para su propia referencia (por ejemplo, "zapier", "slack-tools").
+2. **URL**: el punto final HTTPS que le proporcionó el proveedor del servidor MCP (por ejemplo, `https://mcp.zapier.com/s/abc123/mcp`). Esto generalmente se encuentra en el panel del proveedor o en los documentos de integración.
+3. **Descripción** (opcional): una nota sobre lo que hace este servidor.
+4. **Encabezados**: credenciales de autenticación que requiere el servidor, una por línea. La mayoría de los servidores necesitan un encabezado `Authorization`. Ejemplo: `Authorization: Bearer sk-your-key-here`. Los documentos del proveedor le indicarán qué poner aquí.
+
+Haga clic en **Probar** para verificar la conexión antes de guardar. Si tiene éxito, verá la cantidad de herramientas disponibles. Haga clic en **Conectar** para agregarlo.
+
+### Ámbito personal frente a organización
+
+Se admiten dos ámbitos:
+
+- **Personal**: solo el usuario que ha iniciado sesión obtiene las herramientas. Almacenado como una configuración de ámbito de usuario.
+- **Equipo**: todos los miembros de la organización activa obtienen las herramientas. Los propietarios y administradores pueden agregar; los miembros ven la lista como de solo lectura. Almacenado como una configuración del ámbito de la organización.
+
+Agrega y elimina la recarga en caliente en el administrador MCP en ejecución: sin reinicio del proceso ni reinicio del servidor. Las nuevas herramientas `mcp__<scope>-<name>__*` le aparecen al agente en el siguiente mensaje y se pueden buscar a través de `tool-search`.
+
+HTTPS URL se aceptan en todas partes; `http://` simple solo se permite para `localhost` durante el desarrollo. La autenticación opcional se ingresa como un token de portador que se envía a través de `Authorization: Bearer …` en cada solicitud.
+
+En el fondo, estos servidores persisten en la tabla `settings` del marco bajo la clave `u:<email>:mcp-servers-remote` (Personal) o `o:<orgId>:mcp-servers-remote` (Equipo) y se fusionan con `mcp.config.json` al inicio.
+
+### Puntos finales HTTP
+
+| Método | Ruta                                                  | Propósito                                                                                 |
+| ------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| GET    | `/_agent-native/mcp/servers`                          | Enumera los servidores personales y de organización del usuario actual con estado activo. |
+| POST   | `/_agent-native/mcp/servers`                          | Agregar un servidor. Carrocería: `{ scope, name, url, headers?, description? }`.          |
+| DELETE | `/_agent-native/mcp/servers/:id?scope=user\|org`      | Remove a server and reconfigure the manager.                                              |
+| POST   | `/_agent-native/mcp/servers/:id/test?scope=user\|org` | Dry-run the existing server's connect + list-tools.                                       |
+| POST   | `/_agent-native/mcp/servers/test`                     | Ejecute en seco un URL arbitrario antes de persistir. Cuerpo: `{ url, headers? }`.        |
+
+Los servidores Stdio todavía no funcionan fuera de los tiempos de ejecución de Node, pero los servidores remotos HTTP MCP funcionan en cualquier entorno con `fetch`, incluidas las versiones de producción de escritorio.
+
+## Servidores MCP compartidos a través de un concentrador {#hub}
+
+Si su espacio de trabajo ejecuta varias aplicaciones nativas del agente (por ejemplo, envío + correo + clips), puede configurar **una** aplicación como centro y hacer que las demás extraigan sus servidores MCP de alcance organizativo automáticamente. No se permite copiar y pegar por aplicación URL ni tokens al portador. Consulte [Multi-App Workspace](/docs/multi-app-workspace) para conocer el enfoque canónico que utiliza los recursos MCP del espacio de trabajo de envío.
+
+El envío es el centro convencional: ya coordina todas las aplicaciones.
+
+```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 configuraciones de espacios de trabajo nuevos, prefiera **Enviar recursos MCP del espacio de trabajo** cuando
+quiero el mismo modelo de concesión para todas las aplicaciones y para aplicaciones seleccionadas que utiliza el espacio de trabajo skills
+instrucciones y recursos de referencia. Agregue un recurso de espacio de trabajo con:
+
+```json
+{
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
+  },
+  "description": "Shared MCP tools for workspace apps"
+}
+```
+
+Guárdelo en `mcp-servers/<name>.json` con el tipo `mcp-server`. Todas las aplicaciones
+los recursos los carga cada aplicación del espacio de trabajo; los recursos seleccionados se cargan sólo en
+aplicaciones con una concesión de envío activa. Los marcadores de posición secretos se resuelven desde la aplicación
+almacenamiento secreto, así que coloque tokens de portador sin procesar en Dispatch Vault y haga referencia a ellos
+con `${keys.NAME}` en lugar de almacenarlos en el cuerpo del recurso.
+
+Las aplicaciones actualizan su configuración MCP fusionada aproximadamente una vez por minuto, por lo que es un recurso central
+las ediciones, los cambios de concesión y las eliminaciones entran en vigor sin una implementación. Establecer
+`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` para deshabilitar esa actualización en segundo plano, o
+configúrelo en un valor de al menos `5000` milisegundos para ajustar el intervalo.
+
+El modo central anterior que aparece a continuación sigue siendo útil para "compartir cada ámbito de organización MCP
+servidor de Dispatch” y para implementaciones que ya utilizan el MCP
+configura UI como fuente de la verdad.
+
+### 1. Habilite hub-serve en la aplicación hub (despacho)
+
+Establezca una var de entorno en la implementación de despacho:
+
+```bash
+AGENT_NATIVE_MCP_HUB_TOKEN=<a-long-random-secret>
+```
+
+Dispatch ahora monta `GET /_agent-native/mcp/hub/servers`, que devuelve cada servidor MCP del ámbito de la organización almacenado en su tabla `settings`, con encabezados URL + completos, autenticados por el token.
+
+### 2. Aplicaciones que consumen puntos en el centro
+
+Establecer en cada consumidor (correo, clips, lo que sea):
+
+```bash
+AGENT_NATIVE_MCP_HUB_URL=https://dispatch.acme.com
+AGENT_NATIVE_MCP_HUB_TOKEN=<the-same-secret>
+```
+
+Al inicio, cada consumidor extrae la lista de servidores del concentrador y la combina en su propio administrador MCP. Las herramientas aparecen para el agente como `mcp__hub_<orgId>_<name>__*`, distintas del `mcp__org_…` local del consumidor, por lo que no hay colisiones.
+
+### 3. Lo que se comparte
+
+Solo se comparten servidores de **ámbito de organización**. Los servidores de ámbito de usuario (personales) permanecen con el usuario que los agregó; el centro nunca vuelve a exponer las credenciales personales en todas las aplicaciones.
+
+Las respuestas del Hub incluyen los encabezados de autenticación completos (tokens de portador, etc.). El transporte es HTTPS, el punto final requiere el secreto compartido y solo devuelve filas del alcance de la organización; trate el token URL + del concentrador como una credencial de base de datos.
+
+### 4. Recarga en caliente vs reinicio
+
+El UI local agrega recarga en caliente en cada aplicación a través de `McpClientManager.reconfigure()`, sin reinicio. Los servidores de origen central son seleccionados por la misma actualización periódica en segundo plano (aproximadamente 60 s, ajustable o deshabilitable a través de `AGENT_NATIVE_MCP_CONFIG_REFRESH_MS`) que utiliza la ruta de recursos del espacio de trabajo, por lo que los cambios realizados en Dispatch se propagan a todas las aplicaciones de consumo en aproximadamente un minuto sin reiniciar. Además, cualquier mutación local en una aplicación de consumo activa inmediatamente una reconfiguración de esa aplicación.
+
+### Resumen de puntos finales
+
+| Método | Ruta                             | Propósito                                                                                                                                                                       |
+| ------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GET    | `/_agent-native/mcp/hub/servers` | Servir a todos los servidores del ámbito de la organización con credenciales completas (con acceso al portador, solo montado cuando se configura `AGENT_NATIVE_MCP_HUB_TOKEN`). |
+| GET    | `/_agent-native/mcp/hub/status`  | Devuelve `{ serving, consuming, hubUrl }` para la tarjeta UI de configuración.                                                                                                  |
+
+## Ruta de estado {#status-route}
+
+Cada aplicación expone `GET /_agent-native/mcp/status` para herramientas e incorporación:
+
+```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": {}
+}
+```
+
+Utilice esto para crear sugerencias de incorporación de "Claude-in-chrome detectado: su agente ahora puede manejar Chrome" o depurar problemas de conexión de MCP.
+
+## Modos de fallo {#failures}
+
+Las fallas individuales del servidor MCP nunca desactivan el agente:
+
+- Un `command` mal configurado → se omite el servidor, su error aparece en `/mcp/status` debajo de `errors.<server-id>` y todos los demás servidores continúan funcionando.
+- Falta el MCP SDK en `node_modules` → todas las funciones de MCP se omiten con una advertencia; El chat del agente sigue funcionando sin herramientas MCP.
+- Ejecutar en un tiempo de ejecución perimetral → El cliente MCP no funciona.
+
+El agente nativo siempre arrancará; La configuración rota de MCP solo significa menos herramientas.
+
+## Seguridad {#security}
+
+Las herramientas MCP se ejecutan en su máquina con cualquier permiso que tenga el proceso generado. Trate a `mcp.config.json` como cualquier otra lista de ejecutables que esté dispuesto a dejar que el agente maneje. Las herramientas de los servidores MCP aparecen en el bucle de uso de herramientas del agente al igual que el actions de su plantilla, así que asegúrese de confiar en cada servidor que configure.

package/corpus/core/docs/content/locales/es-ES/mcp-protocol.md

@@ -0,0 +1,279 @@
+---
+title: "Protocolo MCP"
+description: "Exponga su aplicación nativa del agente como un servidor MCP remoto para que Claude, ChatGPT, Claude Code, Cursor y otras herramientas de inteligencia artificial puedan llamar al actions de su aplicación directamente."
+---
+
+# Protocolo MCP
+
+**Esta página: la referencia del servidor MCP de nivel inferior.** Cómo cada aplicación nativa del agente expone su actions sobre MCP: el punto final montado automáticamente, los modos de autenticación, la superficie `tools/call`/`ask-agent` y el montaje personalizado. Consíguelo cuando necesites componentes internos del servidor; para conectar un host, comience con [External Agents](/docs/external-agents).
+
+| Si quieres…                                                                                        | Leer                                     |
+| -------------------------------------------------------------------------------------------------- | ---------------------------------------- |
+| Conecta un agente/host externo a tu aplicación                                                     | [External Agents](/docs/external-agents) |
+| Dale a tu agente más herramientas (consume otros servidores MCP)                                   | [MCP Clients](/docs/mcp-clients)         |
+| Crea UI en línea que se rendericen en Claude/ChatGPT                                               | [MCP Apps](/docs/mcp-apps)               |
+| Referencia del servidor MCP de nivel inferior (autenticación, herramientas, montaje personalizado) | **Esta página** — Protocolo MCP          |
+
+Cada aplicación nativa del agente expone automáticamente un servidor remoto MCP (Protocolo de contexto de modelo), por lo que herramientas externas de IA como Claude, aplicaciones MCP personalizadas ChatGPT, código Claude, cursor, Codex y VS Code GitHub Copilot pueden descubrir y llamar al actions de su aplicación directamente, sin necesidad de código adicional. Si su objetivo es _conectar_ uno de esos hosts a una aplicación alojada, [External Agents](/docs/external-agents) cubre el conector de envío único recomendado, URL, OAuth, MCP aplicaciones en línea UI por aplicación y enlaces profundos. Esta página documenta lo que hay debajo.
+
+## Descripción general {#overview}
+
+MCP es el protocolo estándar para conectar herramientas de IA a capacidades externas. Cuando implementa una aplicación nativa del agente, monta automáticamente un punto final MCP junto con el punto final A2A existente. Cualquier cliente compatible con MCP puede conectarse y utilizar las herramientas de su aplicación.
+
+Conceptos clave:
+
+- **Montado automáticamente**: cada aplicación obtiene `/_agent-native/mcp` gratis, no requiere configuración
+- **HTTP transmitible**: utiliza el transporte moderno MCP sobre el estándar HTTP (POST + SSE)
+- **Mismo actions**: exactamente el mismo registro de acciones que impulsa el chat del agente y A2A
+- **Herramienta `ask-agent`**: una metaherramienta que delega al ciclo completo del agente para tareas complejas
+- **Aplicaciones MCP**: actions puede anunciar recursos interactivos de UI a través de la extensión oficial `io.modelcontextprotocol/ui`
+- **MCP remoto estándar OAuth**: descubrimiento de OAuth 2.1, registro dinámico de cliente, código de autorización + PKCE, rotación de token de actualización
+- **Reserva de autenticación de portador**: utiliza `ACCESS_TOKEN`, `ACCESS_TOKENS` o JWT conectados para clientes que no pueden ejecutar 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 frente a A2A {#mcp-vs-a2a}
+
+Ambos protocolos se montan automáticamente. Utilice el que se ajuste a su caso de uso:
+
+|                                    | MCP                                                                   | A2A                                                 |
+| ---------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------- |
+| **Mejor para**                     | Herramientas externas que llaman a tu aplicación                      | Comunicación de agente a agente                     |
+| **Protocolo**                      | MCP HTTP transmitible                                                 | JSON-RPC 2.0                                        |
+| **Descubrimiento de herramientas** | `tools/list`                                                          | Tarjeta de agente en `/.well-known/agent-card.json` |
+| **Punto final**                    | `/_agent-native/mcp`                                                  | `/_agent-native/a2a`                                |
+| **Con el apoyo de**                | Claude, ChatGPT, Claude Code, Cursor, Codex, Cowork y otros hosts MCP | Otras aplicaciones nativas del agente               |
+| **Ejecución**                      | Llamadas directas a herramientas (sin LLM adicionales)                | Bucle de agente completo (razonamiento LLM)         |
+
+También puedes usar la herramienta `ask-agent` MCP para obtener lo mejor de ambos mundos: llámala desde el código Claude y deja que el agente de tu aplicación razone a través de tareas complejas.
+
+## Configuración manual del cliente MCP {#manual-config}
+
+Para la configuración de un solo comando recomendada, utilice [External Agents](/docs/external-agents). Si está escribiendo a mano la configuración de MCP para un cliente compatible con OAuth, agregue su aplicación como un servidor MCP remoto sin encabezados estáticos:
+
+```bash
+claude mcp add --transport http mail https://mail.example.com/_agent-native/mcp
+```
+
+O escriba la entrada a mano en `.mcp.json` (alcance del proyecto) o `~/.claude.json` (alcance del usuario):
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "mail": {
+      "type": "http",
+      "url": "https://mail.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+Luego ejecute `/mcp` en el código Claude y elija **Autenticar**. Para los clientes que no pueden realizar MCP OAuth remoto, utilice la página Conectar o una entrada de token de portador estático con `headers.Authorization`. Una vez autenticado, podrás utilizar las herramientas de tu aplicación de forma natural:
+
+```
+> draft an email to John about the Q3 report
+
+Claude Code calls: draft-email(to: "john@example.com", subject: "Q3 Report", body: "...")
+```
+
+## Conectarse desde otros clientes MCP {#other-clients}
+
+Cualquier cliente MCP que admita el transporte Streamable HTTP puede conectarse. El punto final es:
+
+```
+POST https://your-app.example.com/_agent-native/mcp
+```
+
+El servidor admite el protocolo de enlace estándar MCP: `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." }
+  ]
+}
+```
+
+Si una acción declara `mcpApp`, el servidor también anuncia la extensión oficial de aplicaciones MCP (`io.modelcontextprotocol/ui`) y admite `resources/list`, `resources/templates/list` y `resources/read` para el recurso de la aplicación. Los hosts que procesan aplicaciones MCP pueden mostrar el UI en línea; los hosts que no lo hacen aún pueden llamar a la herramienta y utilizar el respaldo de enlace profundo. Los productos UI deben usar `embedApp()` para que la superficie en línea sea la ruta real de la aplicación React, o una ruta enfocada que represente un componente React compartido, como un gráfico de análisis, no una implementación simple independiente de HTML. El servidor emite metadatos de aplicaciones MCP estándar y metadatos de compatibilidad de aplicaciones ChatGPT SDK para que los hosts compatibles con aplicaciones puedan encontrar el mismo recurso `ui://`. La matriz de extensión oficial actual incluye Claude, Claude Desktop, VS Code GitHub Copilot, Goose, Postman, MCPJam, ChatGPT y Cursor; La compatibilidad con el host varía según la versión y el plan, así que utilice el [External Agents MCP Apps notes](/docs/external-agents#mcp-apps-compatibility) para obtener orientación para el usuario.
+
+### MCP Puente para insertar aplicaciones {#mcp-app-embed-bridge}
+
+`embedApp()` es el primer asistente de aplicación MCP de bajo nivel para URL: inicia una aplicación firmada
+ruta en línea mediante trasplante (Claude), marco controlado (ChatGPT) o directo
+navegación, media el host actions sobre el puente `ui/*` JSON-RPC (y el
+`agentNative.mcpHost.*` retransmisión postMessage para la ruta de trama controlada), y
+fija la altura del shell de recursos para que una ruta de aplicación completa no se represente como
+artefacto de chat de gran tamaño.
+
+Consulte [MCP Apps](/docs/mcp-apps#mcp-app-bridge) para obtener detalles completos del puente de inserción: trasplante versus marco controlado, las tablas `ui/*` y postMessage, `create_embed_session` / `embedStartUrl`, CSP y reglas de dominio, incorporación de extensión `srcDoc`, sujeción de altura y el cliente de puente host API.
+
+## Herramientas {#tools}
+
+Cada persona que llama recibe un **catálogo compacto de forma predeterminada** (aplicación declarada por plantilla actions más las funciones integradas entre aplicaciones), con la superficie de acción completa disponible solo mediante suscripción explícita y `tool-search` siempre disponible para comunicarse con el resto. Consulte [External Agents → Catalog tiers](/docs/external-agents#catalog-tiers) para obtener la explicación completa.
+
+Cada acción se asigna directamente a una herramienta MCP:
+
+| Propiedad de acción | Propiedad de herramienta MCP |
+| ------------------- | ---------------------------- |
+| `tool.description`  | `description`                |
+| `tool.parameters`   | `inputSchema`                |
+| Nombre de la acción | Nombre de la herramienta     |
+
+Cuando `mcpApp` está presente, la entrada de herramienta también incluye `_meta.ui.resourceUri`, `_meta["ui/resourceUri"]` y `_meta["openai/outputTemplate"]`, y el recurso `ui://` correspondiente se devuelve como `text/html;profile=mcp-app`.
+
+### La herramienta `ask-agent` {#ask-agent}
+
+Además de las herramientas de acción individuales, cada servidor MCP incluye una metaherramienta `ask-agent`. Esto envía un mensaje en lenguaje natural al agente de inteligencia artificial de la aplicación y devuelve la respuesta.
+
+Utilice `ask-agent` para tareas complejas que se beneficien del razonamiento y el contexto del 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"
+  }
+}
+```
+
+El agente ejecuta el mismo ciclo que el chat interactivo: puede llamar a múltiples herramientas, razonar sobre el contexto y producir una respuesta reflexiva.
+
+## Autenticación {#authentication}
+
+El punto final MCP admite MCP OAuth remoto estándar más el respaldo de token de portador existente:
+
+| Modo                                          | Cómo funciona                                                                                                                     |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Estándar MCP OAuth                            | El cliente descubre la autenticación de `WWW-Authenticate`, registra, ejecuta PKCE y envía `Authorization: Bearer <access-token>` |
+| JWT creado por Connect                        | `npx @agent-native/core@latest connect` / la página Conectar crea un JWT revocable por usuario                                    |
+| `ACCESS_TOKEN`                                | Token de portador estático: el cliente envía `Authorization: Bearer <token>`                                                      |
+| `ACCESS_TOKENS`                               | Lista separada por comas de tokens portadores estáticos válidos                                                                   |
+| `A2A_SECRET`                                  | Autenticación basada en JWT: los tokens se verifican criptográficamente                                                           |
+| _(ninguno establecido, solo bucle invertido)_ | No se requiere autenticación para las sondas de desarrollo local                                                                  |
+
+Para hosts MCP compatibles con OAuth, configure el servidor remoto URL sin encabezados estáticos:
+
+```bash
+claude mcp add --transport http agent-native https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+La primera solicitud MCP no autenticada recibe:
+
+```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"
+```
+
+Puntos finales de descubrimiento:
+
+| Punto final                               | Propósito                                                        |
+| ----------------------------------------- | ---------------------------------------------------------------- |
+| `/.well-known/oauth-protected-resource`   | RFC 9728 metadatos de recursos protegidos                        |
+| `/.well-known/oauth-authorization-server` | Metadatos del servidor de autorización OAuth                     |
+| `/_agent-native/mcp/oauth/register`       | Registro dinámico de cliente público                             |
+| `/_agent-native/mcp/oauth/authorize`      | Autorización del navegador + consentimiento                      |
+| `/_agent-native/mcp/oauth/token`          | Concesiones de códigos de autorización y tokens de actualización |
+
+```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}"
+}
+```
+
+Los tokens de acceso son JWT firmados cuya audiencia es exactamente el recurso MCP URL. El servidor acepta solo tokens emitidos por sí mismo y aplica alcances antes de enumerar/llamar herramientas:
+
+| Alcance     | Permite                                              |
+| ----------- | ---------------------------------------------------- |
+| `mcp:read`  | actions de solo lectura                              |
+| `mcp:write` | mutando actions y `ask-agent`                        |
+| `mcp:apps`  | Recursos de aplicaciones MCP (recursos `ui://` HTML) |
+
+Los tokens de actualización se almacenan solo como hashes y se rotan en cada actualización. `npx @agent-native/core@latest connect` escribe esta entrada OAuth exclusiva de URL para clientes de código Claude de forma predeterminada; mantenga la página Conectar, `npx @agent-native/core@latest connect --token <token>` y la configuración del portador estático para el proxy stdio local, clientes antiguos y flujos de emergencia/depuración.
+
+## Configuración personalizada de MCP {#custom-setup}
+
+El servidor MCP se monta automáticamente mediante el complemento de chat del agente. Para la mayoría de las aplicaciones, no se necesita configuración. Si necesita un comportamiento personalizado, puede montarlo manualmente en un complemento del 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",
+  });
+});
+```
+
+## Ejemplo: análisis del código Claude {#example}
+
+Tiene una aplicación de análisis implementada en `analytics.example.com`. Del código Claude:
+
+```bash
+claude mcp add --transport http analytics https://analytics.example.com/_agent-native/mcp
+```
+
+O agregarlo a mano en `.mcp.json`:
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "analytics": {
+      "type": "http",
+      "url": "https://analytics.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+Ahora en 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álisis más complejos:
+
+```
+> 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
+```