Architecture Overview

The agent points its MCP client at the ShieldAgent proxy instead of the upstream server directly. No code changes to the agent or the MCP server. The proxy intercepts every tool call, runs the full security pipeline, and forwards approved requests. This is the primary deployment model and the one that gives you complete visibility into all tool calls.

Best when: you do not own the agent or MCP server, or you want zero-touch deployment. Network segmentation should enforce that agents cannot bypass the proxy.

If your agents call a REST API that you own and operate, use the ShieldAgent SDK to scan each incoming request before executing it. Your server calls client.scan() with the request payload. ShieldAgent runs the full multi-stage security pipeline and returns a verdict (allow / block / human_review). Your code enforces the verdict — execute if allowed, reject if blocked. The security pipeline runs on the ShieldAgent proxy, not in-process.

Best when: you own the API layer your agents call and want to add security scanning without changing your traffic flow. Your code stays in control — ShieldAgent scans and returns a verdict, you enforce it.

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)

If you operate an MCP server that agents connect to, add a client.scan() call before each tool handler. When an agent requests a tool, your server sends the tool name and arguments to ShieldAgent for scanning. ShieldAgent returns a verdict — your code executes the tool only if allowed. This gives you deep visibility and policy enforcement at the point where tools are defined, while keeping ShieldAgent centralized.

Best when: you build and maintain the MCP server and want security enforcement at the tool definition layer. Your server stays in control — ShieldAgent scans, you enforce. Richer context for policy evaluation than external proxy positioning.

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)

The proxy sits at the ingress of the agent itself — between the caller and the agent process. This is useful for inspecting and filtering the inputs that drive the agent (user prompts, orchestration messages, injected context). However, it cannot observe the outbound MCP calls the agent makes to upstream servers, so tool-level enforcement is not possible in this position alone. Use it as a complement to Positions 1–3, not a replacement.

Best when: combined with Position 1 or 2 to cover both inbound prompt inspection and outbound tool call enforcement. Not recommended as a standalone deployment — the outbound tool call path remains unprotected.

ShieldAgent runs as a sidecar container alongside each agent (or alongside your MCP/API server). The agent sends requests to the sidecar instead of the upstream URL directly. No extra network hop — traffic stays on localhost. Same full pipeline as Position 1, but co-located for lower latency and per-agent isolation.

Best when: Kubernetes environments, per-agent isolation requirements, or microservice architectures. Also works as a sidecar of your server — co-locate ShieldAgent alongside your MCP/API server instead of the agent for infrastructure-enforced blocking without a network hop.

ShieldAgent sits behind your existing API gateway (Kong, Envoy, AWS API Gateway). The gateway handles authentication and routing, then forwards agent traffic to ShieldAgent for security scanning before it reaches the upstream. No agent code changes — the gateway routes transparently.

Best when: enterprises with existing API gateways that cannot change agent routing. Limitation: traffic bypassing the gateway is invisible to ShieldAgent.

Traffic flows directly from the agent to upstream without interception. A copy of each request/response is sent to ShieldAgent asynchronously for audit and detection. ShieldAgent cannot block threats in this mode — it provides detection, risk scoring, and compliance evidence without enforcement.

Best when: initial evaluation, compliance auditing, or brownfield environments where inline insertion is not yet possible. Zero latency impact.

Which position should I use?

All tenants share one proxy deployment. Isolation is logical — enforced by JWT claims, row-level security in PostgreSQL, and per-tenant rate limits. Lowest infrastructure cost.