Documentation

MCP Fusion/Integrations and federation/Handoff fédéré avec Swarm

Handoff fédéré avec Swarm

Demandez à l’IA à propos de Vinkius

Acheminez une session MCP active vers un agent spécialiste avec une délégation signée, un isolement des espaces de noms, un état transféré et un retour sûr vers la passerelle.

Un seul connecteur n’a pas à gérer tous les domaines. MCP Fusion Swarm implémente un Federated Handoff Protocol : une passerelle peut transférer une session active à un agent spécialiste de la finance, du support ou des données, exposer les outils de cet agent sous un espace de noms réécrit et ramener la session sans perdre son intention.

Un handoff est une réponse

L’outil de la passerelle renvoie une réponse de handoff marquée au lieu d’essayer de faire elle-même le proxy de tout le domaine :

typescript
import { handoff } from '@mcpfusion/core';

export default f.action('triage.route')
  .describe('Route the request to the right specialist')
  .handle(async (input) => {
    return handoff(`mcp://${input.domain}-agent`, {
      carryOverState: { intent: input.context },
      reason: `Triage to ${input.domain}`,
      modelHint: 'balanced',
    });
  });

La réponse porte la marque _MCPFUSION_handoff, ce qui permet à l’attachement du serveur de la reconnaître et d’activer le chemin de handoff de la passerelle. Ce n’est ni une erreur d’outil ordinaire ni une redirection HTTP.

La passerelle

typescript
import { SwarmGateway } from '@mcpfusion/swarm';

const gateway = new SwarmGateway({
  registry: {
    finance: 'http://finance-agent:8081',
    support: 'http://support-agent:8082',
  },
  delegationSecret: process.env.MCPFUSION_DELEGATION_SECRET!,
  gatewayName: 'triage',
  tokenTtlSeconds: 60,
  connectTimeoutMs: 5_000,
  idleTimeoutMs: 300_000,
  maxSessions: 100,
});

Le registre associe les noms des spécialistes à des URL upstream. La passerelle peut utiliser auto, http ou sse comme transport upstream et limite les connexions avec des délais d’attente et un nombre maximal de sessions. activateHandoff, proxyToolsList, proxyToolsCall, returnToGateway, hasActiveHandoff, isConnecting, sessionCount, connectingCount et dispose constituent l’API opérationnelle.

Délégation signée

La passerelle et le spécialiste partagent un secret. mintDelegationToken(scope, ttlSeconds, secret, issuer, carryOverState, store, traceparent) crée un jeton de délégation HMAC. Les claims comprennent l’émetteur, le sujet, la date d’émission, l’expiration, l’identifiant cible, l’état facultatif et traceparent. Le spécialiste protège ses outils avec :

typescript
import { requireGatewayClearance } from '@mcpfusion/core';

registry.attachToServer(server, {
  middleware: [requireGatewayClearance(process.env.MCPFUSION_DELEGATION_SECRET!)],
});

verifyDelegationToken vérifie l’expiration, la signature et la portée. Les échecs sont typés HandoffAuthError, notamment en cas de jeton manquant, de jeton invalide, de jeton expiré ou de signature invalide. Il s’agit d’une fédération par secret partagé, pas d’un protocole de découverte public : faites tourner le secret, restreignez l’accès réseau upstream et gardez une durée de vie courte pour le jeton.

Isolation des espaces de noms

Un upstream ne peut pas remplacer silencieusement un outil de la passerelle. NamespaceRewriter préfixe les noms du spécialiste lorsque la liste est relayée et retire le préfixe au retour vers l’upstream. Un nom avec un préfixe incorrect déclenche NamespaceError. Le modèle voit donc quel domaine possède une capacité, tandis que le spécialiste reçoit son nom d’action d’origine.

La passerelle injecte aussi un outil de retour sûr. injectReturnTripTool(tools, gatewayName) ajoute la route de retour vers triage et formatSafeReturn(summary, domain) garde le payload de retour borné et explicite.

État transféré et référence de claim

Un petit état d’intention circule dans les claims de délégation. Un état plus volumineux ne le fait pas : au-delà de la taille maximale des claims, Swarm le stocke dans un HandoffStateStore et place une référence dans le jeton. Le InMemoryHandoffStateStore intégré est prévu pour le développement ; en production, il faut un stockage partagé afin que toute instance de la passerelle puisse récupérer la référence.

Le contexte de tracing est transporté dans traceparent, de sorte qu’un handoff puisse être suivi entre les services même si chaque spécialiste possède son propre serveur MCP.

Limites de défaillance

  • délai de connexion : la passerelle signale que l’upstream est indisponible, elle ne réessaie pas aveuglément
  • délai d’inactivité : les handoffs inactifs se ferment et libèrent la session
  • incompatibilité d’espace de noms : la passerelle rejette une réponse d’outil du mauvais domaine
  • délégation invalide : le spécialiste échoue avant que le handler ne voie l’appel
  • retour upstream : la passerelle restaure la route précédente et injecte le chemin de retour sûr

Swarm fournit un protocole et des primitives. Il ne fournit ni découverte de services, ni coffre partagé de secrets, ni stockage universel d’état distribué. Ces éléments restent des décisions de déploiement.

Étapes suivantes