Visión general de la arquitectura

El agente apunta su cliente MCP al proxy de ShieldAgent en lugar del servidor upstream directamente. Sin cambios de código en el agente ni en el servidor MCP. El proxy intercepta cada llamada a herramienta, ejecuta el pipeline de seguridad completo y reenvía las solicitudes aprobadas. Este es el modelo de despliegue principal y el que te da visibilidad completa de todas las llamadas a herramientas.

Ideal cuando: no posees el agente ni el servidor MCP, o quieres un despliegue sin intervención. La segmentación de red debe garantizar que los agentes no puedan eludir el proxy.

Si tus agentes llaman a una API REST que tú posees y operas, usa el SDK de ShieldAgent para escanear cada solicitud entrante antes de ejecutarla. Tu servidor llama a client.scan() con el payload de la solicitud. ShieldAgent ejecuta el pipeline de seguridad completo multi-etapa y devuelve un veredicto (allow / block / human_review). Tu código aplica el veredicto — ejecuta si está permitido, rechaza si está bloqueado. El pipeline de seguridad se ejecuta en el proxy de ShieldAgent, no en proceso.

Ideal cuando: posees la capa de API que llaman tus agentes y quieres añadir escaneo de seguridad sin cambiar el flujo de tráfico. Tu código sigue en control — ShieldAgent escanea y devuelve un veredicto, tú lo aplicas.

import { ShieldAgentClient } from '@shieldagent/sdk';

const client = new ShieldAgentClient({
  baseUrl: 'https://proxy.shieldagent.io',
  apiKey: '{your-api-key}',
});

async function handleAgentRequest(agentId: string, method: string, path: string, body: unknown) {
  const verdict = await client.scan({
    tenantId: '{your-tenant-id}',
    agentId,
    toolName: `api:${method}:${path}`,
    params: { method, path, body },
    context: { transport: 'rest' },
  });

  if (verdict.action === 'block') {
    throw new Error(`Request blocked by ShieldAgent: ${verdict.reason}`);
  }

  if (verdict.action === 'human_review') {
    return { status: 'pending_review', reviewId: verdict.reviewId };
  }

  return executeRequest(method, path, body);
}

from shieldagent import ShieldAgentClient

client = ShieldAgentClient(
    base_url="https://proxy.shieldagent.io",
    api_key="{your-api-key}",
)

async def handle_agent_request(agent_id: str, method: str, path: str, body: dict):
    verdict = await client.scan(
        tenant_id="{your-tenant-id}",
        agent_id=agent_id,
        tool_name=f"api:{method}:{path}",
        params={"method": method, "path": path, "body": body},
        context={"transport": "rest"},
    )

    if verdict.action == "block":
        raise HTTPException(status_code=403, detail=verdict.reason)

    if verdict.action == "human_review":
        return {"status": "pending_review", "review_id": verdict.review_id}

    return execute_request(method, path, body)

Si operas un servidor MCP al que se conectan los agentes, añade una llamada a client.scan() antes de cada manejador de herramienta. Cuando un agente solicita una herramienta, tu servidor envía el nombre de la herramienta y los argumentos a ShieldAgent para escanearlos. ShieldAgent devuelve un veredicto — tu código ejecuta la herramienta solo si está permitido. Esto te da visibilidad profunda y aplicación de políticas en el punto donde se definen las herramientas, manteniendo ShieldAgent centralizado.

Ideal cuando: construyes y mantienes el servidor MCP y quieres aplicación de seguridad en la capa de definición de herramientas. Tu servidor sigue en control — ShieldAgent escanea, tú aplicas. Contexto más rico para la evaluación de políticas que el posicionamiento proxy externo.

import { ShieldAgentClient } from '@shieldagent/sdk';

const client = new ShieldAgentClient({
  baseUrl: 'https://proxy.shieldagent.io',
  apiKey: '{your-api-key}',
});

