Documentación

MCP Fusion/Protocol and runtime/Introspección

Introspección

Pregunta a la IA sobre Vinkius

Haz que un conector se describa a sí mismo: la tarjeta del servidor en la ruta conocida, el manifiesto mcpfusion filtrado por RBAC, los metadatos por acción y los contratos detrás del lockfile.

Un conector que puede describirse a sí mismo es más fácil de operar, auditar e integrar. MCP Fusion expone tres superficies de introspección: una tarjeta de servidor estática, un manifiesto dinámico activo y una API de metadatos dentro del proceso.

La tarjeta del servidor

Se sirve en /.well-known/mcp/server-card.json sobre http y stateless, compilada una vez al iniciar:

json
{
  "$schema": "https://modelcontextprotocol.io/schemas/server-card/v1",
  "version": "1.0",
  "protocolVersion": "2026-07-28",
  "serverInfo": { "name": "billing", "version": "1.4.0", "title": "Billing connector" },
  "transport": { "type": "streamable-http", "endpoint": "/mcp" },
  "capabilities": { "tools": {}, "prompts": {}, "resources": {} },
  "tools": [{ "name": "billing", "description": "...", "tags": ["finance"] }]
}

Las capacidades se rellenan a partir de lo que el servidor registró realmente, así que la tarjeta no puede anunciar una superficie inexistente. Se sirve en modo de solo lectura, sin sesión y con una cabecera de caché pública de cinco minutos. Los clientes de descubrimiento y los sistemas de monitorización la leen sin abrir nunca una conexión MCP.

El manifiesto dinámico

Actívalo para que el conector publique un recurso que se describa a sí mismo:

typescript
attachToServer(server, {
  introspection: {
    enabled: true,
    uri: 'mcpfusion://manifest.json',
    filter: (manifest, ctx) => stripInternal(manifest, ctx.userRole),
  },
});

El manifiesto contiene la identidad del servidor, el marcador de arquitectura MVA y, para cada herramienta, acciones, indicadores destructivos y de solo lectura, campos obligatorios y, para cada Presenter, claves de esquema, tipos de bloque de UI compatibles y si las reglas son contextuales. A diferencia de la tarjeta estática, el manifiesto se lee a través de la conexión MCP, lo que significa que se filtra por sesión: el filtro recibe el manifiesto y el contexto de la solicitud y devuelve lo que esa sesión puede ver. El descubrimiento por roles es, por tanto, una función, no un endpoint separado.

Usa el manifiesto cuando los agentes deban orientarse solos: un agente puede leer primero mcpfusion://manifest.json y planificar contra la superficie exacta a la que tiene derecho.

Metadatos en el proceso

El registro responde preguntas sobre su propia superficie sin un viaje de ida y vuelta por wire:

typescript
for (const builder of registry.getBuilders()) {
  console.log(builder.getName(), builder.getActionNames());
  for (const action of builder.getActionMetadata()) {
    console.log(action.actionName, action.destructive, action.requiredFields);
    console.log(action.hasMiddleware, action.presenterName);
    console.log(action.presenterSchemaKeys, action.presenterUiBlockTypes);
  }
}

Este es el mismo material que consume el compilador de contratos. Por eso la CLI puede imprimir tu superficie, el lockfile puede calcular su hash y un panel de administración puede renderizarla: una fuente, tres consumidores.

Contratos y digests

Cada herramienta se materializa en un ToolContract con secciones de superficie, comportamiento, economía de tokens y permisos, cada una con su hash. computeServerDigest() las compone en un digest del servidor; compareServerDigests() indica si dos despliegues son idénticos en comportamiento. El lockfile escribe exactamente este material en disco. Consulta Contracts para el esquema y la barrera de CI.

Por qué importa en producción

  • Incorporación: un cliente nuevo lee la tarjeta y conoce el transporte y el endpoint antes de conectarse
  • Mínimo privilegio: el filtro del manifiesto convierte la visibilidad de capacidades en una decisión de runtime por rol
  • Auditoría: el digest del contrato es el artefacto que firma un revisor, no una captura de un panel
  • Detección de regresiones: comparar digests entre versiones responde "¿cambió el comportamiento?" sin leer un diff de todo el repositorio

Próximos pasos