Runtime Proxy

Igris Proxy — live policy enforcement, anomaly detection, session management, and transport auto-detection for MCP tool calls.

Igris Proxy

Igris Proxy is the runtime governance layer that sits between MCP clients and upstream servers. Every tool call passes through the proxy for policy evaluation, anomaly detection, and audit logging.

How It Works

Policy Engine

Policies define what tool calls are allowed, denied, or flagged. Each policy contains one or more rules evaluated in order — first match wins.

Policy Rules

{
  tool: string;     // Glob pattern to match tool names
  action: "allow" | "deny" | "alert";
  rate_limit?: number;  // Requests per minute (future)
}

Pattern Matching

Pattern	Matches
*	All tools
read_file	Exact tool name
write_*	Any tool starting with write_
*_dangerous	Any tool ending with _dangerous

Evaluation Order

1. Rules are evaluated top-to-bottom
2. First matching rule determines the action
3. If no rule matches, the tool call is allowed (default open)

Actions

Action	Behavior
allow	Forward to upstream, log the event
deny	Return JSON-RPC error to client, log the denial, do not forward
alert	Forward to upstream, log the event, emit anomaly alert via SSE

Example Policy

[
  { "tool": "delete_*", "action": "deny" },
  { "tool": "write_*", "action": "alert" },
  { "tool": "*", "action": "allow" }
]

This policy:

• Blocks all delete operations
• Allows write operations but flags them as alerts
• Allows everything else silently

Session Management

The proxy tracks agent sessions — one per {organization}:{server} pair. Sessions are created automatically on the first tool call.

Session Lifecycle

Session Object

Field	Description
id	Unique session ID (UUID)
teamId	Organization that owns this session
serverId	MCP server this session is connected to
status	active, suspended, or completed
toolCallsCount	Number of tool calls in this session
startedAt	When the session was created
suspendedAt	When the kill switch was activated
suspendedReason	Why the session was suspended

Kill Switch

The kill switch immediately blocks all tool calls for a session. When activated:

1. Session status changes to suspended
2. All subsequent tools/call requests return a JSON-RPC error
3. The suspension reason is included in the error response
4. Dashboard shows the session as suspended with a resume button

Use cases:

• Runaway agent making too many calls
• Agent accessing tools it shouldn’t
• Emergency stop during an incident

Transport Auto-Detection

MCP servers use different transport protocols. Igris Proxy automatically detects which protocol the upstream server supports.

Supported Transports

Transport	How it works
streamable-http	POST returns an SSE stream. Modern MCP servers use this.
legacy-sse	GET /sse endpoint for streaming, separate POST endpoint for requests. Older MCP servers.
http-jsonrpc	Standard HTTP POST with JSON-RPC response body. Simplest protocol.

Detection Algorithm

1. Send a POST initialize request to the upstream URL
2. If response is text/event-stream → streamable-http
3. If response is JSON → http-jsonrpc
4. If 4xx error, try GET {url}/sse:
   • If SSE stream with endpoint event → legacy-sse
5. Default fallback → http-jsonrpc

Detection results are cached per URL. No manual configuration needed.

SSE Relay

For streamable-http and legacy-sse transports, the proxy relays SSE streams from the upstream server to the MCP client, preserving real-time streaming behavior. GET requests with Accept: text/event-stream are forwarded directly.

Anomaly Detection

Igris Proxy monitors tool call patterns and alerts on suspicious behavior.

Rate Spike Detection

Tracks tool calls per session in a sliding time window. If a session exceeds the configured threshold, an anomaly alert fires.

Default config:

• Window: 60 seconds
• Threshold: 50 calls per window

Destructive Pattern Detection

Watches for sequences of mutation tool calls (matched via configurable glob patterns). Alerts after a configurable number of consecutive destructive calls.

Default destructive patterns:

• write_*, delete_*, create_*, update_*, execute_*, run_*

Default threshold: Alerts after 10 consecutive destructive calls, then enters a 10-minute cooldown to prevent alert fatigue.

Anomaly Alert Object

{
  type: "rate_spike" | "destructive_pattern",
  sessionId: string,
  toolName: string,
  message: string,
  count: number
}

Memory Management

• Stale sessions pruned every 5 minutes (>10 minutes inactive)
• Hard cap: 5,000 active sessions (oldest evicted when exceeded)
• Alert cooldowns prevent duplicate notifications

Alerting

When anomalies or policy denials occur, Igris Proxy can send alerts to external systems.

Supported Destinations

Type	Format
Slack	Block Kit message with emoji, structured fields
Discord	Embed with color-coded severity
HTTP	Raw JSON webhook (any endpoint)

Alert Events

Alerts fire for:

• policy_deny — a tool call was blocked by a policy rule
• anomaly — rate spike or destructive pattern detected
• session_suspended — kill switch was activated

Webhook Configuration

{
  type: "slack" | "discord" | "http",
  url: "https://hooks.slack.com/services/..."
}

Multiple webhooks can be configured. Alerts are sent to all configured destinations in parallel. Webhook delivery failures are non-fatal — they never block the proxy response.

Tool Call Logging

Every tool call (allowed, denied, or alerted) is logged with:

Field	Description
sessionId	Session this call belongs to
teamId	Organization
serverId	Target MCP server
toolName	Name of the tool called
toolArgs	Arguments passed to the tool
policyAction	allow, deny, or alert
policyRuleId	The rule pattern that matched
timestamp	ISO 8601 timestamp
latencyMs	Round-trip time to upstream (for allowed calls)
error	Error message (for failed calls)

Logging is asynchronous and non-blocking — it never slows down the proxy response.