@ory/argus 1.5.3 → 1.7.0

package/dist/mcp.js

@@ -4,15 +4,25 @@
  *
  * Provides types, parsers, and permission check helpers for securing
  * MCP tool calls across all harness plugins. Each harness represents
- * MCP tools differently — parsers normalize them into McpToolIdentifier,
- * and checkMcpPermission runs server-level (and optionally tool-level)
- * Ory permission checks.
+ * MCP tools differently — parsers normalize them into McpToolIdentifier.
+ * Adapters pass that identifier to `gate`, which checks the McpServer and
+ * McpTool namespaces with the same block and mode semantics as native tools.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseClaudeCodeMcpTool = parseClaudeCodeMcpTool;
 exports.parseGeminiMcpTool = parseGeminiMcpTool;
+exports.parseMcpToolWithSeparator = parseMcpToolWithSeparator;
 exports.parseMcpToolGeneric = parseMcpToolGeneric;
+exports.mcpFingerprint = mcpFingerprint;
+exports.mcpServerFingerprints = mcpServerFingerprints;
+exports.mcpServerHint = mcpServerHint;
+exports.normalizeMcpServerName = normalizeMcpServerName;
+exports.mcpToolObject = mcpToolObject;
+exports.parseMcpToolName = parseMcpToolName;
+exports.parseMcpToolArgs = parseMcpToolArgs;
 exports.checkMcpPermission = checkMcpPermission;
+const node_crypto_1 = require("node:crypto");
+const opl_js_1 = require("./opl.js");
 const read_credential_js_1 = require("./read-credential.js");
 // ─── Parsers ───────────────────────────────────────────────────────
 /**
@@ -37,16 +47,53 @@ function parseClaudeCodeMcpTool(toolName) {
 }
 /**
  * Parse MCP context from Gemini CLI hook input.
- * Gemini provides server info via the `mcp_context` field.
+ *
+ * Gemini provides server info via the `mcp_context` field: the configured
+ * `server_name`, the server's own `tool_name` (the hook `tool_name` is the
+ * prefixed `mcp_<server>_<tool>` form), and how the server is launched or
+ * reached (`command`, `args`, `url`).
  */
 function parseGeminiMcpTool(toolName, mcpContext) {
     if (!mcpContext || typeof mcpContext.server_name !== "string")
         return null;
+    const fingerprints = mcpServerFingerprints({
+        url: typeof mcpContext.url === "string" ? mcpContext.url : undefined,
+        command: typeof mcpContext.command === "string" ? mcpContext.command : undefined,
+        args: Array.isArray(mcpContext.args)
+            ? mcpContext.args.filter((arg) => typeof arg === "string")
+            : undefined,
+    });
     return {
         serverName: mcpContext.server_name,
-        toolName,
+        toolName: typeof mcpContext.tool_name === "string" && mcpContext.tool_name !== "" ? mcpContext.tool_name : toolName,
+        ...(fingerprints.length > 0 ? { fingerprints } : {}),
     };
 }
