Docs

MCP Fusion/Integrations and federation/Federated handoff with Swarm

Federated handoff with Swarm

Ask AI about Vinkius

Route a live MCP session to a specialist agent with signed delegation, namespace isolation, carry-over state and a safe return trip to the gateway.

A single connector does not have to own every domain. MCP Fusion Swarm implements a Federated Handoff Protocol: a gateway can transfer a live session to a finance, support or data specialist, expose that specialist's tools under a rewritten namespace and bring the session back without losing its intent.

A handoff is a response

The gateway tool returns a branded handoff response instead of trying to proxy the entire domain itself:

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

The response is branded with _MCPFUSION_handoff, so the server attachment recognizes it and activates the gateway handoff path. It is not an ordinary tool error, and it is not an HTTP redirect.

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

The registry maps specialist names to upstream URLs. The gateway can use auto, http or sse as an upstream transport, and limits connections with timeouts and a maximum session count. activateHandoff, proxyToolsList, proxyToolsCall, returnToGateway, hasActiveHandoff, isConnecting, sessionCount, connectingCount and dispose form the operational API.

Signed delegation

The gateway and specialist share a secret. mintDelegationToken(scope, ttlSeconds, secret, issuer, carryOverState, store, traceparent) creates an HMAC delegation token. Claims include issuer, subject, issued-at, expiry, target id, optional state and traceparent. The specialist protects its tools with:

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

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

verifyDelegationToken checks expiry, signature and scope. Failures are typed as HandoffAuthError, including missing token, invalid token, expired token and invalid signature. This is shared-secret federation, not a public discovery protocol: rotate the secret, restrict upstream network access and keep the token lifetime short.

Namespace isolation

An upstream cannot silently overwrite a gateway tool. NamespaceRewriter prefixes the specialist's names when the list is proxied and strips the prefix on the way back to the upstream. A name with the wrong prefix raises NamespaceError. The model therefore sees which domain owns a capability, while the specialist receives its original action name.

The gateway also injects a safe return tool. injectReturnTripTool(tools, gatewayName) adds the route back to triage, and formatSafeReturn(summary, domain) keeps the return payload bounded and explicit.

Carry-over state and claim check

Small intent state travels in the delegation claims. Larger state does not: above the claim-size threshold, Swarm stores it in an HandoffStateStore and puts a reference in the token. The built-in InMemoryHandoffStateStore is for development; production needs a shared store so any gateway instance can retrieve the claim check.

Tracing context is carried in traceparent, so a handoff can be followed across services even though each specialist owns its own MCP server.

Failure boundaries

  • connection timeout: the gateway reports the upstream unavailable, it does not retry blindly
  • idle timeout: inactive handoffs close and release the session
  • namespace mismatch: the gateway rejects a tool response from the wrong domain
  • invalid delegation: the specialist fails before the handler sees the call
  • upstream return: the gateway restores the prior route and injects the safe return path

Swarm gives you a protocol and primitives. It does not provide service discovery, a shared secret vault or a universal distributed state store. Those remain deployment decisions.

Next steps