Skip to main content

​
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

PatternMatches
*All tools
read_fileExact tool name
write_*Any tool starting with write_
*_dangerousAny 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

ActionBehavior
allowForward to upstream, log the event
denyReturn JSON-RPC error to client, log the denial, do not forward
alertForward 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

FieldDescription
idUnique session ID (UUID)
teamIdOrganization that owns this session
serverIdMCP server this session is connected to
statusactive, suspended, or completed
toolCallsCountNumber of tool calls in this session
startedAtWhen the session was created
suspendedAtWhen the kill switch was activated
suspendedReasonWhy 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

TransportHow it works
streamable-httpPOST returns an SSE stream. Modern MCP servers use this.
legacy-sseGET /sse endpoint for streaming, separate POST endpoint for requests. Older MCP servers.
http-jsonrpcStandard 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

TypeFormat
SlackBlock Kit message with emoji, structured fields
DiscordEmbed with color-coded severity
HTTPRaw 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:
FieldDescription
sessionIdSession this call belongs to
teamIdOrganization
serverIdTarget MCP server
toolNameName of the tool called
toolArgsArguments passed to the tool
policyActionallow, deny, or alert
policyRuleIdThe rule pattern that matched
timestampISO 8601 timestamp
latencyMsRound-trip time to upstream (for allowed calls)
errorError message (for failed calls)
Logging is asynchronous and non-blocking — it never slows down the proxy response.