O gateway

stalwart gateway é um gateway MCP que verifica cada chamada de ferramenta que um agente faz, a caminho da ferramenta. O agente se conecta ao gateway; o gateway se conecta aos seus servidores MCP.

• tools/list devolve só as ferramentas do seu catálogo que o agente conectado pode alcançar.
• tools/call é verificado primeiro: contra o catálogo, o esquema dos argumentos, o histórico da sessão e as regras de ordem, o seu rulebook e os rótulos de confiança. Ele só é despachado com allow. Uma chamada recusada nunca chega ao servidor.
• Uma chamada que precisa de uma pessoa vira uma elicitação MCP com o texto da confirmação. Um cliente a quem não se pode perguntar recebe confirmation_unavailable, nunca uma escrita não confirmada.
• Toda escrita leva uma chave de idempotência em _meta.
• Cada sessão de agente recebe uma sessão MCP própria em cada servidor, aberta com initialize antes da sua primeira chamada e encerrada com ela. As chamadas de uma sessão nunca trafegam nas de outra.
• Depois de uma ferramenta que lê o mundo externo, toda chamada seguinte da sessão leva o seu rótulo. Isso é mais grosseiro que o nó de ferramentas em processo, porque o gateway não vê o contexto do modelo.
• As escritas da sessão são desfeitas da última para a primeira em POST /admin/sessions/{id}/rollback, ou quando a sessão é encerrada com DELETE /mcp?abort=1.
• Toda decisão é escrita na forma do registro de controle, qls-decision/1.

$ pip install stalwart-agents
$ stalwart gateway --config gateway.yaml

catalogue: ./catalogue.json
upstreams:
  "*": http://tools.internal:8080/mcp
agents:
  desk: ${DESK_TOKEN}
  billing: ${BILLING_TOKEN}
admin_token: ${GATEWAY_ADMIN_TOKEN}
audit: /var/log/stalwart/decisions.jsonl
elicitation_timeout: 600        # seconds a person has to answer a confirmation
listen: 0.0.0.0:8800

Cada agente se conecta com o seu próprio token bearer, de modo que o gateway sabe qual agente está chamando e o que ele pode alcançar.

Uma confirmação não respondida em elicitation_timeout segundos (600 por padrão) é recusada, e o mesmo vale para uma cujo cliente se desconecta antes. As outras chamadas da sessão esperam enquanto se pergunta a uma pessoa, porque a verificação e a sua confirmação precisam ver o mesmo histórico.

O gateway só é um ponto de controle se as ferramentas só puderem ser alcançadas por ele. network-policy.yaml é uma NetworkPolicy do Kubernetes que deixa só o gateway alcançar os servidores de ferramentas. Aplique-a, ou o equivalente na sua rede. Para colocar a verificação na frente das suas ferramentas a partir do Kong AI Gateway, veja a receita do Kong.