Dokumentation

MCP Fusion/Integrations and federation/Föderierte Übergabe mit Swarm

Föderierte Übergabe mit Swarm

Frag die KI über Vinkius

Leiten Sie eine aktive MCP-Sitzung mit signierter Delegation, Namespace-Isolation, übertragenem Zustand und sicherem Rückweg zum Gateway an einen Spezialisten weiter.

Ein einzelner Konnektor muss nicht jede Domäne besitzen. MCP Fusion Swarm implementiert ein Federated Handoff Protocol: Ein Gateway kann eine aktive Sitzung an einen Finanz-, Support- oder Daten-Spezialisten übertragen, dessen Tools unter einem umgeschriebenen Namespace bereitstellen und die Sitzung zurückführen, ohne ihre Absicht zu verlieren.

Ein Handoff ist eine Antwort

Das Gateway-Tool gibt eine markierte Handoff-Antwort zurück, anstatt die gesamte Domäne selbst zu proxien:

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

Die Antwort trägt die Markierung _MCPFUSION_handoff, sodass die Server-Anbindung sie erkennt und den Gateway-Handoff-Pfad aktiviert. Sie ist weder ein gewöhnlicher Tool-Fehler noch eine HTTP-Weiterleitung.

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

Die Registry ordnet Spezialistennamen Upstream-URLs zu. Das Gateway kann auto, http oder sse als Upstream-Transport verwenden und begrenzt Verbindungen durch Timeouts und eine maximale Sitzungsanzahl. activateHandoff, proxyToolsList, proxyToolsCall, returnToGateway, hasActiveHandoff, isConnecting, sessionCount, connectingCount und dispose bilden die operative API.

Signierte Delegation

Das Gateway und der Spezialist teilen ein Geheimnis. mintDelegationToken(scope, ttlSeconds, secret, issuer, carryOverState, store, traceparent) erstellt ein HMAC-Delegationstoken. Die Claims enthalten Aussteller, Subjekt, Ausstellungszeitpunkt, Ablauf, Ziel-ID, optionalen Zustand und traceparent. Der Spezialist schützt seine Tools mit:

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

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

verifyDelegationToken prüft Ablauf, Signatur und Geltungsbereich. Fehler sind als HandoffAuthError typisiert und umfassen fehlendes, ungültiges oder abgelaufenes Token sowie eine ungültige Signatur. Dies ist eine Föderation mit gemeinsamem Geheimnis, kein öffentliches Discovery-Protokoll: Rotieren Sie das Geheimnis, beschränken Sie den Upstream-Netzwerkzugriff und halten Sie die Token-Lebensdauer kurz.

Namespace-Isolation

Ein Upstream kann ein Gateway-Tool nicht unbemerkt überschreiben. NamespaceRewriter setzt den Namen des Spezialisten beim Weiterleiten der Liste ein Präfix voran und entfernt es auf dem Rückweg zum Upstream. Ein Name mit falschem Präfix löst NamespaceError aus. Das Modell erkennt dadurch, welche Domäne eine Fähigkeit besitzt, während der Spezialist seinen ursprünglichen Aktionsnamen erhält.

Das Gateway fügt außerdem ein sicheres Rückkehr-Tool ein. injectReturnTripTool(tools, gatewayName) ergänzt die Route zurück zu triage, und formatSafeReturn(summary, domain) hält die Rückgabe-Payload begrenzt und eindeutig.

Übertragener Zustand und Claim-Referenz

Kleiner Absichtszustand wird in den Delegations-Claims übertragen. Größerer Zustand wird nicht übertragen: Oberhalb des Claim-Größenlimits speichert Swarm ihn in einem HandoffStateStore und legt eine Referenz im Token ab. Der integrierte InMemoryHandoffStateStore ist für die Entwicklung gedacht. In der Produktion benötigen Sie einen gemeinsamen Speicher, damit jede Gateway-Instanz die Claim-Referenz abrufen kann.

Der Tracing-Kontext wird in traceparent übertragen. Dadurch kann ein Handoff serviceübergreifend verfolgt werden, obwohl jeder Spezialist seinen eigenen MCP-Server besitzt.

Fehlergrenzen

  • Verbindungs-Timeout: Das Gateway meldet den nicht verfügbaren Upstream und wiederholt nicht blind
  • Inaktivitäts-Timeout: Inaktive Handoffs werden geschlossen und geben die Sitzung frei
  • Namespace-Abweichung: Das Gateway weist eine Tool-Antwort aus der falschen Domäne zurück
  • Ungültige Delegation: Der Spezialist schlägt fehl, bevor der Handler den Aufruf sieht
  • Upstream-Rückkehr: Das Gateway stellt die vorherige Route wieder her und fügt den sicheren Rückweg ein

Swarm liefert ein Protokoll und Primitive. Es stellt weder Service Discovery noch einen gemeinsamen Geheimnisspeicher noch einen universellen verteilten Zustandsspeicher bereit. Diese Punkte bleiben Entscheidungen der Bereitstellung.

Nächste Schritte