Skip to main content

​
Sessions

Agent sessions are automatically created when an MCP client begins making tool calls through the Igris gateway. They provide a grouping mechanism for related tool calls and a kill switch for immediate control. Source: packages/proxy/src/session-manager.ts, apps/api/src/routes/sessions.ts.

​
How Sessions Work

When the proxy receives a tool call, Igris checks for an active session for that organization + connection combination. If none exists, one is created automatically. Each session tracks:
  • Organization — which org owns this session
  • Connection — which connection the calls are routed through
  • Status — active, suspended, or completed
  • Tool call count — total number of calls in this session
  • Started at — when the session was created
Sessions expire after 30 minutes of inactivity. Last-access time is tracked internally for TTL purposes only; there is no updatedAt field on the session object.

​
Session Deduplication

Igris prevents duplicate sessions for the same org + connection combination. If a session already exists and is active, new tool calls join that session rather than creating a new one. This keeps the audit trail clean and the kill switch effective.

​
Kill Switch

The kill switch lets you instantly suspend a session. When suspended:
  • All incoming tool calls for that session return a JSON-RPC error: "Agent session suspended by kill switch"
  • The upstream MCP server receives no further requests
  • A session_suspended webhook is dispatched to any registered webhook endpoints
Suspension dispatches a webhook but does not log an audit event and does not emit an SSE event. Notification is via webhook only.

​
Suspending via API

POST https://api.igrisecurity.com/api/v1/sessions/{id}/suspend
Authorization: Bearer <token>
Content-Type: application/json

{ "reason": "Suspected credential exfiltration" }
Response: 
{ "suspended": true }

​
Resuming via API

POST https://api.igrisecurity.com/api/v1/sessions/{id}/resume
Authorization: Bearer <token>
Response: 
{ "resumed": true }

​
Listing Sessions

GET https://api.igrisecurity.com/api/v1/sessions?status=active
Authorization: Bearer <token>
Filter by status=active, status=suspended, or status=completed. Multiple statuses can be comma-separated.

​
Use Cases

  • Incident response — immediately halt a misbehaving agent without restarting infrastructure
  • Maintenance windows — suspend sessions during database maintenance
  • Investigation — pause activity while reviewing anomaly alerts
  • Cost control — stop a runaway agent racking up API costs
  • Policies — rules that govern what tool calls are allowed in a session
  • Anomaly Detection — automatic alerts on rate spikes and destructive patterns
  • Tool Calls — how igris.mcp calls flow through the proxy and are audit-logged