# Agentes reales, MCP propio y pruebas de velocidad

El modelo, el servidor y el programa que lo usa son tres componentes distintos. Entrenar un LoRA no corrige automáticamente un contrato HTTP incompatible, una plantilla equivocada o un cliente que interpreta mal el streaming. Este taller empieza por el endpoint instalado y termina con una herramienta propia que exige tu llave.

**Material del taller:** [kit de réplica y ejemplos](../../downloads/ia-lab-replica-v4.7.zip). No contiene credenciales. Las pruebas nuevas son sintéticas y acotadas; no se reinició ni reconfiguró llama.cpp.

[TOC]

## 1. Línea base comprobada en GPU 0

El 23 de septiembre se ejecutó `examples/canary.py` contra el mismo `ornith-local` servido por llama.cpp. La salida está en `canary-gpu0.json` dentro del kit.

| Caso | Resultado | Tiempo observado |
|---|---|---|
| Chat | `stop`, contenido CANARIO_OK | 351 ms |
| Primera herramienta | `tool_calls`, JSON exacto 17 + 25 | 672 ms |
| Segunda herramienta | `tool_calls`, JSON exacto 42 + 8 | 574 ms |
| Continuación | `stop`, respuesta con 50 | 535 ms |
| Historial | recupera HISTORIAL_OK | 388 ms |
| Streaming | contenido STREAM_OK, `stop` y `[DONE]` | 255 ms al primer texto, 283 ms total |

Estos son **seis ejemplos cortos**, con elección de herramienta forzada y sumas puras ejecutadas por el test. No prueban selección autónoma de herramientas, desempeño en un repositorio ni latencia p95. La segunda llamada aprovechó caché; no se compara como si fuera una primera solicitud fría. Para repetir:

```bash
python3 examples/canary.py --base http://127.0.0.1:8120/v1 \
  --model ornith-local --out prueba-nueva.json
```

El archivo de salida debe ser nuevo. Si hay autenticación en tu proxy, establece `ATLAS_API_KEY` mediante tu gestor de secretos; el ejemplo la lee del entorno. El endpoint actual inspeccionado no exige esa llave. Poner `apiKey: local-no-auth` en un cliente **no protege** un servidor abierto.

## 2. OpenCode: sí existe un perfil real

La búsqueda inicial en el directorio predeterminado fue insuficiente. Recuperamos `/home/lab/bench/ornith/opencode-lab/config/opencode.json` y `env.sh`. El perfil apunta a `http://127.0.0.1:8120/v1`, usa `local-ornith/ornith-local` y declara herramientas, contexto 262144 y salida 16384. El servidor observado limita su salida a 4096: esa diferencia se debe revisar, no atribuir al modelo.

