Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.igrisecurity.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Tool Calls

When you’d rather not wire up your own MCP client, the SDK exposes igris.mcp — a small JSON-RPC client that speaks to the Igris gateway directly. Every call is policy-evaluated, identity-tagged, and audit-logged exactly the same way external MCP clients are.

​
When to use this

Use igris.mcp.* when…Use igris.connectHttp() when…
You’re calling tools from server-side code (jobs, agents, schedulers)You’re configuring an external MCP client (Claude Desktop, Cursor, VS Code, your own MCP-aware app)
You want zero extra dependencies on top of the SDKYou already use @modelcontextprotocol/sdk or another HTTP MCP client and want to keep that wiring
You want one return type (string content) instead of full JSON-RPC plumbingYou need raw access to MCP capabilities, prompts, resources, etc.
Both paths route through the same gateway, hit the same policies, and produce the same audit events.

​
API

igris.mcp.initialize(slug, options?): Promise<{ protocolVersion, serverInfo }>
igris.mcp.listTools(slug, options?):  Promise<McpTool[]>
igris.mcp.callTool(slug, toolName, args, options?): Promise<string>
All three accept the same McpConfigOptions: 
interface McpConfigOptions {
  user?: string;            // sent as X-Igris-User
  traceId?: string;         // sent as X-Igris-Trace-Id; auto-generated if omitted
  metadata?: Record<string, string | number | boolean>;
                            // sent as X-Igris-Metadata: <JSON>
}

​
Quick Start

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

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

// Optional handshake — useful for sanity checking that the connection is wired up.
const init = await igris.mcp.initialize("github-prod", {
  user: "alice@company.com",
});
console.log(init.serverInfo);
// { name: "github-mcp", version: "1.2.0" }

// Discover available tools.
const tools = await igris.mcp.listTools("github-prod", {
  user: "alice@company.com",
});
for (const tool of tools) {
  console.log(`${tool.name} — ${tool.description}`);
}

// Invoke a tool. The return value is the upstream tool's text content joined.
const output = await igris.mcp.callTool(
  "github-prod",
  "create_issue",
  {
    repo: "acme/igris",
    title: "Migration plan for v2",
    body: "Initial draft.",
  },
  {
    user: "alice@company.com",
    traceId: "trace-issue-triage-789",
    metadata: { feature: "issue-triage", env: "production" },
  },
);

console.log(output);
Every call hits https://api.igrisecurity.com/v1/mcp/<slug> (or your self-hosted gateway), carries Authorization: Bearer <apiKey>, and is policy-evaluated server-side before being forwarded to the upstream MCP server with its real credential injected.

​
Threading multiple calls under one trace

If a single user request triggers several tool calls, share the trace id so Lens can show the whole chain as one operation: 
const traceId = "trace-" + crypto.randomUUID();
const opts = { user: "alice@company.com", traceId };

await igris.mcp.callTool("github-prod", "list_issues", { repo: "acme/igris" }, opts);
await igris.mcp.callTool("slack-prod",  "post_message", {
  channel: "#triage",
  text: "Top 3 issues this week ...",
}, opts);
Both rows in the audit trail will share traceId = "trace-...", which lets you filter Lens to the full sequence.

​
Error handling

igris.mcp.callTool throws on policy denial, rate limiting, auth failure, and upstream errors. Pattern-match with the typed error classes: 
import {
  IgrisPolicyDeniedError,
  IgrisRateLimitError,
  IgrisAuthError,
  IgrisError,
} from "@igris-security/sdk";

try {
  await igris.mcp.callTool("github-prod", "delete_repo", { repo: "acme/legacy" });
} catch (e) {
  if (e instanceof IgrisPolicyDeniedError) {
    // 403 — denied by a policy rule. e.response carries the rule that fired.
  } else if (e instanceof IgrisRateLimitError) {
    // 429 — back off and retry.
  } else if (e instanceof IgrisAuthError) {
    // 401 — bad or missing API key.
  } else if (e instanceof IgrisError) {
    // any other gateway error
  } else {
    throw e;
  }
}

​
What gets logged

Every initialize, listTools, and callTool produces an audit event with:
  • The actor (user, derived from X-Igris-User)
  • The connection slug
  • The tool name and arguments (for callTool)
  • The policy decision (allow / deny / alert)
  • Any matched rule and conditions
  • The trace id (X-Igris-Trace-Id)
  • All metadata fields (X-Igris-Metadata)
  • The timing and outcome
All of this surfaces in Lens and is queryable via the audit-events API.
  • Connections — how to register the upstream MCP server and store its credential
  • Identity & Metadata — what the gateway does with user, traceId, and metadata
  • Policies — how to gate tools/call by tool name, user, or metadata
  • MCP Client Config — the alternative path: drive an external MCP client