What is Igris?

Igris is an AI governance gateway that sits between your AI agents and MCP servers. It enforces security policies, tracks who called what tool and when, detects anomalies, and gives you a complete audit trail.

The SDK connects your application to the Igris gateway with type-safe APIs.

Install

# bun
bun add @igris-security/sdk

# npm
npm install @igris-security/sdk

# pnpm
pnpm add @igris-security/sdk

Quick Start

import { Igris } from "@igris-security/sdk";

const igris = new Igris({
  apiKey: "ig_your_api_key",
  baseUrl: "https://your-igris-instance.com", // optional, defaults to api.igrisecurity.com
});

// Get HTTP connection config for your AI agent
const httpConfig = igris.connectHttp("my-connection", {
  user: "[email protected]",
  metadata: { role: "developer", team: "platform" },
});

console.log(httpConfig);
// {
//   url: "https://your-igris-instance.com/v1/mcp/my-connection",
//   headers: {
//     Authorization: "Bearer ig_your_api_key",
//     "X-Igris-Trace-Id": "ig_trace_a1b2c3d4e5f6g7h8",
//     "X-Igris-User": "[email protected]",
//     "X-Igris-Metadata": '{"role":"developer","team":"platform"}'
//   }
// }

Usage with MCP Clients

Claude Desktop / Cursor / Windsurf

Use the SDK to generate the MCP config, then pass it to your MCP client:

import { Igris } from "@igris-security/sdk";

const igris = new Igris({ apiKey: process.env.IGRIS_API_KEY! });

// Every tool call now flows through the Igris gateway
const config = igris.connectHttp("my-mcp-server", {
  user: "[email protected]",
  traceId: "session-abc-123", // optional: correlate requests
  metadata: { role: "admin" }, // optional: used for policy conditions
});

// Use config.url and config.headers with your MCP client

Standalone Function

If you don't need the full client, use buildHttpConnection directly:

import { buildHttpConnection } from "@igris-security/sdk";

const config = buildHttpConnection(
  "ig_your_api_key",
  "https://your-igris-instance.com",
  "my-connection",
  { user: "[email protected]" },
);

Resource APIs

The SDK provides typed access to the Igris management API for programmatic control.

Connections (Virtual Keys)

// List all connections
const { data: connections } = await igris.virtualKeys.list();

// Get a specific connection by slug
const connection = await igris.virtualKeys.get("my-connection");
console.log(connection.upstreamUrl); // "https://my-mcp-server.com"

Policies

// List all policies
const { data: policies } = await igris.policies.list();

// List policies for a specific connection
const { data: filtered } = await igris.policies.list({
  virtualKeySlug: "my-connection",
});

// Get a specific policy
const policy = await igris.policies.get("policy-uuid");
console.log(policy.rules);
// [
//   { tool: "delete_*", action: "deny", conditions: { "metadata.role": "viewer" } },
//   { tool: "*", action: "allow" }
// ]

Audit Events

// List recent audit events
const { data: events } = await igris.auditEvents.list({ limit: 50 });

// Filter by user
const { data: userEvents } = await igris.auditEvents.list({
  userId: "[email protected]",
});

// Filter by trace ID (correlate a session)
const { data: traceEvents } = await igris.auditEvents.list({
  traceId: "ig_trace_a1b2c3d4e5f6g7h8",
});

// Filter by connection
const { data: connectionEvents } = await igris.auditEvents.list({
  virtualKey: "my-connection",
  limit: 100,
  offset: 0,
});

Identity & Tracing

Igris tracks who made each tool call and lets you correlate requests across sessions.

User Identity

Pass user to attach a user identity to every tool call flowing through the gateway:

const config = igris.connectHttp("my-connection", {
  user: "[email protected]",
});

This shows up in the audit trail and can be used in policy conditions:

{ "tool": "delete_*", "action": "deny", "conditions": { "metadata.role": "viewer" } }

Trace IDs

Every request gets an auto-generated trace ID (ig_trace_...). You can also provide your own:

const config = igris.connectHttp("my-connection", {
  traceId: "my-custom-trace-id",
});

Use trace IDs to correlate all tool calls within a single agent session.

Metadata

Attach arbitrary key-value metadata for policy evaluation:

const config = igris.connectHttp("my-connection", {
  user: "[email protected]",
  metadata: {
    role: "developer",
    team: "platform",
    environment: "production",
  },
});

Metadata is available in policy conditions via dot notation: metadata.role, metadata.team, etc.

Headers Reference

| Header | Description | Auto-generated | |--------|-------------|:--------------:| | Authorization | Bearer <apiKey> | Yes | | X-Igris-Trace-Id | Trace ID for request correlation | Yes (overridable) | | X-Igris-User | User identity string | No | | X-Igris-Metadata | JSON-encoded metadata object | No |

API Reference

new Igris(config)

| Parameter | Type | Required | Description | |-----------|------|:--------:|-------------| | config.apiKey | string | Yes | Your Igris API key (starts with ig_) | | config.baseUrl | string | No | Gateway URL. Defaults to https://api.igrisecurity.com |

igris.connectHttp(slug, options?)

Returns { url: string, headers: Record<string, string> } for wiring into an MCP client.