async function handleToolCall(toolName: string, params: unknown, clientName?: string) {
  const verdict = await client.scan({
    tenantId: '{your-tenant-id}',
    clientHint: clientName,
    toolName,
    params,
    context: { transport: 'mcp' },
  });

  if (verdict.action === 'block') {
    throw new Error(`Tool blocked by ShieldAgent: ${verdict.reason}`);
  }

  if (verdict.action === 'human_review') {
    return { status: 'pending_review', reviewId: verdict.reviewId };
  }

  return executeToolHandler(toolName, params);
}

from shieldagent import ShieldAgentClient

client = ShieldAgentClient(
    base_url="https://proxy.shieldagent.io",
    api_key="{your-api-key}",
)

async def handle_tool_call(tool_name: str, params: dict, client_name: str | None = None):
    verdict = await client.scan(
        tenant_id="{your-tenant-id}",
        client_hint=client_name,
        tool_name=tool_name,
        params=params,
        context={"transport": "mcp"},
    )

    if verdict.action == "block":
        raise MCPError(f"Tool blocked by ShieldAgent: {verdict.reason}")

    if verdict.action == "human_review":
        return {"status": "pending_review", "review_id": verdict.review_id}

    return execute_tool(tool_name, params)

El proxy se sitúa en el ingreso del propio agente — entre el caller y el proceso del agente. Esto es útil para inspeccionar y filtrar las entradas que dirigen al agente (prompts de usuario, mensajes de orquestación, contexto inyectado). Sin embargo, no puede observar las llamadas MCP salientes que el agente realiza a los servidores upstream, por lo que la aplicación a nivel de herramienta no es posible en esta posición por sí sola. Úsalo como complemento a las Posiciones 1–3, no como reemplazo.

Ideal cuando: se combina con la Posición 1 o 2 para cubrir tanto la inspección de prompts entrantes como la aplicación de llamadas a herramientas salientes. No se recomienda como despliegue independiente — la ruta de llamadas a herramientas salientes queda sin protección.

ShieldAgent se ejecuta como contenedor sidecar junto a cada agente (o junto a tu servidor MCP/API). El agente envía solicitudes al sidecar en lugar de la URL upstream directamente. Sin salto de red adicional — el tráfico permanece en localhost. Mismo pipeline completo que la Posición 1, pero co-ubicado para menor latencia y aislamiento por agente.

Ideal cuando: entornos Kubernetes, requisitos de aislamiento por agente, o arquitecturas de microservicios. También funciona como sidecar de tu servidor — co-ubica ShieldAgent junto a tu servidor MCP/API en lugar del agente para bloqueo garantizado por infraestructura sin salto de red.

ShieldAgent se sitúa detrás de tu API gateway existente (Kong, Envoy, AWS API Gateway). El gateway gestiona la autenticación y el enrutamiento, luego reenvía el tráfico del agente a ShieldAgent para el escaneo de seguridad antes de que llegue al upstream. Sin cambios de código en el agente — el gateway enruta de forma transparente.

Ideal cuando: empresas con API gateways existentes que no pueden cambiar el enrutamiento del agente. Limitación: el tráfico que evita el gateway es invisible para ShieldAgent.

El tráfico fluye directamente del agente al upstream sin intercepción. Una copia de cada solicitud/respuesta se envía a ShieldAgent de forma asíncrona para auditoría y detección. ShieldAgent no puede bloquear amenazas en este modo — proporciona detección, puntuación de riesgo y evidencia de cumplimiento sin aplicación.

Ideal cuando: evaluación inicial, auditoría de cumplimiento, o entornos heredados donde la inserción inline aún no es posible. Sin impacto en la latencia.

¿Qué posición debo usar?

Todos los inquilinos comparten un despliegue de proxy. El aislamiento es lógico — aplicado mediante claims JWT, seguridad a nivel de fila en PostgreSQL y límites de tasa por inquilino. Menor coste de infraestructura.