+/**
+ * Parse a `<server><separator><tool>` tool name, as Goose (`__`), OpenClaw
+ * (`__`), Cline (`__`), and OpenCode (`_`) build them. With `servers`, the
+ * longest configured server name that prefixes the tool name wins, so server
+ * names containing the separator split correctly and native tools without a
+ * server prefix return null. Without `servers`, the first separator splits.
+ */
+function parseMcpToolWithSeparator(toolName, separator, servers) {
+    if (servers) {
+        let match;
+        for (const server of servers) {
+            if (server !== "" &&
+                toolName.length > server.length + separator.length &&
+                toolName.startsWith(server + separator) &&
+                server.length > (match?.length ?? -1)) {
+                match = server;
+            }
+        }
+        return match === undefined ? null : { serverName: match, toolName: toolName.slice(match.length + separator.length) };
+    }
+    const index = toolName.indexOf(separator);
+    if (index <= 0 || index + separator.length >= toolName.length)
+        return null;
+    return { serverName: toolName.slice(0, index), toolName: toolName.slice(index + separator.length) };
+}
 /**
  * Generic MCP tool parser for harnesses that use a `mcp:<server>:<tool>`
  * convention. Returns null if the tool ID doesn't start with the prefix.
@@ -56,6 +103,8 @@ function parseMcpToolGeneric(toolId, mcpPrefix = "mcp:") {
         return null;
     const rest = toolId.slice(mcpPrefix.length);
     const sepIdx = rest.indexOf(":");
+    if (sepIdx === 0 || rest === "")
+        return null;
     if (sepIdx === -1) {
         return { serverName: rest, toolName: "" };
     }
@@ -64,40 +113,224 @@ function parseMcpToolGeneric(toolId, mcpPrefix = "mcp:") {
         toolName: rest.slice(sepIdx + 1),
     };
 }
+// ─── Fingerprints ──────────────────────────────────────────────────
+const MAX_MCP_FINGERPRINTS = 4;
+const PACKAGE_RUNNERS = new Set(["npx", "bunx", "uvx", "pipx", "deno"]);
+const PACKAGE_RUNNER_SUBCOMMANDS = new Set(["dlx", "exec", "run", "x", "tool"]);
+/** Runners whose package follows one of {@link PACKAGE_RUNNER_SUBCOMMANDS} (`deno run npm:@scope/mcp`). */
+const SUBCOMMAND_RUNNERS = new Set(["pnpm", "yarn", "bun", "uv", "pipx", "deno"]);
+const CONTAINER_RUNNERS = new Set(["docker", "podman"]);
+/** Container global flags, before the subcommand, that take a separate value argument. */
+const CONTAINER_GLOBAL_VALUE_FLAGS = new Set([
+    "-H", "--host", "-c", "--context", "--config", "-l", "--log-level", "--tlscacert", "--tlscert", "--tlskey",
+    "--connection", "--url", "--identity", "--root", "--runroot", "--storage-driver", "--cgroup-manager",
+]);
+/** Container `run` flags that take a separate value argument. Unlisted flags are treated as boolean. */
+const CONTAINER_VALUE_FLAGS = new Set([
+    "-a", "--attach", "--annotation", "--add-host", "--blkio-weight", "--blkio-weight-device", "--cap-add", "--cap-drop",
+    "--cgroup-parent", "--cgroupns", "--cidfile", "-c", "--cpu-shares", "--cpu-period", "--cpu-quota", "--cpu-rt-period",
+    "--cpu-rt-runtime", "--cpus", "--cpuset-cpus", "--cpuset-mems", "--detach-keys", "--device", "--device-cgroup-rule",
+    "--device-read-bps", "--device-read-iops", "--device-write-bps", "--device-write-iops", "--dns", "--dns-option",
+    "--dns-search", "--domainname", "-e", "--env", "--env-file", "--entrypoint", "--expose", "--gpus", "--group-add",
+    "--health-cmd", "--health-interval", "--health-retries", "--health-start-interval", "--health-start-period",
+    "--health-timeout", "-h", "--hostname", "--ip", "--ip6", "--ipc", "--isolation", "--kernel-memory", "-l", "--label",
+    "--label-file", "--link", "--link-local-ip", "--log-driver", "--log-opt", "--mac-address", "-m", "--memory",
+    "--memory-reservation", "--memory-swap", "--memory-swappiness", "--mount", "--name", "--network", "--net",
+    "--network-alias", "--oom-score-adj", "-p", "--publish", "--pid", "--pids-limit", "--platform", "--pull",
+    "--restart", "--runtime", "--security-opt", "--shm-size", "--stop-signal", "--stop-timeout", "--storage-opt",
+    "--sysctl", "--tmpfs", "-u", "--user", "--ulimit", "--userns", "--uts", "-v", "--volume", "--volume-driver",
+    "--volumes-from", "-w", "--workdir", "--arch", "--os", "--variant", "--secret", "--hooks-dir", "--pod",
+    "--uidmap", "--gidmap", "--subuidname", "--subgidname", "--userns-uid-map", "--userns-gid-map",
+]);
+/**
+ * The hash Agent Security matches against cataloged server identifiers: the
+ * first 16 hex characters of the SHA-256 of the trimmed, lowercased identifier.
+ */
+function mcpFingerprint(identifier) {
+    return (0, node_crypto_1.createHash)("sha256").update(identifier.trim().toLowerCase()).digest("hex").slice(0, 16);
+}
+/**
+ * Hash the identifiers that recognize an MCP server whatever it is named: the
+ * remote URL host, the package a runner launches (`npx -y @playwright/mcp@1`
+ * yields `@playwright/mcp`), or the container image (`ghcr.io/github/github-mcp-server`).
+ * Only hashes leave the process; paths, arguments, and credentials are never sent.
+ */
+function mcpServerFingerprints(source) {
+    const identifiers = new Set();
+    const host = urlHost(source.url);
+    if (host)
+        identifiers.add(host);
+    const words = [...(source.command ? source.command.trim().split(/\s+/) : []), ...(source.args ?? [])].filter((word) => word !== "");
+    const launched = launchedIdentifier(words);
+    if (launched)
+        identifiers.add(launched);
+    return [...identifiers].slice(0, MAX_MCP_FINGERPRINTS).map(mcpFingerprint);
+}
+function urlHost(value) {
+    if (!value)
+        return undefined;
+    try {
+        return new URL(value).hostname.toLowerCase() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function launchedIdentifier(words) {
+    const [command, ...rest] = words;
+    if (!command)
+        return undefined;
+    const runner = command.split(/[\\/]/).pop().toLowerCase().replace(/\.(exe|cmd)$/, "");
+    if (CONTAINER_RUNNERS.has(runner)) {
+        const runIndex = containerRunIndex(rest);
+        if (runIndex < 0)
+            return undefined;
+        for (let index = runIndex + 1; index < rest.length; index++) {
+            const word = rest[index];
+            if (word.startsWith("-")) {
+                if (!word.includes("=") && CONTAINER_VALUE_FLAGS.has(word))
+                    index++;
+                continue;
+            }
+            return containerImage(word);
+        }
+        return undefined;
+    }
+    let args = rest;
+    if (SUBCOMMAND_RUNNERS.has(runner)) {
+        while (args[0] && PACKAGE_RUNNER_SUBCOMMANDS.has(args[0]))
+            args = args.slice(1);
+    }
+    else if (!PACKAGE_RUNNERS.has(runner)) {
+        return undefined;
+    }
+    for (let index = 0; index < args.length; index++) {
+        const word = args[index];
+        if (word === "-p" || word === "--package" || word === "--from") {
+            const value = args[index + 1];
+            return value ? packageName(value) : undefined;
+        }
+        if (word.startsWith("-"))
+            continue;
+        return packageName(word);
+    }
+    return undefined;
+}
+/**
+ * The index of the `run` subcommand in a container command's arguments, after
+ * any global flags (`docker --context remote run …`, `podman container run …`),
+ * or -1 when the command runs nothing.
+ */
+function containerRunIndex(args) {
+    for (let index = 0; index < args.length; index++) {
+        const word = args[index];
+        if (word.startsWith("-")) {
+            if (!word.includes("=") && CONTAINER_GLOBAL_VALUE_FLAGS.has(word))
+                index++;
+            continue;
+        }
+        if (word === "container" && args[index + 1] === "run")
+            return index + 1;
+        return word === "run" ? index : -1;
+    }
+    return -1;
+}
+function packageName(spec) {
+    let name = spec.replace(/^npm:|^jsr:/, "");
+    const versionAt = name.lastIndexOf("@");
+    if (versionAt > 0)
+        name = name.slice(0, versionAt);
+    name = name.replace(/\[.*\]$/, "").replace(/[=<>~!].*$/, "");
+    if (name === "" || name.includes("://") || name.startsWith(".") || name.startsWith("/"))
+        return undefined;
+    return name.toLowerCase();
+}
+function containerImage(reference) {
+    let image = reference.toLowerCase().split("@")[0];
+    const lastSlash = image.lastIndexOf("/");
+    const tag = image.indexOf(":", lastSlash + 1);
+    if (tag >= 0)
+        image = image.slice(0, tag);
+    image = image.replace(/^(docker\.io|index\.docker\.io)\//, "").replace(/^library\//, "");
+    return image || undefined;
+}
+/** The `mcp` hint Agent Security resolves an MCP check's server from. */
+function mcpServerHint(mcpTool) {
+    return {
+        server: mcpTool.serverName,
+        ...(mcpTool.toolName ? { tool: mcpTool.toolName } : {}),
+        ...(mcpTool.fingerprints?.length ? { fingerprints: mcpTool.fingerprints.slice(0, MAX_MCP_FINGERPRINTS) } : {}),
+    };
+}
+// ─── Normalization ─────────────────────────────────────────────────
+/**
+ * Normalize a configured MCP server name to the reported `McpServer` object:
+ * trimmed and lowercased. Agent Security resolves it, with the check's `mcp`
+ * hint, to the catalog server it enforces.
+ */
+function normalizeMcpServerName(serverName) {
+    return serverName.trim().toLowerCase();
+}
+/** The `McpTool` object for one call: `<server>:<tool>`. */
+function mcpToolObject(serverName, toolName) {
+    return `${normalizeMcpServerName(serverName)}:${toolName}`;
+}
+/**
+ * Parse a harness MCP tool name in either the `mcp__<server>__<tool>` form
+ * (Claude Code, Claude Agent SDK, Codex) or the `mcp:<server>:<tool>` form
+ * (OpenCode, OpenClaw, and older Codex builds).
+ */
+function parseMcpToolName(toolName) {
+    return parseClaudeCodeMcpTool(toolName) ?? parseMcpToolGeneric(toolName);
+}
+/**
+ * Parse the arguments of a generic "call an MCP tool" harness tool, such as
+ * Cline's `use_mcp_tool` (`{ server_name, tool_name, arguments }`). Returns null
+ * unless both a server and a tool name are present.
+ */
+function parseMcpToolArgs(toolArgs) {
+    if (!toolArgs || typeof toolArgs !== "object")
+        return null;
+    const args = toolArgs;
+    const serverName = [args.server_name, args.serverName, args.ServerName].find((value) => typeof value === "string" && value.trim() !== "");
+    const toolName = [args.tool_name, args.toolName, args.ToolName].find((value) => typeof value === "string" && value.trim() !== "");
+    return serverName && toolName ? { serverName, toolName } : null;
+}
 // ─── Permission Check ──────────────────────────────────────────────
 /**
- * Check MCP server-level (and optionally tool-level) permissions.
+ * Check the user's MCP `use` permits without machine-principal blocks or mode.
  *
- * Server check: namespace=mcp_servers, object=<serverName>, relation=use
- * Tool check:   namespace=mcp_tools,   object=<server>:<tool>, relation=invoke
+ * Server check: `McpServer:<server>#use`. Tool check, when the tool name is
+ * known and `checkToolLevel` is not false: `McpTool:<server>:<tool>#use`. The
+ * server name is normalized with {@link normalizeMcpServerName}.
  *
- * The subject is whatever the caller resolved (SubjectSet or direct ID).
+ * Harness adapters should pass `mcpTool` to `gate` / `decideTool` instead, which
+ * also applies Agent, Sub-Agent, and Project blocks and the permission mode.
  * Throws on API errors — callers handle fail-open behavior.
  */
 async function checkMcpPermission(client, mcpTool, options) {
-    const serverNamespace = options.serverNamespace ??
-        (process.env.ORY_MCP_SERVER_NAMESPACE ?? "mcp_servers");
-    const toolNamespace = options.toolNamespace ??
-        (process.env.ORY_MCP_TOOL_NAMESPACE ?? "mcp_tools");
-    const checkToolLevel = options.checkToolLevel ??
-        process.env.ORY_MCP_TOOL_LEVEL_CHECKS === "true";
+    const serverNamespace = options.serverNamespace ?? opl_js_1.MCP_SERVER_NAMESPACE;
+    const toolNamespace = options.toolNamespace ?? opl_js_1.MCP_TOOL_NAMESPACE;
+    const checkToolLevel = options.checkToolLevel ?? true;
+    const serverName = normalizeMcpServerName(mcpTool.serverName);
     // MCP tool calls arrive on the same subprocess lifecycle events as any other
     // tool, so this read needs a credential resolved for exactly the reasons
     // `gateToolCall` does (#242).
     await (0, read_credential_js_1.ensureReadCredential)(client);
+    const mcp = mcpServerHint(mcpTool);
     const serverCheck = {
         namespace: serverNamespace,
-        object: mcpTool.serverName,
-        relation: "users",
+        object: serverName,
+        relation: opl_js_1.PERMIT_USE,
         ...options.subject,
+        mcp,
     };
     const activityAttributes = {
         mcpServer: mcpTool.serverName,
         ...(mcpTool.toolName ? { mcpTool: mcpTool.toolName } : {}),
         ...options.activityAttributes,
     };
-    if (!checkToolLevel || !mcpTool.toolName) {
-        // Server-only check
+    if (!checkToolLevel) {
         const result = await client.checkPermission(serverCheck, { activityAttributes });
         return {
             serverAllowed: result.allowed,
@@ -107,12 +340,12 @@ async function checkMcpPermission(client, mcpTool, options) {
             mcpTool,
         };
     }
-    // Batch check: server + tool
     const toolCheck = {
         namespace: toolNamespace,
-        object: `${mcpTool.serverName}:${mcpTool.toolName}`,
-        relation: "invoke",
+        object: mcpToolObject(serverName, mcpTool.toolName ?? ""),
+        relation: opl_js_1.PERMIT_USE,
         ...options.subject,
+        mcp,
     };
     const batchResult = await client.batchCheckPermissions([serverCheck, toolCheck], { activityAttributes });
     const serverAllowed = batchResult.results[0]?.allowed ?? false;

package/dist/opl.d.ts

@@ -86,6 +86,16 @@ export declare const DEFAULT_NAMESPACE = "AgentTool";
  * `resolveShellCommandNamespace()` in tool-catalog.ts.
  */
 export declare const DEFAULT_SHELL_NAMESPACE = "ShellTool";
+/**
+ * Namespaces for MCP calls. A call is checked as `McpServer:<server>#use` and
+ * `McpTool:<server>:<tool>#use`, where `<server>` is the lowercased configured
+ * server name. Same default-allow / explicit-block model as the native tool
+ * namespaces; Agent Security projects per-server Admin, Write, Read, and No
+ * access levels into them. Not operator-configurable: the server catalog owns
+ * the objects.
+ */
+export declare const MCP_SERVER_NAMESPACE = "McpServer";
+export declare const MCP_TOOL_NAMESPACE = "McpTool";
 /**
  * Namespace for delegation nodes — the current-state graph of who delegated to
  * whom (`Delegation:agent:<join>`, `Delegation:subagent:<join>|<type>`). Its own
@@ -232,7 +242,7 @@ export declare function renderPrincipalClass(name: string): string;
 /**
  * Render a native tool-namespace class body: the `blockedSubjects` relation and
  * the default-allow `use` permit Argus checks. The single definition is used for
- * both AgentTool and ShellTool; MCP namespaces remain grant-based elsewhere.
+ * AgentTool, ShellTool, McpServer, and McpTool.
  */
 export declare function renderToolNamespaceClass(namespace?: string): string;
 /**

package/dist/opl.js

@@ -35,7 +35,7 @@
  * grant relation is the plural `users` and the permit the singular verb `use`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NODE_REFERENCE_NAMESPACES = exports.PRINCIPAL_NAMESPACES = exports.OPL_IMPORT_SYMBOLS = exports.OPL_IMPORT_MODULE = exports.PERMIT_USE = exports.PROJECT_POSTURE_OBJECT = exports.PERMISSION_MODE_OBJECT = exports.PERMISSION_MODE_NAMESPACE = exports.RELATION_OPTED_OUT_SUBJECTS = exports.AUTO_ENROLL_OBJECT = exports.ENROLLMENT_NAMESPACE = exports.RELATION_MEMBERS = exports.SUBAGENT_TYPE_NAMESPACE = exports.AGENT_TYPE_NAMESPACE = exports.AGENT_ROLE_NAMESPACE = exports.SUBAGENT_NODE_NAMESPACE = exports.AGENT_NODE_NAMESPACE = exports.DELEGATION_NAMESPACE = exports.DEFAULT_SHELL_NAMESPACE = exports.DEFAULT_NAMESPACE = exports.RELATION_ENFORCED_SUBJECTS = exports.RELATION_CREDENTIALS = exports.RELATION_BLOCKED_SUBJECTS = exports.RELATION_DELEGATES = exports.RELATION_USERS = void 0;
+exports.NODE_REFERENCE_NAMESPACES = exports.PRINCIPAL_NAMESPACES = exports.OPL_IMPORT_SYMBOLS = exports.OPL_IMPORT_MODULE = exports.PERMIT_USE = exports.PROJECT_POSTURE_OBJECT = exports.PERMISSION_MODE_OBJECT = exports.PERMISSION_MODE_NAMESPACE = exports.RELATION_OPTED_OUT_SUBJECTS = exports.AUTO_ENROLL_OBJECT = exports.ENROLLMENT_NAMESPACE = exports.RELATION_MEMBERS = exports.SUBAGENT_TYPE_NAMESPACE = exports.AGENT_TYPE_NAMESPACE = exports.AGENT_ROLE_NAMESPACE = exports.SUBAGENT_NODE_NAMESPACE = exports.AGENT_NODE_NAMESPACE = exports.DELEGATION_NAMESPACE = exports.MCP_TOOL_NAMESPACE = exports.MCP_SERVER_NAMESPACE = exports.DEFAULT_SHELL_NAMESPACE = exports.DEFAULT_NAMESPACE = exports.RELATION_ENFORCED_SUBJECTS = exports.RELATION_CREDENTIALS = exports.RELATION_BLOCKED_SUBJECTS = exports.RELATION_DELEGATES = exports.RELATION_USERS = void 0;
 exports.renderOplImport = renderOplImport;
 exports.renderPrincipalClass = renderPrincipalClass;
 exports.renderToolNamespaceClass = renderToolNamespaceClass;
@@ -99,6 +99,16 @@ exports.DEFAULT_NAMESPACE = "AgentTool";
  * `resolveShellCommandNamespace()` in tool-catalog.ts.
  */
 exports.DEFAULT_SHELL_NAMESPACE = "ShellTool";
+/**
+ * Namespaces for MCP calls. A call is checked as `McpServer:<server>#use` and
+ * `McpTool:<server>:<tool>#use`, where `<server>` is the lowercased configured
+ * server name. Same default-allow / explicit-block model as the native tool
+ * namespaces; Agent Security projects per-server Admin, Write, Read, and No
+ * access levels into them. Not operator-configurable: the server catalog owns
+ * the objects.
+ */
+exports.MCP_SERVER_NAMESPACE = "McpServer";
+exports.MCP_TOOL_NAMESPACE = "McpTool";
 /**
  * Namespace for delegation nodes — the current-state graph of who delegated to
  * whom (`Delegation:agent:<join>`, `Delegation:subagent:<join>|<type>`). Its own
@@ -259,7 +269,7 @@ function renderPrincipalClass(name) {
 /**
  * Render a native tool-namespace class body: the `blockedSubjects` relation and
  * the default-allow `use` permit Argus checks. The single definition is used for
- * both AgentTool and ShellTool; MCP namespaces remain grant-based elsewhere.
+ * AgentTool, ShellTool, McpServer, and McpTool.
  */
 function renderToolNamespaceClass(namespace = exports.DEFAULT_NAMESPACE) {
     return `class ${namespace} implements Namespace {
@@ -406,6 +416,13 @@ function buildAgentSecurityOpl(namespace = exports.DEFAULT_NAMESPACE, shellNames
         "// default-allow / explicit-block model as the tool namespace above.",
         renderToolNamespaceClass(shellNamespace),
         "",
+        `// MCP calls: \`${exports.MCP_SERVER_NAMESPACE}:<server>\` and \`${exports.MCP_TOOL_NAMESPACE}:<server>:<tool>\`. Agent`,
+        "// Security links a scope to per-server tier anchors to apply Admin, Write,",
+        "// Read, or No access. Same default-allow / explicit-block model.",
+        renderToolNamespaceClass(exports.MCP_SERVER_NAMESPACE),
+        "",
+        renderToolNamespaceClass(exports.MCP_TOOL_NAMESPACE),
+        "",
         "// The shared role whose members can be blocked as a group.",
         renderAgentRoleNamespaceClass(),
         "",

package/dist/permission-mode.d.ts

@@ -39,7 +39,7 @@
  *   3. **Persistent cache** — when the server is unreachable, fall back to the
  *      last value read from the server, persisted in `config.json`
  *      (`source: "cache"`).
- *   4. **`observe`** — nothing was ever cached (`source: "default"`).
+ *   4. **`enforce`** — a failed read and no applicable cache (`source: "default"`).
  *
  * The persistent cache is written by {@link warmPermissionModeCache} at session
  * start and when a gate first discovers a new acting-machine scope. It only
@@ -76,7 +76,7 @@ export declare function preparePermissionModeBatch(client: OryAgentClient, subje
 }): PermissionModeBatchPlan;
 /**
  * Resolve the current permission mode for `subject`. Never throws — a Keto
- * error falls back to the persistent cache, then `observe`. See the module
+ * error falls back to the persistent cache, then `enforce`. See the module
  * doc for the precedence. Does **not** persist (that is
  * {@link warmPermissionModeCache}'s job); `opts.now` is injectable for tests.
  */

package/dist/permission-mode.js

@@ -40,7 +40,7 @@
  *   3. **Persistent cache** — when the server is unreachable, fall back to the
  *      last value read from the server, persisted in `config.json`
  *      (`source: "cache"`).
- *   4. **`observe`** — nothing was ever cached (`source: "default"`).
+ *   4. **`enforce`** — a failed read and no applicable cache (`source: "default"`).
  *
  * The persistent cache is written by {@link warmPermissionModeCache} at session
  * start and when a gate first discovers a new acting-machine scope. It only
@@ -225,7 +225,7 @@ function fallbackPermissionMode(projectUrl, subjectKeys) {
         ? cache.mode
         : undefined;
     const mode = scopedMode ?? (legacyMode === "enforce" ? "enforce" : undefined);
-    return mode ? { mode, source: "cache" } : { mode: "observe", source: "default" };
+    return mode ? { mode, source: "cache" } : { mode: "enforce", source: "default" };
 }
 function persistPermissionModeMemo(client, projectUrl, now, requestedKeys) {
     const updates = {};
@@ -259,7 +259,7 @@ function persistPermissionModeMemo(client, projectUrl, now, requestedKeys) {
 }
 /**
  * Resolve the current permission mode for `subject`. Never throws — a Keto
- * error falls back to the persistent cache, then `observe`. See the module
+ * error falls back to the persistent cache, then `enforce`. See the module
  * doc for the precedence. Does **not** persist (that is
  * {@link warmPermissionModeCache}'s job); `opts.now` is injectable for tests.
  */
@@ -378,9 +378,9 @@ async function resolvePermissionMode(client, subject, opts = {}) {
         }
         client.logger.debug("permission.mode_default", {
             code: oryErr?.code,
-            note: "mode check failed and no cached value; defaulting to observe",
+            note: "mode check failed and no cached value; defaulting to enforce",
         });
-        return { mode: "observe", source: "default" };
+        return { mode: "enforce", source: "default" };
     }
 }
 /**

package/dist/permissions-cli.d.ts

@@ -11,7 +11,7 @@
  *
  * Everything that *writes* to the project is provisioned in the **Ory Console**
  * (Agent Security), not from the plugin: the permission model, explicit native
- * blocks, MCP grants, and the observe/enforce posture. That is what lets a
+ * blocks, MCP server access, and the observe/enforce posture. That is what lets a
  * plugin be installed with nothing but a project URL — the public OAuth2 client
  * id has a reserved default, with no workspace privilege, project API key, or admin write path. The
  * plugin is a read-only client of the project's permission state.

package/dist/permissions-cli.js

@@ -12,7 +12,7 @@
  *
  * Everything that *writes* to the project is provisioned in the **Ory Console**
  * (Agent Security), not from the plugin: the permission model, explicit native
- * blocks, MCP grants, and the observe/enforce posture. That is what lets a
+ * blocks, MCP server access, and the observe/enforce posture. That is what lets a
  * plugin be installed with nothing but a project URL — the public OAuth2 client
  * id has a reserved default, with no workspace privilege, project API key, or admin write path. The
  * plugin is a read-only client of the project's permission state.
@@ -78,7 +78,7 @@ function printPermissionsHelp(binName) {
     console.log("  observe  — Log an audit event and allow the tool through. The default.");
     console.log("  enforce  — Block the tool. The production posture.");
     console.log("");
-    console.log("The plugin only ever *reads* permissions. Native tool blocks, MCP grants,");
+    console.log("The plugin only ever *reads* permissions. Native tool blocks, MCP server access,");
     console.log("the permission model, and the observe/enforce posture are all managed in");
     console.log("the Ory Console (Agent Security) by someone with access to the project.");
     console.log("");
@@ -97,7 +97,7 @@ function printProvisioningMovedToConsole(binName, attempted) {
     console.error("Permissions are provisioned in the Ory Console (Agent Security):");
     console.error("  - the permission model applied to the project");
     console.error("  - explicit native-tool blocks for a user, agent, or group");
-    console.error("  - MCP grants");
+    console.error("  - MCP server access");
     console.error("  - the observe / enforce posture, project-wide or per principal");
     console.error("");
     console.error("The plugin reads that state and enforces it. To see what it resolves:");

package/dist/permissions.d.ts

@@ -13,9 +13,8 @@
  *          tool through.
  *        - `enforce` — return `{ kind: "deny", … }` so the caller blocks.
  *   3. On a thrown {@link OryError}, inspects the classified code:
- *        - Infrastructure errors (`network_error`, `rate_limited`,
- *          `not_found`, `unknown`) — returns `{ kind: "fail_open", … }`.
- *          Callers should log and allow.
+ *        - Network, rate-limit and server failures deny in enforce mode;
+ *          observe mode remains permissive.
  *        - Auth-rejected check calls (`forbidden`, `session_inactive`,
  *          `session_aal2_required` — the check itself was rejected, so
  *          its result cannot be trusted) — in `enforce` mode returns
@@ -27,6 +26,7 @@
  * opencode `throw OryDenialError`, etc.) without re-implementing the
  * mode logic.
  */
+import { type McpToolIdentifier } from "./mcp.js";
 import type { OryAgentClient } from "./client.js";
 import { type PermissionMode } from "./config.js";
 import type { OryError, OryErrorCode, PermissionCheck, PermissionResult } from "./types.js";
@@ -34,14 +34,14 @@ import type { OryError, OryErrorCode, PermissionCheck, PermissionResult } from "
  * Why a permission check came back denied, once the block-aware OPL schema is
  * in play:
  *
- *   - `not_granted` — compatibility for grant-based checks outside native
- *     AgentTool/ShellTool policy (notably MCP).
+ *   - `not_granted` — compatibility for grant-based checks outside the native
+ *     AgentTool, ShellTool, McpServer, and McpTool policy.
  *   - `explicit_block` — a native `use` permit denied because a
  *     `blockedSubjects` relation matched.
  *
  * Threaded onto the decision's activity attributes and into the observe-mode
  * audit event so "explicitly blocked" is distinguishable from "never granted"
- * in activity logs, mirroring how `checkRejected` distinguishes an auth-rejected
+ * in activity logs, mirroring how `checkRejected` distinguishes a failed
  * deny.
  */
 export type BlockReason = "not_granted" | "explicit_block";
@@ -65,7 +65,7 @@ export interface DecisionActivityAttributes {
     /** SubjectSet rendered as `<namespace>:<object>#<relation>` when used. */
     subjectSet?: string;
     /**
-     * Set when the check call itself was auth-rejected and enforce mode
+     * Set when the check call itself failed and enforce mode
      * turned that into a deny — the classified {@link OryErrorCode} that
      * caused it. Makes the "denied because the check failed" case
      * distinguishable from a normal Keto deny in the audit trail.
@@ -272,6 +272,30 @@ export interface GateToolCallArgs {
  * semantics; the new `interactive` kind means "do nothing else."
  */
 export declare function gateToolCall(client: OryAgentClient, args: GateToolCallArgs): Promise<ToolGateOutcome>;
+export interface GateMcpToolCallArgs {
+    harness: string;
+    /** The harness-side tool name, kept for activity and denial context. */
+    toolName: string;
+    mcpTool: McpToolIdentifier;
+    /** The user subject checked for `use`, built with `resolveUserSubject`. */
+    subject: Pick<PermissionCheck, "subjectId" | "subjectSet">;
+    activityAttributes?: Record<string, unknown>;
+    modeOverride?: PermissionMode;
+    principals?: PrincipalBlockSubjects;
+}
+/**
+ * Gate one MCP tool call against the Agent Security MCP namespaces.
+ *
+ * The call is checked twice with the native tool model: `McpServer:<server>`
+ * (No access blocks every tool on the server, cataloged or not) and
+ * `McpTool:<server>:<tool>` (Read and Write levels block tool tiers). Each check
+ * covers the user's `use` permit and every machine-principal block, so an MCP
+ * level set on the Project, an Identity, an Agent, or a Sub-Agent applies here.
+ * The server name is normalized to its lowercased form, matching the server
+ * catalog. The most restrictive outcome wins.
+ */
+export declare function gateMcpToolCall(client: OryAgentClient, args: GateMcpToolCallArgs): Promise<PermissionDecision>;
+export declare function mostRestrictiveDecision(decisions: PermissionDecision[]): PermissionDecision;
 /**
  * Gate a shell tool by decomposing its command into the program/builtin words
  * that will run and checking each as `ShellTool:<word>#use`, on top of the
@@ -280,16 +304,16 @@ export declare function gateToolCall(client: OryAgentClient, args: GateToolCallA
  * Aggregation: **any deny → deny** (naming the offending word); else any observe
  * → observe (pass through, per-word `permission.observe_deny` events recorded);
  * else allow. A too-complex / unparseable command is **fail-closed** in enforce
- * (deny + alert) and logged-then-passed in observe. A parser-unavailable or
- * infrastructure error is **fail-open** (top-level decision only) — availability
- * must not hinge on the parser.
+ * (deny + alert) and logged-then-passed in observe. A parser-unavailable
+ * condition falls back to the top-level decision. Network, rate-limit, and
+ * server failures in word checks deny in enforce mode.
  */
 export declare function decomposeAndCheck(client: OryAgentClient, args: GateToolCallArgs): Promise<PermissionDecision>;
 /**
  * Run a permission check and resolve the configured mode against the
  * result. Never throws — infrastructure errors surface as a typed
- * `{ kind: "fail_open" }` decision, and auth-rejected check calls in
- * enforce mode as `{ kind: "deny" }` (see
+ * `{ kind: "fail_open" }` decision in observe mode, and untrusted or unavailable
+ * check calls in enforce mode as `{ kind: "deny" }` (see
  * {@link CHECK_UNTRUSTED_CODES}).
  */
 export declare function checkAndDecide(client: OryAgentClient, check: PermissionCheck, opts?: CheckAndDecideOptions): Promise<PermissionDecision>;