| Parameter | Type | Required | Description | |-----------|------|:--------:|-------------| | slug | string | Yes | Connection slug (virtual key) | | options.user | string | No | User identity | | options.traceId | string | No | Custom trace ID (auto-generated if omitted) | | options.metadata | Record<string, string \| number \| boolean> | No | Key-value pairs for policy conditions |

igris.virtualKeys

| Method | Returns | Description | |--------|---------|-------------| | .list() | PaginatedResponse<VirtualKey> | List all connections | | .get(slug) | VirtualKey | Get connection by slug |

igris.policies

| Method | Returns | Description | |--------|---------|-------------| | .list(params?) | PaginatedResponse<Policy> | List policies. Filter with { virtualKeySlug } | | .get(id) | Policy | Get policy by ID |

igris.auditEvents

| Method | Returns | Description | |--------|---------|-------------| | .list(params?) | PaginatedResponse<AuditEvent> | List audit events. Filter with { userId, traceId, virtualKey, limit, offset } |

Types

All types are exported from the package:

import type {
  IgrisConfig,
  HttpConnection,
  HttpConnectionOptions,
  VirtualKey,
  Policy,
  PolicyRule,
  AuditEvent,
  PaginatedResponse,
} from "@igris-security/sdk";

Full Example

A complete example: an AI agent simulator that makes governed MCP tool calls through the Igris gateway with role-based policy enforcement.

import { Igris } from "@igris-security/sdk";

// ── Setup ────────────────────────────────────────────────────
const igris = new Igris({
  apiKey: process.env.IGRIS_API_KEY!,
  baseUrl: "http://localhost:3100",
});

// ── Helper: Make a governed MCP tool call ────────────────────
async function callTool(
  connectionSlug: string,
  toolName: string,
  args: Record<string, unknown>,
  user: string,
  metadata: Record<string, string> = {},
) {
  // Get gateway config with user identity + metadata for policy evaluation
  const mcp = igris.connectHttp(connectionSlug, { user, metadata });

  // Make the JSON-RPC call through the gateway
  const res = await fetch(mcp.url, {
    method: "POST",
    headers: mcp.headers,
    body: JSON.stringify({
      jsonrpc: "2.0",
      method: "tools/call",
      params: { name: toolName, arguments: args },
      id: Date.now(),
    }),
  });

  const json = (await res.json()) as any;

  if (json.error) {
    return { allowed: false, error: json.error.message };
  }

  const text = json.result?.content?.[0]?.text;
  return { allowed: true, result: text ? JSON.parse(text) : json.result };
}

// ── Scenario: Role-based access control ──────────────────────
//
// Policy on the gateway:
//   { tool: "delete_*", action: "deny", conditions: { "metadata.role": "viewer" } }
//   { tool: "*", action: "allow" }

const CONNECTION = "my-mcp-server";

console.log("=== Admin user (full access) ===\n");

const weather = await callTool(
  CONNECTION,
  "get_weather",
  { city: "San Francisco" },
  "[email protected]",
  { role: "admin" },
);
console.log(`  get_weather: ${weather.allowed ? "ALLOWED" : "DENIED"}`);

const deleteResult = await callTool(
  CONNECTION,
  "delete_record",
  { id: "rec_123" },
  "[email protected]",
  { role: "admin" },
);
console.log(`  delete_record: ${deleteResult.allowed ? "ALLOWED" : "DENIED"}`);

console.log("\n=== Viewer user (restricted) ===\n");

const viewerWeather = await callTool(
  CONNECTION,
  "get_weather",
  { city: "Tokyo" },
  "[email protected]",
  { role: "viewer" },
);
console.log(`  get_weather: ${viewerWeather.allowed ? "ALLOWED" : "DENIED"}`);

const viewerDelete = await callTool(
  CONNECTION,
  "delete_record",
  { id: "rec_456" },
  "[email protected]",
  { role: "viewer" },
);
console.log(`  delete_record: ${viewerDelete.allowed ? "DENIED" : "ALLOWED"}`);
// → DENIED by policy: delete_* blocked for viewers

// ── Query the audit trail ────────────────────────────────────
console.log("\n=== Audit Trail ===\n");

const { data: events } = await igris.auditEvents.list({ limit: 10 });

for (const event of events) {
  console.log(
    `  [${event.policyAction?.toUpperCase().padEnd(5)}] ${event.toolName?.padEnd(20)} by ${event.userId ?? "unknown"}`,
  );
}
// Output:
//   [DENY ] delete_record        by [email protected]
//   [ALLOW] get_weather           by [email protected]
//   [ALLOW] delete_record         by [email protected]
//   [ALLOW] get_weather           by [email protected]

// ── List connections & policies ──────────────────────────────
const { data: connections } = await igris.virtualKeys.list();
console.log(`\nConnections: ${connections.map((c) => c.slug).join(", ")}`);

const { data: policies } = await igris.policies.list({
  virtualKeySlug: CONNECTION,
});
for (const policy of policies) {
  console.log(`\nPolicy: ${policy.name}`);
  for (const rule of policy.rules) {
    console.log(`  ${rule.tool} → ${rule.action}`);
  }
}

Save as demo.ts and run:

IGRIS_API_KEY=ig_your_key bun demo.ts

Requirements

• Node.js 18+ or Bun 1.0+
• An Igris API key (get one from the dashboard)

Links

• Documentation
• Dashboard
• GitHub
• npm

License

MIT