Núcleo digital · servidor MCP

La máquina habita la sintaxis

El núcleo DWFW incluye un servidor MCP (Model Context Protocol) para que un agente — Claude u otro cliente MCP — lea el observatorio, la cartografía y el Event Stack y proponga conexiones con procedencia máquina. No puede confirmar conexiones, asignar significados ni avanzar movimientos: lo impide el RBAC del usuario de servicio, no la buena voluntad del agente.

Servidor https://dwfw.trabemflex.com/mcp · OAuth · stdioGuía de la API Código e instrucciones · GitHub

Qué es

MCP (Model Context Protocol) es el protocolo abierto con el que un modelo de lenguaje se conecta a herramientas externas. El servidor dwfw tiene dos transportes con la misma lógica: stdio para desarrollo local (mcp/index.mjs) y Streamable HTTP para producción, en https://dwfw.trabemflex.com/mcp. Ambos traducen cada llamada del agente en peticiones a la API REST del núcleo — la misma que documenta la guía de la API, con los mismos permisos.

El reparto de papeles es doctrinal: la máquina habita la sintaxis; el humano, la semántica. Un agente conectado puede detectar patrones formales y proponer conexiones; un curador humano las confirma o las descarta en el panel. El servidor no otorga poderes: quien decide es el RBAC del núcleo, a través del usuario de servicio con rol investigador.

Qué puede hacer un agente conectado, hoy: buscar y leer obras, autores y nodos, recorrer la cartografía, consultar el programa del Event Stack, y proponer conexiones entre obras y nodos (entran como propuesta, procedencia máquina). Qué no puede: confirmar esas propuestas, asignar significados, avanzar movimientos curatoriales, ni ver o tocar usuarios, credenciales o activos privados. La conexión recomendada es de un clic con OAuth 2.1 (como los conectores de HubSpot o Slack): autorizas con tu usuario DWFW en una pantalla de consentimiento y el cliente queda conectado, sin copiar tokens; cada sesión pertenece a una persona, aparece en la auditoría, caduca sola y se revoca en el admin. Sigue disponible la alternativa con token para clientes que no hablen OAuth.

Conexión con un clic (OAuth)

La vía recomendada. El servidor implementa OAuth 2.1 con registro dinámico de clientes y PKCE — el mismo flujo de los conectores de HubSpot o Slack: autorizas con tu usuario DWFW en una pantalla de consentimiento y el cliente queda conectado, sin tokens copiados a mano. Cada sesión pertenece a una persona (la auditoría registra su email), se revoca en el admin (Sesiones MCP) y caduca sola: acceso de 1 hora que el cliente renueva hasta 30 días.

claude.ai (web o escritorio): Ajustes → Conectores → «Añadir conector personalizado» → URL https://dwfw.trabemflex.com/mcp → autorizar en la pantalla de DWFW.
Claude Code: el comando de abajo; el navegador abre el consentimiento y al autorizar la sesión queda conectada.

# Claude Code: sin token ni cabeceras — el navegador abre el consentimiento de DWFW
claude mcp add --transport http dwfw https://dwfw.trabemflex.com/mcp

# Tras autorizar debe aparecer ✔ Connected
claude mcp list

Conexión remota con token (alternativa)

El transporte de producción es Streamable HTTP y es stateless: cada petición es autocontenida, sin sesiones ni afinidad de cliente. Si no puedes usar OAuth, la alternativa manual es un token de cliente (sección siguiente); viaja siempre en la cabecera Authorization, nunca en la URL.

# Claude Code: conectar con el servidor remoto (token de la sección siguiente)
claude mcp add --transport http dwfw https://dwfw.trabemflex.com/mcp \
  --header "Authorization: Bearer dwfw_mcp_…"

# Comprobar el estado del servicio (sin credenciales)
curl https://dwfw.trabemflex.com/mcp/salud

# Otros clientes MCP con HTTP remoto: configuración genérica
{
  "mcpServers": {
    "dwfw": {
      "url": "https://dwfw.trabemflex.com/mcp",
      "headers": { "Authorization": "Bearer dwfw_mcp_…" }
    }
  }
}

