# Instrucciones para el agente: MCP-UI: interfaces interactivas para herramientas MCP

Pega este texto a tu agente (Claude Code, Codex, OpenCode, Hermes o el que uses) y dile «ayúdame a montarlo». Son los pasos para ponerlo en marcha; el porqué de cada pieza está en la guía completa.

- Dificultad: avanzado
- Proyecto: https://github.com/MCP-UI-Org/mcp-ui (licencia Apache-2.0)
- Guía completa: https://lab.wisd.ai/hub/mcp-ui-interactive-apps

---

## Para el agente: cómo acompañar al usuario

1. Pregunta primero para qué lo quiere. Si su objetivo no necesita algún paso, sáltalo.
2. Antes de instalar, comprueba lo que ya tiene (versiones, claves, sistema operativo).
3. Avanza un paso cada vez: explica en una frase qué vas a hacer y deja que el usuario lo ejecute o lo apruebe.
4. Tras cada paso, comprueba que funcionó antes de seguir. Si falla, para y explica el error.
5. No inventes comandos ni opciones: si la documentación del proyecto contradice estos pasos, manda la documentación.
6. Al terminar, haz una prueba real con el objetivo del usuario y dile dónde profundizar.

---

## Pasos de configuración

### Paso 1: delimita la ruta de servidor

Usa un proyecto MCP JavaScript que ya arranque por entrada/salida estándar y VS Code con soporte MCP Apps como aplicación que muestra la interfaz. Comprueba `node --version` y `npm --version`; los manifiestos de estos SDK no declaran un mínimo Node numérico. No hace falta construir un cliente React para esta ruta.

Desde la raíz del proyecto instala las dependencias que importa el ejemplo del [README](https://github.com/MCP-UI-Org/mcp-ui#-getting-started):

```sh
npm install @mcp-ui/server @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk zod
```

### Paso 2: registra herramienta y recurso

En el módulo de tu servidor, antes de conectar su transporte, adapta el ejemplo oficial usando su instancia `server` de `McpServer`:

```js
import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server';
import { createUIResource } from '@mcp-ui/server';
import { z } from 'zod';

const widgetUI = await createUIResource({
  uri: 'ui://my-server/widget',
  content: { type: 'rawHtml', htmlString: '<h1>Interactive Widget</h1>' },
  encoding: 'text',
});
registerAppResource(server, 'widget_ui', widgetUI.resource.uri, {}, async () => ({
  contents: [widgetUI.resource]
}));
registerAppTool(server, 'show_widget', {
  description: 'Show widget',
  inputSchema: { query: z.string() },
  _meta: { ui: { resourceUri: widgetUI.resource.uri } }
}, async ({ query }) => ({
  content: [{ type: 'text', text: `Query: ${query}` }]
}));
```

Conserva el arranque y transporte del servidor existente. Se añade `show_widget` y el recurso `ui://my-server/widget`; no se crea un servicio HTTP nuevo.

### Paso 3: conecta y llama desde VS Code

En VS Code abre la paleta → MCP: Add Server → Command (stdio). Introduce el comando de arranque de ese proyecto (el que ya comprobaste en el paso 1) y guárdalo para ese espacio de trabajo. La [documentación del cliente](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) explica cómo iniciar el servidor y autorizar sus herramientas. En el chat en modo agente, habilita `show_widget` y pide: «Llama a show_widget con query igual a prueba». Acepta la ejecución de esa herramienta.

## Comprobación

La respuesta de texto debe contener `Query: prueba`; la interfaz debe mostrar `Interactive Widget`. El cliente obtiene el recurso enlazado mediante `resources/read`. Esta tarjeta estática comprueba transporte, vínculo y presentación; no demuestra acciones interactivas. Para botones y mensajes usa después los ejemplos de acciones del README.

## Si algo falla

Si aparece solo texto, revisa soporte MCP Apps y `_meta.ui.resourceUri`. Si no se descubre la herramienta, revisa primero el arranque y los registros de tu servidor. Para crear además un cliente con `@mcp-ui/client`, el manifiesto requiere React y React DOM 18 o 19 y `AppRenderer` necesita la dirección de su entorno aislado; es otra ruta, descrita en el README.