Architecture Overview
ShieldAgent enforces security at the boundary between AI agents and the tools they use. Where exactly that boundary sits in your stack is flexible — deploy the proxy inline between agent and upstream, or call the Verdict API from your own server code before executing requests.
Where to Position ShieldAgent
ShieldAgent can be inserted at several points in the agent-to-tool call chain. The right position depends on what you own in your stack and the level of visibility you need. All positions use the same multi-stage security pipeline; only the integration method differs. Positions 2 and 3 use the REST Verdict API — your code sends request payloads to ShieldAgent for scanning and enforces the returned verdict.
Position 1 — Proxy between Agent and MCP
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.
Position 2 — Verdict API in your own API
If your agents call a REST API that you own and operate, call the ShieldAgent REST scan endpoint before executing each request. 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.
SDK examples have been retired. For a supported integration, use the OpenAPI reference.
Position 3 — Verdict API in your own MCP server
If you operate an MCP server that agents connect to, call POST /tenants/:tenantId/scan 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.
SDK examples have been retired. For a supported integration, use the OpenAPI reference.
| Position | What you need to own | Agent code changes | Sees outbound tool calls | Enforcement |
|---|---|---|---|---|
| 1 — Inline Proxy | Nothing | Point at proxy URL | Yes | Infrastructure |
| 2 — Verdict API (REST) | Your API server | Call the REST scan endpoint | Yes | Customer code |
| 3 — Verdict API (MCP) | Your MCP server | Call the REST scan endpoint | Yes | Customer code |
Positions 1-3 cover the main integration patterns for ShieldAgent SaaS.
Passthrough vs. Verdict API
Two REST integration patterns exist for customers who own their server. Choose based on whether ShieldAgent needs to forward traffic to a separate upstream.
| Scenario | Pattern | How it works |
|---|---|---|
| Your server is a gateway to a different upstream | REST proxy forwarding | Your REST client sends the request to ShieldAgent proxy. Proxy scans, then forwards to the real upstream and returns the response. |
| Your server IS the tool provider (no separate upstream) | Verdict API (REST scan) | Your REST client sends the payload to ShieldAgent. ShieldAgent returns a verdict (allow/block/human_review). Your server executes or rejects locally. |
Enforcement Model
All deployment positions run the same multi-stage security pipeline — detection, policy evaluation, risk scoring, and audit are handled by ShieldAgent. What differs is who enforces the verdict. Position 1 blocks routed calls before forwarding in enforce mode; shadow mode logs without blocking. Positions 2 and 3 use the Verdict API: ShieldAgent detects threats and returns a verdict; your server code enforces it.
Enforcement Comparison
| Position | Enforced by | Block mechanism | Guarantee |
|---|---|---|---|
| 1 — Inline Proxy | ShieldAgent | Proxy rejects routed requests in enforce mode | Applies to routed calls in enforce mode; shadow mode logs without blocking |
| 2 — Verdict API (REST) | Your server code | Your handler throws or returns error | Code-level — depends on implementation |
| 3 — Verdict API (MCP) | Your server code | Your tool handler rejects | Code-level — depends on implementation |
Responsibility Matrix
| Responsibility | Position 1 (Inline Proxy) | Positions 2 & 3 (Verdict API) |
|---|---|---|
| Threat detection | ShieldAgent | ShieldAgent |
| Policy evaluation | ShieldAgent | ShieldAgent |
| Risk scoring | ShieldAgent | ShieldAgent |
| Audit trail | ShieldAgent | ShieldAgent |
| Compliance documentation (Annex IV) | ShieldAgent | ShieldAgent |
| Blocking threats | ShieldAgent — for routed calls in enforce mode | Customer code — confirmations are self-reported |
| Blocking evidence | Proxy decision for routed calls in enforce mode | Optional client-reported confirmations; not independent proof of blocking |
Compliance Framework Impact
| Framework | Position 1 (Inline Proxy) | Positions 2 & 3 (Verdict API) |
|---|---|---|
| SOC 2 CC6.1 (Logical access controls) | ShieldAgent evidences the agent-traffic portion of this control; scope is a subset of CC6.1. | ShieldAgent provides detection + audit. Your enforcement code is part of the combined control evaluated by auditors. |
| ISO 42001 A.6.2.6 (AI system operation and monitoring) | ShieldAgent supplies the runtime operation and monitoring evidence, and reports the control as covered or partial from it. Whether your AI management system conforms is your auditor’s determination. | Identical — the monitoring evidence does not depend on enforcement topology. Coverage is still driven by the evidence present, not by the integration you choose. |
| EU AI Act Art. 9 (Risk management) | ShieldAgent evaluates threats and can block routed calls in enforce mode; these decisions may support provider risk controls. | ShieldAgent evaluates threats; customer code decides whether to enforce. Document the integration’s actual controls where relevant. |
| EU AI Act Art. 14 (Human oversight) | Human review via ShieldAgent dashboard. | Human review via dashboard + your explicit enforcement decision after receiving a human_review verdict. |
| EU AI Act Annex IV (Technical documentation) | Proxy decisions for routed calls in enforce mode can support technical documentation. | Describe the actual enforcement mechanism where relevant; ShieldAgent confirmation enrollment rates are optional self-reported telemetry, not an Annex IV requirement. |
Security Pipeline
Every intercepted request travels through the same ordered security pipeline regardless of which deployment position you use. Capabilities marked always run unconditionally; the rest are bypassed in shadow mode or when not configured.
Verifies credentials, identifies the tenant and agent, and determines whether shadow mode applies.
Applies configurable rate limits per tenant and per agent to protect upstream services from overload.
Evaluates your configurable policy rules against each request — allow, deny, or escalate to human review. Shadow mode logs without blocking.
Detects prompt injection, data exfiltration, tool misuse, and other threats using pattern matching and machine learning.
Assigns a risk score to each agent based on behavior patterns. Blocks or escalates when risk exceeds your configured thresholds.
Records a tamper-evident audit event for every request and verdict, including denied requests. Never blocks the request path.
Capabilities run in sequence. Any step can short-circuit the pipeline by returning a deny decision. Audit logging always runs, even for denied requests.
Data Isolation & Multi-Tenancy
ShieldAgent's SaaS platform enforces strict logical isolation between all tenants. All infrastructure is fully managed — you choose where to position ShieldAgent in your stack, not how to operate it.
Logical Multi-Tenant Isolation
All tenants share a single managed proxy. Isolation is enforced at every layer — JWT claims per request, row-level access controls, and per-tenant rate limits. Your data is never co-mingled with another tenant's data.
| Topology | Isolation | Managed by | Applies to |
|---|---|---|---|
| Shared (SaaS) | Logical | ShieldAgent | All plans |
Platform Capabilities
ShieldAgent provides a complete security platform for AI agent operations. All capabilities are fully managed — there is no infrastructure for you to configure or deploy.
| Capability | What it does |
|---|---|
| Security Scanning | Scans every tool call and API request for threats including prompt injection, data exfiltration, and tool misuse before they reach your systems. |
| Policy Enforcement | Evaluate configurable policy rules against every request. Policies can allow, deny, or escalate to human review. Shadow mode lets you observe without blocking. |
| Dashboard & Monitoring | Real-time security dashboard for monitoring agent activity, managing policies, exploring audit logs, and registering agents. |
| Audit Trail | Tamper-evident audit log of every tool call and verdict. Export at any time via the dashboard or a configured webhook. |
| Risk Scoring | Continuous per-agent risk scoring with behavioral anomaly detection and configurable alert thresholds. |
| Compliance Reporting | Auto-generated compliance documentation for SOC 2, ISO 42001, and EU AI Act frameworks including Annex IV evidence. |
Supported Transports
The proxy supports both network and process-based MCP transports. Choose based on how your agent framework communicates with MCP servers.
| Transport | Protocol | Use case |
|---|---|---|
| HTTP/SSE | HTTP streaming | Network agents, multi-replica deployments |
| stdio | Standard I/O | Agent spawns proxy as child process (local dev, desktop apps) |
| REST API proxy | HTTP methods | Pass-through for non-MCP REST APIs with policy enforcement |
How ShieldAgent Scales
Automatic scaling
ShieldAgent scales transparently to your traffic volume. Proxy capacity, session affinity, and database throughput are managed automatically — no configuration required on your end.
SSE connection reliability
Server-Sent Event connections are long-lived and handled with automatic reconnection routing. Session affinity is managed by the platform so your agents reconnect without data loss.
Audit throughput
The audit trail is designed for high throughput. Events are written asynchronously and never block the request path. Export at any time via the dashboard or a configured webhook.
Included in ShieldAgent SaaS
All infrastructure is operated by ShieldAgent. The following capabilities are included — nothing to deploy or maintain on your side.
Security Scanning · Policy Enforcement · Dashboard & Monitoring · Audit Trail · Risk Scoring · Compliance Reporting