Phase 13 - Lesson 23

Capstone — Construir un Ecosistema Completo de Herramientas

La Fase 13 enseñó cada pieza. Este capstone las conecta en un sistema con formato de producción: un servidor MCP con herramientas + recursos + prompts + tareas + UI, OAuth 2.1 en el borde, un gateway RBAC, un cliente multi-servidor, una llamada de subagente A2A, rastreo OTel en un colector, detección de envenenamiento de herramientas en CI y un paquete AGENTS.md + SKILL.md. Al final, podrás defender cada decisión de arquitectura.

Tipo: Build Lenguajes: Python (stdlib, end-to-end ecosystem harness) Prerrequisitos: Fase 13 · 01 a 21 Tiempo: ~120 minutos

Objetivos de Aprendizaje

Componer un servidor MCP que exponga herramientas, recursos, prompts y una tarea con una aplicación ui://.
Proteger el servidor con un gateway OAuth 2.1 que imponga RBAC y hashes fijados.
Escribir un cliente multi-servidor que realice rastreo con atributos GenAI de OTel de extremo a extremo.
Delegar parte de una carga de trabajo a un subagente A2A; verificar que la opacidad se preserve.
Empaquetar todo el stack con AGENTS.md + SKILL.md para que otros agentes puedan ejecutarlo.

El Problema

Entregar el sistema de "investigación y reporte":

El usuario pregunta: "summarize the three most-cited 2026 arXiv papers on agent protocols."
El sistema: busca en arXiv a través de MCP; delega la síntesis del artículo a un agente escritor especializado a través de A2A; agrega los resultados; renderiza un reporte interactivo como un recurso de MCP Apps ui://; registra cada paso en OTel.

Todas las primitivas de la Fase 13 aparecen aquí. Esto no es un juguete — sistemas de asistencia de investigación en producción lanzados en 2026 por Anthropic (el producto Claude Research), OpenAI (GPTs con SDK de Apps) y terceros tienen exactamente este formato.

El Concepto

Architecture

[user] -> [client] -> [gateway (OAuth 2.1 + RBAC)] -> [research MCP server]
                                                      |
                                                      +- MCP tool: arxiv_search (pure)
                                                      +- MCP resource: notes://recent
                                                      +- MCP prompt: /research_topic
                                                      +- MCP task: generate_report (long)
                                                      +- MCP Apps UI: ui://report/current
                                                      +- A2A call: writer-agent (tasks/send)
                                                      |
                                                      +- OTel GenAI spans

Trace hierarchy

