Documentación

MCP Fusion/Integrations and federation/Handoff federado con Swarm

Handoff federado con Swarm

Pregunta a la IA sobre Vinkius

Dirige una sesión MCP activa a un agente especialista con delegación firmada, aislamiento de namespaces, estado transferido y un regreso seguro al gateway.

Un solo conector no tiene que ser dueño de todos los dominios. MCP Fusion Swarm implementa un Federated Handoff Protocol: un gateway puede transferir una sesión activa a un especialista en finanzas, soporte o datos, exponer las herramientas de ese especialista bajo un namespace reescrito y devolver la sesión sin perder su intención.

Un handoff es una respuesta

La herramienta del gateway devuelve una respuesta de handoff identificada en lugar de intentar actuar como proxy de todo el dominio:

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 respuesta lleva la marca _MCPFUSION_handoff, por lo que el acoplamiento del servidor la reconoce y activa la ruta de handoff del gateway. No es un error de herramienta normal ni una redirección HTTP.

El gateway

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,
});

El registro asigna nombres de especialistas a URLs upstream. El gateway puede usar auto, http o sse como transporte upstream y limita las conexiones mediante timeouts y un número máximo de sesiones. activateHandoff, proxyToolsList, proxyToolsCall, returnToGateway, hasActiveHandoff, isConnecting, sessionCount, connectingCount y dispose forman la API operativa.

Delegación firmada

El gateway y el especialista comparten un secreto. mintDelegationToken(scope, ttlSeconds, secret, issuer, carryOverState, store, traceparent) crea un token de delegación HMAC. Las claims incluyen emisor, sujeto, momento de emisión, expiración, ID de destino, estado opcional y traceparent. El especialista protege sus herramientas con:

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

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

verifyDelegationToken comprueba la expiración, la firma y el alcance. Los fallos tienen el tipo HandoffAuthError e incluyen token ausente, token no válido, token caducado y firma no válida. Esto es federación mediante un secreto compartido, no un protocolo público de descubrimiento: rota el secreto, restringe el acceso de red upstream y mantén corto el tiempo de vida del token.

Aislamiento de namespaces

Un upstream no puede sobrescribir en silencio una herramienta del gateway. NamespaceRewriter antepone un prefijo a los nombres del especialista cuando se retransmite la lista y elimina el prefijo al volver al upstream. Un nombre con el prefijo incorrecto genera NamespaceError. Así, el modelo ve qué dominio posee una capacidad y el especialista recibe su nombre de acción original.

El gateway también inyecta una herramienta de retorno seguro. injectReturnTripTool(tools, gatewayName) añade la ruta de vuelta a triage y formatSafeReturn(summary, domain) mantiene el payload de retorno acotado y explícito.

Estado transferido y comprobante de claim

Un pequeño estado de intención viaja en las claims de delegación. El estado más grande no lo hace: por encima del límite de tamaño de las claims, Swarm lo guarda en un HandoffStateStore y coloca una referencia en el token. El InMemoryHandoffStateStore integrado sirve para desarrollo; en producción necesitas un almacén compartido para que cualquier instancia del gateway pueda recuperar el comprobante.

El contexto de tracing se transporta en traceparent, de modo que un handoff puede seguirse entre servicios aunque cada especialista sea dueño de su propio servidor MCP.

Límites de fallo

  • timeout de conexión: el gateway informa de que el upstream no está disponible, no reintenta a ciegas
  • timeout de inactividad: los handoffs inactivos se cierran y liberan la sesión
  • incompatibilidad de namespace: el gateway rechaza una respuesta de herramienta del dominio incorrecto
  • delegación no válida: el especialista falla antes de que el handler vea la llamada
  • retorno del upstream: el gateway restaura la ruta anterior e inyecta la ruta de retorno seguro

Swarm te proporciona un protocolo y primitivas. No proporciona descubrimiento de servicios, un almacén compartido de secretos ni un almacén universal de estado distribuido. Esas siguen siendo decisiones de despliegue.

Próximos pasos