El esquema de la CLI instalada **2.0.5** usa `providers` → `package: @opencode/ai/providers/openai-compatible` → `settings`. El archivo recuperado está completo en `evidence/historical/opencode-lab/config/opencode.json`. La documentación web consultada presenta otro esquema (`provider`, `npm`, `options`); no mezcles ambos a ciegas. Valida contra la versión que instalaste. [Proveedores de OpenCode](https://opencode.ai/docs/providers/).

Para reproducir el contexto histórico en la réplica, restaura los archivos en su ruta o adapta **todos** los paths del `env.sh`, luego:

```bash
source /home/lab/bench/ornith/opencode-lab/env.sh
opencode --version
opencode run --help
opencode run --standalone --format json \
  --model local-ornith/ornith-local \
  'No uses herramientas. Responde exactamente OPENCODE_CANARIO_OK.'
```

`env.sh` cambia de directorio. `OPENCODE_CONFIG_DIR` es `opencode.d`, mientras `OPENCODE_CONFIG` apunta al JSON de `config/`. Los datos/caché se aíslan con variables XDG. No ejecutes el wrapper histórico `ornith-opencode-final.sh` para esta prueba: recrea contenedores y termina procesos.

**Reproducción nueva superada:** OpenCode 2.0.5 se ejecutó con ese proveedor, configuración original de sólo lectura y directorio/caché temporales separados. Emitió el evento de texto `OPENCODE_CANARIO_OK` y terminó con código cero; el intervalo entre eventos de inicio y texto fue aproximadamente 1.3 segundos (no incluye todo el arranque de la CLI). Esta prueba cubre chat mediante el adaptador real, no herramientas autónomas ni edición de repositorios.

Hay registros históricos de seis tareas concurrentes que terminaron con código de salida cero, entre 139 y 271 segundos. Eso demuestra que hubo una integración ejecutada, pero no sustituye revisar los archivos generados y sus tests. Tampoco permite decir que el modelo “no funciona en OpenCode”. El estado de la reproducción nueva queda en el informe de verificación del kit.

## 3. Codex: Responses directo no es todavía Codex completo

La configuración predeterminada encontrada usa `gpt-5.6-terra`; no apuntaba a Ornith. La CLI instalada es **0.154.0**. Se lanzó un canario efímero, con directorio temporal, sandbox de sólo lectura y `--ignore-user-config`, usando un proveedor local explícito. No se cambió la cuenta ni el archivo de configuración del usuario.

Un POST directo a `/v1/responses` terminó con HTTP 200, estado `completed` y texto visible `RESPONSE_OK`. Sin embargo, la prueba de **Codex real** falló: primero registró metadatos de modelo incompatibles (`missing field slug` al refrescar `/models`), después cinco reconexiones y un error genérico. No se ha aislado la causa exacta de esas reconexiones. No llamar a esto “modelo incapaz” ni “adaptador validado”.

La documentación actual define `wire_api="responses"`. El perfil de laboratorio, pasado sólo en la invocación, fue:

```toml
model = "ornith-local"
model_provider = "ornith_atlas"
[model_providers.ornith_atlas]
name = "Ornith Atlas probe"
base_url = "http://127.0.0.1:8120/v1"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
```

Esto describe **la prueba fallida**, no una configuración promovida. Próxima prueba: trazar estados y tipos de eventos de Responses, sin guardar secretos ni razonamiento privado; comparar el contrato que exige esta versión de Codex con el que entrega este commit de llama.cpp. Después probar una tarea de código con checker. Cambiar los pesos antes de resolver el transporte haría más difícil atribuir el fallo. [Referencia oficial de configuración](https://developers.openai.com/codex/config-reference/).

## 4. DeepSeek Harness y habilidades

También existe `/home/lab/.dsh/profiles/web`; no era correcto concluir que no había Harness por no encontrarlo en otras rutas. El kit incluye su `package.json` y el [manual de panel y terminales](../../operar-ia-lab/terminales/). Un paquete instalado o un puerto abierto no demuestra la ejecución completa de herramientas desde el navegador.

Para probar cualquier harness, usa la misma progresión: mensaje simple → una herramienta sin efectos externos → resultado → segunda herramienta → historial → SSE → tarea de código con tests → cancelación/reintento. Guarda versión del cliente, plantilla, modelo, solicitud anonimizada, resultado del checker y terminación. Las instrucciones/skills ayudan a encaminar el agente; el dataset debe enseñar contratos y recuperación de errores, no sólo respuestas bonitas.

Práctica propuesta: en un repositorio **de pruebas**, pedir implementar `normalizar_nombre`, comprobar espacios, acentos y entrada vacía con tests preparados antes. Repetir baseline y candidato con la misma tarea. No ejecutar código generado con acceso a credenciales, shell de producción o directorios personales. La [lección de datasets](../datasets/) explica cómo separar entrenamiento y evaluación.

## 5. Crear un MCP propio con autenticación

`agent-examples/mcp_server.py` implementa dos herramientas: `sumar` y `perfiles_documentados`. La segunda devuelve un inventario fechado con `live:false`: no finge consultar la GPU. No tiene shell, escritura de archivos ni control de servicios. Usa el SDK oficial MCP 2.2.0, HTTP en localhost y una barrera Bearer que rechaza solicitudes sin la llave.

```bash
python3 -m venv .venv-mcp
.venv-mcp/bin/pip install -r agent-examples/requirements.txt
cd agent-examples
../.venv-mcp/bin/python -m unittest -v test_mcp.py
# bash: introduce una llave aleatoria de al menos 24 caracteres sin mostrarla.
read -r -s -p 'Llave MCP: ' ATLAS_MCP_KEY
printf '\n'
export ATLAS_MCP_KEY
../.venv-mcp/bin/python mcp_server.py
```

Mantén esa terminal abierta. En otra, introduce **la misma llave**, expórtala y realiza la inicialización:

```bash
curl --fail-with-body http://127.0.0.1:8766/mcp \
  -H "Authorization: Bearer $ATLAS_MCP_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"atlas-curl","version":"1"}}}'
```

Después de inicializar, el cliente MCP normal envía `notifications/initialized`. Para esta demostración HTTP **sin estado de sesión**, puedes enviar esa notificación con el mismo encabezado y luego consultar:

```bash
curl --fail-with-body http://127.0.0.1:8766/mcp \
  -H "Authorization: Bearer $ATLAS_MCP_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sumar","arguments":{"a":17,"b":25}}}'
```

Resultado esperado: 42. Repite **sin** Authorization: debe devolver 401. No metas la llave en la URL, los prompts, el HTML, el repositorio o el ZIP. En un host multiusuario, evita además exponerla en argumentos visibles del proceso: usa el cliente MCP/gestor de secretos o un archivo temporal de configuración curl con permisos 0600. Al terminar, detén este servidor con Ctrl+C y `unset ATLAS_MCP_KEY`.

Este Bearer compartido es una demostración para tu laboratorio privado, **no una implementación del flujo OAuth de autorización MCP para terceros**. Para acceso remoto conserva el bind local y usa un túnel SSH; para un servicio multiusuario añade identidad, permisos por herramienta, expiración/rotación, TLS, cuotas y auditoría. Validar Origin/Host protege frente a DNS rebinding, no sustituye autenticación. [Transportes MCP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports), [SDK oficial](https://github.com/modelcontextprotocol/python-sdk).

## 6. Las cinco pruebas del MCP que sí se ejecutaron

Se ejecutó el servidor mediante su cliente de pruebas local, sin exponer un servicio en ia-lab: sin llave 401; llave incorrecta 401; initialize/list/call correctos y suma 42; Origin ajeno 403; ausencia de secreto impide arrancar. No se ha añadido este MCP a tus perfiles personales ni se ha probado una llamada autónoma desde OpenCode, Codex o DSH.

Para conectarlo después, registra una herramienta HTTP local en el cliente y pasa la llave desde su mecanismo de secretos. Primero confirma `tools/list`, luego `sumar`, después una herramienta real de sólo lectura. Que un curl funcione no prueba que el harness esté usando el mismo transporte y encabezados.

## 7. Responder rápido: qué medir y qué cambiar

No optimices sólo tokens por segundo. Mide primer texto visible, latencia completa de herramienta, exactitud, cancelación y percentiles con carga repetida. Separa solicitudes frías/calientes y contexto 8K/32K/128K. Un modelo que contesta rápido pero omite una herramienta o rompe el schema no cumple la tarea.

Mantén cargado un único baseline por GPU, usa schemas pequeños, no incluyas catálogos de cientos de herramientas, reutiliza conexiones y prefijos idénticos cuando proceda. Comprueba que cada cambio realmente usa el backend esperado. En esta entrega no se alteraron potencia, memoria, caché, concurrencia ni parámetros del servicio activo para prometer velocidad.

Orden de experimentos: arreglar transporte/plantilla → medir el perfil actual → variar una opción de contexto/KV/batching → comprobar calidad → evaluar distillation/LoRA/pruning por separado. MTP y DFlash son rutas distintas y no se activan por tener descargado un archivo. Conserva un resultado negativo: también evita repetir una receta que ya falló.
