Documentação

MCP Fusion/Integrations and federation/Handoff federado com Swarm

Handoff federado com Swarm

Pergunte à IA sobre a Vinkius

Direcione uma sessão MCP ativa para um agente especialista com delegação assinada, isolamento de namespace, estado transferido e retorno seguro ao gateway.

Um único conector não precisa controlar todos os domínios. MCP Fusion Swarm implementa um Federated Handoff Protocol: um gateway pode transferir uma sessão ativa para um especialista em finanças, suporte ou dados, expor as ferramentas desse especialista sob um namespace reescrito e devolver a sessão sem perder sua intenção.

Um handoff é uma resposta

A ferramenta do gateway retorna uma resposta de handoff identificada em vez de tentar fazer proxy de todo o domínio por conta própria:

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

A resposta é identificada com _MCPFUSION_handoff, para que o anexo do servidor a reconheça e ative o caminho de handoff do gateway. Ela não é um erro comum de ferramenta nem um redirecionamento HTTP.

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

O registro mapeia nomes de especialistas para URLs upstream. O gateway pode usar auto, http ou sse como transporte upstream e limita conexões com timeouts e uma contagem máxima de sessões. activateHandoff, proxyToolsList, proxyToolsCall, returnToGateway, hasActiveHandoff, isConnecting, sessionCount, connectingCount e dispose formam a API operacional.

Delegação assinada

O gateway e o especialista compartilham um segredo. mintDelegationToken(scope, ttlSeconds, secret, issuer, carryOverState, store, traceparent) cria um token de delegação HMAC. As claims incluem emissor, sujeito, momento de emissão, expiração, ID do destino, estado opcional e traceparent. O especialista protege suas ferramentas com:

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

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

verifyDelegationToken verifica expiração, assinatura e escopo. As falhas são tipadas como HandoffAuthError, incluindo token ausente, token inválido, token expirado e assinatura inválida. Isso é federação por segredo compartilhado, não um protocolo de descoberta pública: alterne o segredo, restrinja o acesso à rede upstream e mantenha curto o tempo de vida do token.

Isolamento de namespace

Um upstream não pode substituir silenciosamente uma ferramenta do gateway. NamespaceRewriter acrescenta um prefixo aos nomes do especialista quando a lista é encaminhada e remove o prefixo no caminho de volta ao upstream. Um nome com o prefixo errado gera NamespaceError. Assim, o modelo vê qual domínio é responsável por uma capacidade, enquanto o especialista recebe seu nome de ação original.

O gateway também injeta uma ferramenta de retorno seguro. injectReturnTripTool(tools, gatewayName) adiciona a rota de volta para triage, e formatSafeReturn(summary, domain) mantém o payload de retorno limitado e explícito.

Estado transferido e comprovante de claim

Um pequeno estado de intenção viaja nas claims de delegação. O estado maior não: acima do limite de tamanho das claims, o Swarm o armazena em um HandoffStateStore e coloca uma referência no token. O InMemoryHandoffStateStore integrado serve para desenvolvimento; em produção, é necessário um armazenamento compartilhado para que qualquer instância do gateway possa recuperar o comprovante.

O contexto de tracing é transportado em traceparent, portanto um handoff pode ser acompanhado entre serviços mesmo que cada especialista controle seu próprio servidor MCP.

Limites de falha

  • timeout de conexão: o gateway informa que o upstream está indisponível, sem repetir cegamente
  • timeout de inatividade: handoffs inativos são fechados e liberam a sessão
  • incompatibilidade de namespace: o gateway rejeita uma resposta de ferramenta do domínio errado
  • delegação inválida: o especialista falha antes que o handler veja a chamada
  • retorno do upstream: o gateway restaura a rota anterior e injeta o caminho de retorno seguro

O Swarm oferece um protocolo e primitivas. Ele não fornece descoberta de serviços, um cofre compartilhado de segredos nem um armazenamento universal de estado distribuído. Essas continuam sendo decisões de deploy.

Próximos passos