agent.invoke_agent
 ├── llm.chat (kick off)
 ├── mcp.call -> tools/call arxiv_search
 ├── mcp.call -> resources/read notes://recent
 ├── mcp.call -> prompts/get research_topic
 ├── a2a.tasks/send -> writer-agent
 │    └── task transitions (opaque internals)
 ├── mcp.call -> tools/call generate_report (task-augmented)
 │    └── tasks/status polling
 │    └── tasks/result (completed, returns ui:// resource)
 └── llm.chat (final synthesis)

Un trace id. Cada span tiene los atributos gen_ai.* correctos.

Postura de seguridad

OAuth 2.1 + PKCE con indicador de recurso fijando la audiencia al gateway.
El gateway almacena las credenciales de upstream; el usuario nunca las ve.
RBAC: alice tiene research:read, research:write, puede llamar a todas las herramientas. bob tiene research:read, no puede llamar a generate_report.
Manifiesto de descripción fijado: descarta cualquier servidor cuyos hashes de herramientas hayan cambiado.
Auditoría "Rule of Two": ninguna herramienta combina entrada no confiable, datos sensibles y acción consecuente.

Renderizado

La tarea final generate_report devuelve bloques de contenido más un recurso ui://report/current. El host del cliente (Claude Desktop, etc.) renderiza el panel interactivo en un iframe sandbox. El panel contiene una lista ordenada de artículos, recuentos de citas y un botón que llama a host.callTool('summarize_paper', {arxiv_id}) para cualquier artículo en el que el usuario haga clic.

Empaquetado

Todo se entrega como:

research-system/
  AGENTS.md                     # project conventions
  skills/
    run-research/
      SKILL.md                  # the top-level workflow
  servers/
    research-mcp/               # the MCP server
      pyproject.toml
      src/
  agents/
    writer/                     # the A2A agent
  gateway/
    config.yaml                 # RBAC + pinned manifest

Los usuarios despliegan con docker compose up. Los usuarios de Claude Code, Cursor, Codex y opencode pueden ejecutar el sistema invocando la skill run-research.

Qué aportó cada lección de la Fase 13

Lección	Qué utiliza el capstone
01-05	Interfaz de herramientas, portabilidad del proveedor, llamadas en paralelo, esquemas, linting
06-10	Primitivas de MCP, servidor, cliente, transportes, recursos + prompts
11-14	Muestreo, raíces + elicitación, tareas asíncronas, aplicaciones `ui://`
15-17	Envenenamiento de herramientas, OAuth 2.1, gateway + registro
18	Delegación de subagente A2A
19	Rastreo GenAI con OTel
20	Gateway de enrutamiento para la capa LLM
21	Empaquetado con SKILL.md + AGENTS.md

Use It

El archivo code/main.py entrelaza los patrones de las lecciones anteriores en una demostración ejecutable. Todo usando stdlib, todo en proceso para que puedas leerlo de extremo a extremo. Ejecuta el flujo completo para el escenario de investigación y reporte: handshake con gateway, simulación de OAuth 2.1, fusión de tools/list, generate_report como una tarea, llamada A2A a writer, recurso ui:// devuelto, spans de OTel emitidos.

Qué observar:

Un trace id en cada salto.
La política del gateway bloquea la escritura por parte de un segundo usuario.
El ciclo de vida de la tarea va de working → completed y devuelve tanto texto como contenido ui://.
El estado interno de la llamada A2A es opaco para el orquestador.
AGENTS.md y SKILL.md son los únicos archivos que otro agente necesita para reproducir el flujo de trabajo.

Ship It

Esta lección produce outputs/skill-ecosystem-blueprint.md. Dada una necesidad de producto (investigación, síntesis, automatización), la skill produce la arquitectura completa: qué primitivas de MCP, qué controles de gateway, qué llamadas A2A, qué telemetría, qué empaquetado.

Ejercicios

Ejecuta code/main.py. Observa el trace id único y cómo se anidan los spans. Cuenta cuántas primitivas de la Fase 13 toca la demostración.
Extiende la demostración: agrega un segundo servidor MCP de backend (por ejemplo, bibliography) y confirma que el gateway fusione sus herramientas en el mismo namespace.
Reemplaza el agente escritor A2A simulado con uno real que se ejecute en un subproceso. Utiliza el harness de la Lección 19.
Agrega un paso de redacción de PII en el gateway de enrutamiento entre el orquestador y el LLM. Confirma que los correos electrónicos en la consulta del usuario se limpien.
Escribe un AGENTS.md para un compañero de equipo que mantendrá este sistema. Debería tomar menos de cinco minutos leerlo y darle todo lo que necesita para ejecutar el capstone en Cursor o Codex.

Key Terms

Término	Lo que la gente dice	Lo que realmente significa
Capstone	"Demostración de integración de Fase-13"	Sistema de extremo a extremo que utiliza cada primitiva
Research and report	"El escenario"	Patrón de búsqueda, síntesis y renderizado
Ecosystem	"Todas las piezas juntas"	Servidor + cliente + gateway + subagente + telemetría + paquete
Trace hierarchy	"Trace id único"	El span de cada salto comparte el trace; padre-hijo a través de ids de span
Gateway-issued token	"Autenticación transitiva"	El cliente ve solo el token del gateway; el gateway almacena las credenciales de upstream
Merged namespace	"Todas las herramientas en una lista única y plana"	Fusión de múltiples servidores en el gateway, con prefijo en caso de colisión
Opacity boundary	"La llamada A2A oculta detalles internos"	El razonamiento del subagente es invisible para el orquestador
Three-layer stack	"Pila de tres capas AGENTS.md + SKILL.md + MCP"	Contexto del proyecto + flujo de trabajo + herramientas
Defense-in-depth	"Múltiples capas de seguridad"	Hashes fijados, OAuth, RBAC, Rule of Two, registro de auditoría
Spec compliance matrix	"Lo que entregamos que la especificación requiere"	Lista de verificación que mapea los entregables a los requisitos de 2025-11-25