@ory/cursor 1.5.2 → 1.6.0

package/README.md

@@ -104,17 +104,36 @@ Then a denied tool is actually blocked (`preToolUse` returns `permission: "deny"
 | Cursor hook | What the plugin does |
 |---|---|
 | `sessionStart` | User + agent auth gates, user→agent delegation (never blocks) |
-| `preToolUse` | The permission gate — blocks with `permission: "deny"` in enforce mode |
+| `preToolUse` | The permission gate for native tools — blocks with `permission: "deny"` in enforce mode |
+| `beforeMCPExecution` | The permission gate for MCP tools — checks `McpServer` and `McpTool` and blocks with `permission: "deny"` in enforce mode |
 | `postToolUse` / `postToolUseFailure` | Record `tool.complete` / `tool.fail` activity |
 | `beforeSubmitPrompt` | Record `user.prompt` activity (never blocks the human) |
 | `subagentStart` / `subagentStop` | Spawn-scoped child Talos identity + delegation activity |
 
-The fine-grained `beforeShellExecution` / `beforeMCPExecution` / `beforeReadFile`
-hooks are **not** registered: `preToolUse` already gates those categories, so
-registering them would only spawn extra hook subprocesses without adding any
-enforcement. (When they do fire, the handler records activity only.)
+The fine-grained `beforeShellExecution` / `beforeReadFile` hooks are **not**
+registered: `preToolUse` already gates those categories, so registering them
+would only spawn extra hook subprocesses without adding any enforcement. (When
+they do fire, the handler records activity only.)
 
-The `preToolUse` gate is registered fail-closed: if the hook can't produce a verdict, Cursor blocks the tool (exit code 2), so a crashed or timed-out gate can't silently defeat enforce mode. The audit/identity hooks stay fail-open — none of them gate a tool, and session start must never block.
+### MCP servers
+
+`preToolUse` names an MCP tool `MCP:<tool>` without its server, so the plugin
+gates MCP calls in `beforeMCPExecution`, which [Cursor documents](https://cursor.com/docs/hooks)
+with the server's `mcp.json` key (`mcp_server_name`), the server's own
+`tool_name`, and its stdio launch `command` or HTTP/SSE `url`. Each call checks
+`McpServer:<server>` and `McpTool:<server>:<tool>`; Agent Security resolves the
+reported key to a cataloged server, helped by hashed fingerprints of the
+launched package, container image, or URL host (raw commands, arguments, and
+URLs never leave the machine). `preToolUse` still checks `MCP:<tool>` as a
+native tool, as it did before MCP gating, but records no activity, so one call
+is counted once.
+
+Cursor documents that `beforeMCPExecution` does not run in cloud agents, and
+that cloud agents load only project hooks, not `~/.cursor/hooks.json`. With a
+`--project` install, MCP calls a cloud agent makes get only that native
+`MCP:<tool>` check, so per-server MCP levels do not apply to them.
+
+Both gates are registered fail-closed: if the hook can't produce a verdict, Cursor blocks the tool (exit code 2), so a crashed or timed-out gate can't silently defeat enforce mode. The audit/identity hooks stay fail-open — none of them gate a tool, and session start must never block. Re-run `install` after upgrading to register `beforeMCPExecution`.
 
 ## Connect to Ory Agent Security
 
@@ -136,7 +155,7 @@ npx -y -p @ory/cursor ory-cursor configure \
 
 **Ory Network or OEL.** Either works. For an Ory Network project the URL is `https://<slug>.projects.oryapis.com`; for a self-hosted **Ory Enterprise License** deployment, point `--project-url` at that deployment's base URL and use the sign-in client id from its Agent Security configuration. Everything downstream — sign-in, checks, delegation — is identical.
 
-**There is nothing else for you to create.** The sign-in client, permission model, native-tool blocks, MCP grants, and observe/enforce posture are provisioned in the Console by someone with project access. At session start the plugin loads or enrolls Cursor's Talos runtime credential in the OS credential store; tool paths only read it. Installing needs no workspace privilege.
+**There is nothing else for you to create.** The sign-in client, permission model, native-tool blocks, MCP server access, and observe/enforce posture are provisioned in the Console by someone with project access. At session start the plugin loads or enrolls Cursor's Talos runtime credential in the OS credential store; tool paths only read it. Installing needs no workspace privilege.
 
 Sign-in runs at the start of every session and never blocks — a declined, skipped, or timed-out login simply leaves that session without a user identity.
 

package/dist/cli/setup.js

@@ -93,7 +93,7 @@ function writeJson(file, value) {
 /**
  * Resolve this install's runtime and write its shims.
  *
- * Cursor's `preToolUse` gate is registered `failClosed: true` (see
+ * Cursor's `preToolUse` and `beforeMCPExecution` gates are registered `failClosed: true` (see
  * {@link oryHooksBlock}), so a hook that cannot answer blocks every tool. That
  * makes the shim's runtime-missing path load-bearing: it has to emit an
  * explicit allow, not just exit 0.
@@ -110,21 +110,24 @@ function wireCursorRuntime(args) {
 }
 /**
  * Build the Ory hooks block. Only the load-bearing events are registered:
- * `preToolUse` is the permission gate; the rest are audit/identity. The
- * fine-grained shell/MCP/file hooks are intentionally omitted — `preToolUse`
- * already covers those categories, and registering them would spawn a hook
- * subprocess per file read / shell line for no added enforcement.
+ * `preToolUse` is the permission gate for native tools and `beforeMCPExecution`
+ * the gate for MCP tools; the rest are audit/identity. `beforeMCPExecution` is
+ * the only hook that reports an MCP call's server (its `mcp.json` key and launch
+ * command or URL) — `preToolUse` sees just `MCP:<tool>` and defers those calls
+ * to it. The other fine-grained shell/file hooks are intentionally omitted —
+ * `preToolUse` already covers those categories, and registering them would
+ * spawn a hook subprocess per file read / shell line for no added enforcement.
  *
- * The `preToolUse` gate is registered `failClosed: true`. Cursor's hook default
- * is fail-open: a crashed / timed-out / malformed-JSON hook lets the tool
- * through. For the one hook that makes the permission decision that would
- * silently defeat `enforce` mode (the whole point of the gate), so we opt it
- * into fail-closed — if the gate can't produce a verdict, Cursor blocks the
- * tool. The gate still fails *open* on the paths Ory treats as non-blocking
- * (network / rate-limit), because those are handled inside the hook, which
- * exits 0 with an allow verdict; `failClosed` only governs the hook process
- * itself failing to answer. The audit/identity hooks stay fail-open — none of
- * them gate a tool, and session start must never block.
+ * Both gates are registered `failClosed: true`. Cursor's hook default is
+ * fail-open: a crashed / timed-out / malformed-JSON hook lets the tool through.
+ * For a hook that makes the permission decision that would silently defeat
+ * `enforce` mode (the whole point of the gate), so we opt it into fail-closed —
+ * if the gate can't produce a verdict, Cursor blocks the tool. The gate still
+ * fails *open* on the paths Ory treats as non-blocking (network / rate-limit),
+ * because those are handled inside the hook, which exits 0 with an allow
+ * verdict; `failClosed` only governs the hook process itself failing to answer.
+ * The audit/identity hooks stay fail-open — none of them gate a tool, and
+ * session start must never block.
  */
 function oryHooksBlock(command) {
     const entry = (timeout, failClosed = false) => [
@@ -134,6 +137,7 @@ function oryHooksBlock(command) {
         sessionStart: entry(SESSION_START_TIMEOUT_SEC),
         sessionEnd: entry(TOOL_HOOK_TIMEOUT_SEC),
         preToolUse: entry(TOOL_HOOK_TIMEOUT_SEC, true),
+        beforeMCPExecution: entry(TOOL_HOOK_TIMEOUT_SEC, true),
         postToolUse: entry(TOOL_HOOK_TIMEOUT_SEC),
         postToolUseFailure: entry(TOOL_HOOK_TIMEOUT_SEC),
         beforeSubmitPrompt: entry(TOOL_HOOK_TIMEOUT_SEC),

package/dist/handlers.js

@@ -52,16 +52,19 @@ async function handleHookEvent(input, client, deps = {}) {
                 return await handleAudit(input, client, "compaction", {
                     trigger: input.trigger,
                 });
-            // Fine-grained shell / MCP / file hooks surface activity to the user and
-            // are activity-only — `preToolUse` already ran the permission gate for the
-            // corresponding tool category, so gating here would double-count.
+            // MCP calls are gated here, not in `preToolUse`: only this hook carries
+            // the server's `mcp.json` key and how the server is launched or reached.
+            case "beforeMCPExecution":
+                return await handleBeforeMcpExecution(input, client);
+            // The remaining fine-grained hooks are activity-only — `preToolUse`
+            // already ran the permission gate for the corresponding tool category,
+            // so gating here would double-count.
             case "beforeShellExecution":
             case "afterShellExecution":
                 return await handleAudit(input, client, "user.interaction", {
                     kind: event,
                     hasCommand: input.command !== undefined,
                 });
-            case "beforeMCPExecution":
             case "afterMCPExecution":
                 return await handleAudit(input, client, "user.interaction", {
                     kind: event,
@@ -106,10 +109,34 @@ async function handlePreToolUse(input, client) {
         toolName,
         toolInput: input.tool_input,
     });
+    // `preToolUse` names an MCP tool `MCP:<tool>` with no server. Locally the
+    // install's `beforeMCPExecution` fires for the same call with the server's
+    // `mcp.json` key and owns the MCP decision and its activity. Cloud agents do
+    // not run `beforeMCPExecution`, so the native check still applies here, as
+    // it did before MCP gating existed, but without recording the call twice.
+    if (isMcpPreToolUse(toolName)) {
+        const session = sessionKey(input);
+        const result = await (0, argus_1.decideTool)(client, {
+            harness: HARNESS,
+            toolName,
+            toolArgs: input.tool_input,
+            subjectFallback: session ? `session:${session}` : undefined,
+            principals: subAgentPrincipals(input),
+        });
+        if (result.blocked) {
+            const reason = result.denialMessage;
+            return { permission: "deny", agent_message: reason, user_message: reason };
+        }
+        return {};
+    }
     // Only offer a `session:` fallback subject when Cursor actually sent a
     // session — interpolating an absent one yields the literal
     // `session:undefined`, a subject that matches nothing yet looks like a real
     // one in the audit trail.
+    return gateCursorTool(input, client, toolName, input.tool_input);
+}
+/** The acting sub-agent's principals, when Cursor identifies one. */
+function subAgentPrincipals(input) {
     const session = sessionKey(input);
     const subAgentType = input.subagent_type;
     const subAgent = subAgentType
@@ -117,19 +144,20 @@ async function handlePreToolUse(input, client) {
             ? (0, argus_1.loadSubAgentDynamicCredentials)(HARNESS, session, subAgentType)
             : (0, argus_1.loadSubAgentDynamicCredentials)(HARNESS, subAgentType)
         : undefined;
+    return subAgent
+        ? { subAgentClientId: subAgent.clientId, subAgentType, perSpawnId: input.subagent_id, sessionId: session }
+        : undefined;
+}
+/** Gate one tool call, as the acting sub-agent when Cursor identifies it. */
+async function gateCursorTool(input, client, toolName, toolArgs, mcpTool) {
+    const session = sessionKey(input);
     const result = await (0, argus_1.gate)(client, {
         harness: HARNESS,
         toolName,
-        toolArgs: input.tool_input,
+        toolArgs,
         subjectFallback: session ? `session:${session}` : undefined,
-        principals: subAgent
-            ? {
-                subAgentClientId: subAgent.clientId,
-                subAgentType,
-                perSpawnId: input.subagent_id,
-                sessionId: session,
-            }
-            : undefined,
+        ...(mcpTool ? { mcpTool } : {}),
+        principals: subAgentPrincipals(input),
     });
     if (result.blocked) {
         const reason = result.denialMessage;
@@ -137,6 +165,50 @@ async function handlePreToolUse(input, client) {
     }
     return {};
 }
+// ─── beforeMCPExecution — the MCP permission gate ───────────────────
+/** Cursor's `preToolUse` / `postToolUse` name for an MCP tool: `MCP:<tool>`. */
+const MCP_TOOL_PREFIX = "MCP:";
+function isMcpPreToolUse(toolName) {
+    return toolName.startsWith(MCP_TOOL_PREFIX);
+}
+/**
+ * Gate an MCP call with the server Cursor reports: `mcp_server_name` is the
+ * server's `mcp.json` key and `tool_name` the server's own tool name. The
+ * launch command (stdio) or URL (HTTP/SSE) becomes hashed fingerprints, so a
+ * cataloged server is recognized whatever the user named it locally.
+ */
+async function handleBeforeMcpExecution(input, client) {
+    const serverName = input.mcp_server_name?.trim() ?? "";
+    const mcpToolName = input.tool_name ?? "";
+    client.logger.info("lifecycle.before_mcp_execution", {
+        sessionId: sessionKey(input),
+        mcpServer: serverName,
+        mcpTool: mcpToolName,
+    });
+    const fingerprints = (0, argus_1.mcpServerFingerprints)({
+        url: input.url ?? input.mcp_server_url,
+        command: input.command,
+    });
+    // A missing server key still reaches Agent Security, which treats an
+    // unrecognized server as uncatalogued rather than letting it pass unchecked.
+    const mcpTool = {
+        serverName: serverName || "unknown",
+        toolName: mcpToolName,
+        ...(fingerprints.length > 0 ? { fingerprints } : {}),
+    };
+    return gateCursorTool(input, client, `${MCP_TOOL_PREFIX}${mcpToolName || "unknown"}`, parseToolInput(input.tool_input), mcpTool);
+}
+/** `beforeMCPExecution` sends the arguments as a JSON string. */
+function parseToolInput(toolInput) {
+    if (typeof toolInput !== "string")
+        return toolInput;
+    try {
+        return JSON.parse(toolInput);
+    }
+    catch {
+        return undefined;
+    }
+}
 // ─── postToolUse ────────────────────────────────────────────────────
 async function handlePostToolUse(input, client) {
     const toolName = input.tool_name ?? "unknown";

package/dist/types.d.ts

@@ -30,7 +30,11 @@ export interface CursorHookInput {
     reason?: string;
     duration_ms?: number;
     tool_name?: string;
-    tool_input?: Record<string, unknown>;
+    /**
+     * The tool arguments. An object on `preToolUse`; a JSON-encoded string on
+     * `beforeMCPExecution`.
+     */
+    tool_input?: Record<string, unknown> | string;
     /** postToolUse — JSON-stringified tool output. */
     tool_output?: string;
     tool_use_id?: string;
@@ -41,8 +45,12 @@ export interface CursorHookInput {
     command?: string;
     sandbox?: boolean;
     output?: string;
-    /** MCP url (remote) — present for MCP hooks. */
+    /** The server's key in `mcp.json` (for example `linear`). */
+    mcp_server_name?: string;
+    /** Remote server URL — present only for HTTP/SSE servers. */
     url?: string;
+    /** Same as `url`; present only for HTTP/SSE servers. */
+    mcp_server_url?: string;
     file_path?: string;
     edits?: Array<{
         old_string?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/cursor",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Ory plugin for Cursor: scaffolding rules, a local Ory instance, and authentication, authorization, and audit for every tool call",
   "license": "Apache-2.0",
   "homepage": "https://github.com/ory/ory-agent-plugins/tree/main/packages/cursor",
@@ -57,10 +57,10 @@
   ],
   "dependencies": {
     "reova": "^0.7.0",
-    "@ory/argus": "1.5.2"
+    "@ory/argus": "1.6.0"
   },
   "devDependencies": {
-    "typescript": "^6.0.2"
+    "typescript": "^7.0.2"
   },
   "engines": {
     "node": ">=22"