Autenticación remota

El token de cliente (dwfw_mcp_…) se emite con una llamada a la API con sesión de dirección: POST https://dwfw.trabemflex.com/api/tokens-mcp con {"nombre": "quién lo usa"}. El token en claro viene SOLO en esa respuesta JSON — cópialo entonces; en base de datos solo queda su hash y no vuelve a poder leerse. Desmarcar "Activo" en el admin lo revoca (efectivo en ≤1 minuto); la caducidad opcional lo apaga sola.

Son tres identidades que no se mezclan: el token identifica al cliente remoto; el servidor MCP habla con la API como maquina@dwfw.test con una clave interna que nunca sale del servidor; y los permisos los pone el RBAC de ese usuario. Las sesiones OAuth conviven con estos tokens: mismo transporte, mismas herramientas, misma barrera RBAC.

Conexión local (stdio)

Hacen falta Node 18+ y una copia del repositorio. El servidor no necesita base de datos ni configuración local: solo variables de entorno que apuntan a la API. En Claude Desktop, añade el bloque JSON de abajo a claude_desktop_config.json.

# Clonar el núcleo e instalar las dependencias del servidor (Node 18+)
git clone https://github.com/juanceldran/dwfw-core
cd dwfw-core/mcp && pnpm install --ignore-workspace

# Arrancar a mano (habla por stdio; normalmente lo lanza el cliente MCP)
DWFW_API_URL=https://dwfw.trabemflex.com/api DWFW_API_KEY=… node index.mjs

# Claude Code: registrar el servidor (ajusta la ruta a tu copia del repositorio)
claude mcp add dwfw \
  -e DWFW_API_URL=https://dwfw.trabemflex.com/api \
  -e DWFW_API_KEY=… \
  -- node /ruta/dwfw-core/mcp/index.mjs

# Comprobar que aparece y conecta
claude mcp list

{
  "mcpServers": {
    "dwfw": {
      "command": "node",
      "args": ["/ruta/dwfw-core/mcp/index.mjs"],
      "env": {
        "DWFW_API_URL": "https://dwfw.trabemflex.com/api",
        "DWFW_API_KEY": "…"
      }
    }
  }
}

Credenciales y variables

La vía recomendada es una clave de API del usuario de servicio maquina@dwfw.test (rol investigador): se genera en el admin, en la ficha del usuario, marcando "Enable API Key". Viaja como cabecera Authorization: usuarios API-Key … y evita guardar contraseñas en configuraciones de cliente. La alternativa es DWFW_EMAIL + DWFW_PASSWORD (el servidor renueva el JWT solo).

Sin credenciales, el servidor funciona en modo lectura pública: el archivo (obras en movimiento 7), los autores, los nodos, la cartografía, los significados y el programa del Event Stack. Proponer conexiones exige sesión de servicio.

# API del núcleo (producción; en desarrollo, http://localhost:3000/api)
DWFW_API_URL=https://dwfw.trabemflex.com/api

# Clave de API del usuario de servicio (recomendada; se genera en el admin)
DWFW_API_KEY=…

# Alternativa: sesión con email y contraseña del usuario de servicio
DWFW_EMAIL=maquina@dwfw.test
DWFW_PASSWORD=…

# Idioma por defecto de las respuestas: es · en · zh · ja
DWFW_LOCALE=es

Herramientas

Seis herramientas de lectura y una sola de escritura. Los nombres y parámetros son identificadores técnicos y no se traducen; el contenido sí llega en el idioma pedido con locale.

