Skip to main content

ExtMCP Guardrails

O Workspace cortex/mcp/guardrails fornece o processador de política ExtMCP gRPC independente para o AgentGateway no subsistema AI Cortex.

Detalhes do Serviço​

  • Protocolo: gRPC (ext_mcp.proto)
  • Porta: 9001
  • Linguagem: Node.js 22 (TypeScript)
  • Função: Proxy de Rede Transparente e Validador de Requisições

Arquitetura​

O serviço Guardrails implementa o protocolo ExtMCP do AgentGateway para interceptar chamadas de método do Model Context Protocol (MCP) antes que elas atinjam os containers downstream.

Ele recebe payloads nativos de MCP estruturados (nome do método JSON-RPC, parâmetros, etc.) em vez de HTTP bruto. Isso permite a inspeção precisa de chamadas de ferramentas (tools/call) e respostas (tools/list).

Processadores​

1. Mutador de Requisição (request-mutator.ts)​

Realiza o gancho na fase tools/call para atuar como um Proxy de Rede Transparente.

Comportamento:

  • Realiza varredura profunda recursiva em todos os argumentos no payload JSON de qualquer chamada de ferramenta.
  • Reescreve qualquer string contendo localhost ou 127.0.0.1 para host.docker.internal.
  • Garante conectividade perfeita entre container e host sem exigir que o agente de IA compreenda o modelo de rede subjacente do Docker/Kubernetes.

2. Enriquecedor de Resposta (response-enricher.ts)​

Realiza o gancho na fase de saída tools/list.

Comportamento:

  • Atua como um pass-through puro ({ pass: {} }).
  • Nota: Em versões legadas, este processador injetava instruções em markdown nas descrições de ferramentas. Isso foi removido para evitar o inchaço do esquema e preservar a eficiência da janela de contexto do LLM. As instruções do agente agora são gerenciadas no lado do cliente via .agents/rules.

Contrato Fail-Safe (Fail-Open)​

Para manter alta disponibilidade no plano de dados do Cortex, todos os processadores ExtMCP devem capturar exceções internas (por exemplo, erros de parsing) e retornar graciosamente para uma resposta { pass: {} }. Isso garante que um bug na lógica de guardrail não derrube todo o toolchain de IA.