# Banco D: demo de MCP App

Servidor MCP que muestra un widget interactivo dentro de un cliente MCP (por ejemplo, Claude Desktop) para un flujo de solicitud de préstamo online. La app pertenece a **Banco D**, un banco ficticio.

Es una **demo educativa del estándar [MCP Apps (SEP-1865)](https://blog.modelcontextprotocol.io/posts/2026-01-26-mcp-apps/)**. Lo interesante no es la solicitud de préstamo en sí, sino que en un mismo flujo se muestran **tres niveles distintos** de qué ve el agente en cada paso.

> Autor: [Diego Ponce de León](https://www.linkedin.com/in/dponcedeleon/). Los datos, la marca y los cálculos son ficticios.

## Índice

- [Los tres niveles de visibilidad al agente](#los-tres-niveles-de-visibilidad-al-agente)
- [Cómo funciona la demo, paso a paso](#cómo-funciona-el-demo-paso-a-paso)
- [Instalación](#instalación)
- [Conectar a Claude Desktop](#conectar-a-claude-desktop)
- [Esta demo no es un patrón de despliegue a producción](#esta-demo-no-es-un-patrón-de-despliegue-a-producción)
- [Estructura del código](#estructura-del-código)
- [Licencia](#licencia)

## Los tres niveles de visibilidad al agente

Cada respuesta de una tool en MCP Apps tiene dos canales:

- **`content`**: texto que el agente lee.
- **`structuredContent`**: JSON que va al widget (el agente no lo ve).

Con esos dos canales y el flag `_meta.ui.visibility`, el desarrollador decide, en cada paso, qué llega al agente. Esta demo usa los tres niveles posibles.

### Nivel 1: el agente lo ve todo

En esta demo ocurre al iniciar la solicitud (`iniciar_solicitud_prestamo`). Si el usuario mencionó un monto en el chat, el agente lo pasa como `monto_sugerido` y el widget arranca con ese monto pre-llenado.

### Nivel 2: el agente ve solo el resultado

El widget captura los datos y el `content` de la tool devuelve solo el resultado agregado. Los detalles del formulario no llegan al agente.

En esta demo ocurre en la selección de plan. Cuando el usuario elige un plan en el widget, el agente recibe un texto como *"Plan elegido: 12 cuotas de S/ 320,88 (pago total S/ 3 850,56, intereses S/ 350,56)"*. Nada más.

### Nivel 3: el agente no ve nada

La tool tiene `_meta.ui.visibility=["app"]`, así que el cliente MCP la oculta del listado del agente. El agente ni siquiera sabe que la tool existe. Solo el widget la puede llamar, vía `postMessage`.

En esta demo ocurre con `autorizar_con_clave` (el PIN nunca aparece en el contexto del modelo, ni siquiera un intento fallido) y con `capturar_cuenta_destino` (el número de cuenta destino se queda dentro del widget). Cuando el flujo termina, el widget emite un `ui/message` explícito para avisar al agente del resultado final.

## Cómo funciona la demo, paso a paso

1. **Paso 1: monto y día de pago** *(nivel 1)*. El agente detecta que el usuario quiere un préstamo y llama `iniciar_solicitud_prestamo`. Si el usuario mencionó un monto en el chat, el agente lo pasa como `monto_sugerido` y el widget arranca con ese valor pre-llenado; si no, el widget arranca vacío. El usuario ajusta el día de pago y hace clic en "Ver mis opciones".

2. **Paso 2: elegir plan** *(nivel 2)*. El widget calcula 3 planes (12, 24 y 36 cuotas) con cuota mensual, total, intereses y TCEA. El usuario elige uno. El agente recibe solo el plan elegido y los tres valores comerciales del plan.

3. **Paso 3: evaluación y términos** *(nivel 2)*. El widget muestra un spinner por 2,5 segundos y transiciona a "aprobado". El usuario acepta los términos.

4. **Paso 4: autorización con PIN** *(nivel 3)*. El widget muestra un keypad numérico con countdown de 2:00. El PIN de prueba es **`1234`**. El agente no ve la tool `autorizar_con_clave` en su lista y no puede llamarla. Si el usuario ingresa mal el PIN, el widget lo indica; el agente no se entera.

5. **Paso 5: cuenta destino** *(nivel 3)*. El usuario elige a qué cuenta se acredita el préstamo y la forma de pago. Las cuentas están escritas directamente en el widget (en producción vendrían del perfil autenticado del cliente). La tool que registra la selección también es solo-widget, así que el número de cuenta no pasa por el canal del agente.

6. **Paso 6: desembolsado** *(nivel 1, cierre)*. El widget confirma el desembolso y emite un `ui/message` con el resumen: *"Préstamo desembolsado: S/ 3 500,00 en 12 cuotas de S/ 320,88 (TCEA 19,56%). Nº operación BD-XXXXXXXX. Débito automático el día 15 de cada mes."*. Con eso el agente puede continuar la conversación con contexto del cierre.

---

## Instalación

Requisitos:

- Python 3.11+
- [`uv`](https://docs.astral.sh/uv/) instalado
- Claude Desktop (macOS o Windows), o cualquier cliente compatible con MCP Apps

Clonar e instalar:

```bash
git clone https://github.com/dponcedeleonf/demo-app-mcp-prestamo.git
cd demo-app-mcp-prestamo
uv sync
```

Verificar el servidor sin conectarlo al cliente:

```bash
uv run python -m banco_d --introspect
```

Debería imprimir el UI resource, las 9 tools con su `_meta` y `visibility`, y validar que el HTML sea correcto.

## Conectar a Claude Desktop

Edita `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o `%APPDATA%\Claude\claude_desktop_config.json` (Windows) y agrega la entrada:

```json
{
  "mcpServers": {
    "banco-d": {
      "command": "uv",
      "args": [
        "--directory",
        "/ruta/absoluta/a/demo-app-mcp-prestamo",
        "run",
        "python",
        "-m",
        "banco_d"
      ]
    }
  }
}
```

Reemplaza `/ruta/absoluta/...` con la ruta real. Cierra Claude Desktop con Cmd+Q y ábrelo de nuevo. Empieza una conversación nueva y pídele un préstamo al agente. PIN de prueba: **1234**.

## Esta demo no es un patrón de despliegue a producción

Esta demo corre en **stdio con edición manual del config del cliente**. Esa no es la forma en la que un producto real se conecta a Claude Desktop u otro cliente MCP. Ninguna empresa (banco, retail, salud) le pediría a un cliente instalar Python, copiar archivos y editar `claude_desktop_config.json`.

En producción, un servidor MCP orientado a clientes se despliega sobre **HTTPS con OAuth 2.1** y se instala vía **Settings → Connectors** en Claude Desktop, claude.ai u otro cliente compatible. Ese modelo permite autenticación por usuario, multi-tenencia, auditoría, control de tráfico y actualización centralizada.

---

## Estructura del código

```
demo-app-mcp-prestamo/
├── pyproject.toml
├── README.md
├── uv.lock
└── src/banco_d/
    ├── __init__.py
    ├── __main__.py                  # punto de entrada: python -m banco_d
    ├── server.py                    # servidor MCP: registro de tools y resources
    ├── sessions.py                  # estado en memoria por session_id
    ├── prestamo/
    │   ├── __init__.py
    │   ├── state.py                 # PrestamoState + cálculo cuota francesa (TNA 18%)
    │   └── tools.py                 # 9 tools del flujo, con visibility declarada
    └── views/
        └── prestamo_view.html       # widget de 6 pantallas + keypad + countdown
```

Referencias útiles para leer el código:

- **`prestamo/tools.py`**: el docstring del módulo separa las tools visibles al agente de las que son solo del widget. Cada entrada de la lista `TOOLS` lleva un tag `[AGENTE]` o `[SOLO WIDGET]`.
- **`server.py`, función `_tool_meta`**: genera el `_meta.ui.visibility` que el cliente MCP respeta para ocultar tools del listado del agente.
- **`prestamo_view.html`, sección PANTALLA 4**: el keypad, el countdown OTP, el enlace "Solicitar nueva clave" y el emisor de `ui/message` post-autorización.
- **`prestamo_view.html`, sección MCP APPS**: descripción de cada método JSON-RPC del protocolo y quién lo manda.
- **`prestamo_view.html`, `maybeEmitUiMessage`**: cómo el widget envía texto al contexto del agente cuando decide hacerlo.

## Licencia

MIT.