Herramienta	Qué hace	Parámetros
`buscar_obras` · lee	Obras del observatorio visibles para la sesión de servicio; filtra por texto, movimiento o tipo.	`q · movimiento · tipo · limit · locale`
`ficha_obra` · lee	Ficha completa de una obra: autor, conexiones (origen y destino) y significados asignados.	`id · locale`
`buscar_autores` · lee	Diseñadores, colectivos, laboratorios e instituciones (capa 2).	`q · tipo · locale`
`buscar_nodos` · lee	Nodos de la cartografía (capa 3): corrientes, desarrollos técnicos, comunidades, instituciones, tensiones.	`q · tipo · locale`
`cartografia` · lee	Conexiones del grafo; todas por defecto, o filtradas por estado (propuesta · confirmada · descartada).	`estado · locale`
`programa` · lee	Programa del Event Stack: ediciones, capítulos de marca y piezas audiovisuales.	`locale`
`proponer_conexion` · escribe	La única escritura: crea una conexión con procedencia máquina y estado propuesta, con la evidencia en nota.	`origen · destino · tipoRelacion · nota`

dwfw://doctrina — Recurso de solo lectura con las reglas duras del núcleo en markdown. Un cliente puede cargarlo en contexto antes de que el agente empiece a trabajar.

Qué puede hacer y qué no

Los límites no son promesas del agente: los aplica el servidor del núcleo en cada petición. El usuario de servicio tiene capacidades de lectura y conexion:proponer; cualquier otra escritura recibe un 403 con mensaje explícito. Aunque el agente lo intente, el núcleo lo impide.

Puede

● Leer el observatorio completo (obras en cualquier movimiento), autores, nodos, conexiones, significados y el programa del Event Stack.
● Buscar y filtrar por texto, tipo, movimiento o estado, en cualquiera de los cuatro idiomas (locale).
● Proponer conexiones entre obras y/o nodos (cualquier combinación de origen y destino) con evidencia sintáctica en nota: nacen con procedencia maquina y estado propuesta.
● Leer el recurso dwfw://doctrina para conocer las reglas antes de actuar.

No puede

● Confirmar ni descartar conexiones: es un acto semántico y exige la capacidad conexion:confirmar (403 con mensaje explícito).
● Asignar significados (capa 4): exige significado:asignar, capacidad reservada a curadores humanos (403); además el servidor fuerza procedencia: humano en todo significado.
● Avanzar movimientos curatoriales: el estado de una obra solo cambia con movimiento:avanzar.
● Crear, editar o borrar obras, autores, nodos, ediciones o usuarios; ni subir o publicar activos de Media.
● Pedir o inferir métricas de popularidad: no existen likes, vistas ni ranking en la API (epojé algorítmica).

# Proponer una conexión: nace como propuesta, con procedencia máquina
proponer_conexion {
  "origen":  { "tipo": "obras", "id": 3 },
  "destino": { "tipo": "nodos", "id": 2 },
  "tipoRelacion": "dialoga_con",
  "nota": "Ambas trabajan crecimiento biológico simulado: micelio como lógica generativa."
}
# → { "ok": true, "id": 12, "estado": "propuesta", "procedencia": "maquina",
#     "mensaje": "Propuesta registrada. Queda pendiente de confirmación humana." }

# Ver las propuestas pendientes de confirmación humana
cartografia { "estado": "propuesta" }

Versiones del protocolo

El transporte HTTP sirve las revisiones que soporta el SDK oficial: 2025-11-25, 2025-06-18, 2025-03-26 y 2024-11-05. Los clientes de la revisión 2026-07-28 — que hace el protocolo stateless, como ya es este servidor — sondean y negocian a la baja solos (Claude Code reciente lo hace). Adoptarla cuando el SDK la publique será una actualización de dependencia, no un rediseño.

Doctrina para agentes

Antes de trabajar, conviene que el agente cargue el recurso dwfw://doctrina. En resumen:

Procedencia en cada capa: lo que propone la máquina queda como propuesta hasta que un humano lo confirme.
Epojé algorítmica: el orden lo marca el peso de la idea; no hay métricas que optimizar ni que pedir.
Los siete movimientos: solo un humano avanza el estado curatorial; de las obras, solo el movimiento 7 (archivo) es público sin sesión.
El origen cultural es un dato descriptivo, nunca un criterio de orden ni de jerarquía.
Los activos técnicos son privados hasta el movimiento 7 (curación a ciegas).