Documentation

MCP Fusion/Protocol and runtime/Introspection

Introspection

Demandez à l’IA à propos de Vinkius

Faites en sorte qu’un connecteur se décrive lui-même : la fiche serveur sur le chemin bien connu, le manifeste mcpfusion filtré par RBAC, les métadonnées par action et les contrats derrière le lockfile.

Un connecteur capable de se décrire lui-même est plus facile à exploiter, auditer et intégrer. MCP Fusion expose trois surfaces d’introspection : une fiche serveur statique, un manifeste dynamique en direct et une API de métadonnées dans le processus.

La fiche serveur

Servie à /.well-known/mcp/server-card.json sur http et stateless, compilée une fois au démarrage :

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"] }]
}

Les capacités sont renseignées à partir de ce que le serveur a réellement enregistré ; la fiche ne peut donc pas annoncer une surface inexistante. Elle est servie en lecture seule, sans session, avec un en-tête de cache public de cinq minutes. Les clients de découverte et les systèmes de supervision la lisent sans jamais ouvrir de connexion MCP.

Le manifeste dynamique

Activez-le pour que le connecteur publie une ressource qui se décrit :

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

Le manifeste contient l’identité du serveur, le marqueur d’architecture MVA et, pour chaque outil, les actions, les indicateurs destructif et lecture seule, les champs requis et, pour chaque Presenter, les clés de schéma, les types de blocs d’interface pris en charge et le caractère contextuel des règles. Contrairement à la fiche statique, le manifeste est lu à travers la connexion MCP, ce qui signifie qu’il est filtré par session : le filtre reçoit le manifeste et le contexte de la requête et renvoie ce que cette session peut voir. La découverte par rôle est donc une fonction, et non un endpoint séparé.

Utilisez le manifeste lorsque les agents doivent s’orienter seuls : un agent peut lire mcpfusion://manifest.json en premier et planifier sur la surface exacte à laquelle il a droit.

Métadonnées dans le processus

Le registre répond aux questions sur sa propre surface sans aller-retour sur le 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);
  }
}

C’est le même matériau que consomme le compilateur de contrats. La CLI peut donc afficher votre surface, le lockfile peut la hacher et un tableau de bord administrateur peut la rendre : une source, trois consommateurs.

Contrats et digests

Chaque outil devient un ToolContract avec des sections surface, comportement, économie des tokens et habilitations, chacune hachée. computeServerDigest() les compose en un digest serveur ; compareServerDigests() indique si deux déploiements sont identiques du point de vue comportemental. Le lockfile écrit exactement ce matériau sur disque. Voir Contracts pour le schéma et la barrière CI.

Pourquoi c’est important en exploitation

  • Intégration : un nouveau client lit la fiche et connaît le transport et le point de terminaison avant de se connecter
  • Moindre privilège : le filtre du manifeste fait de la visibilité des capacités une décision d’exécution par rôle
  • Audit : le digest du contrat est l’artefact signé par un réviseur, pas une capture d’écran d’un tableau de bord
  • Détection des régressions : comparer les digests entre versions répond à « le comportement a-t-il changé ? » sans lire le diff de tout le dépôt

Étapes suivantes