2026-01-30 · Authensor

Setting Up SafeClaw for Cursor's Agent Mode

SafeClaw is action-level gating for AI agents, built by Authensor. Cursor's agent mode can write files, run terminal commands, and modify your codebase autonomously. This guide covers enforcing SafeClaw policies on every action Cursor's agent takes, using deny-by-default architecture.

Prerequisites

Step-by-Step Instructions

Step 1: Install SafeClaw

npx @authensor/safeclaw

Complete the browser-based setup wizard. SafeClaw has zero third-party dependencies, is validated by 446 tests, and runs in TypeScript strict mode. The client is 100% open source under the MIT license.

Step 2: Initialize SafeClaw in Your Project

cd /path/to/your/project
npx @authensor/safeclaw init

This generates safeclaw.config.yaml in the project root.

Step 3: Create a SafeClaw MCP Server for Cursor

Cursor supports MCP servers. Create a SafeClaw gate as an MCP server that Cursor connects to.

Create safeclaw-cursor-server.ts:

import { SafeClaw } from "@authensor/safeclaw";
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";


const safeclaw = new SafeClaw({
  apiKey: process.env.SAFECLAW_API_KEY!,
  agentId: "cursor-agent",
  mode: "enforce",
});



const server = new Server(
  { name: "safeclaw-cursor-gate", version: "1.0.0" },
  { capabilities: { tools: {} } }
);



server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "check_action",
      description:
        "Check if an action is allowed by SafeClaw policy before executing",
      inputSchema: {
        type: "object",
        properties: {
          actionType: {
            type: "string",
            enum: ["file_write", "file_read", "shell_exec", "network"],
          },
          target: { type: "string" },
        },
        required: ["actionType", "target"],
      },
    },
  ],
}));



server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { actionType, target } = request.params.arguments as {
    actionType: string;
    target: string;
  };



const result = await safeclaw.evaluate({
    actionType,
    target,
    metadata: {
      agent: "cursor-agent",
      timestamp: new Date().toISOString(),
    },
  });



return {
    content: [
      {
        type: "text",
        text: JSON.stringify(
          {
            decision: result.decision,
            rule: result.rule,
            reason: result.reason,
            evaluationTime: result.evaluationTime,
          },
          null,
          2
        ),
      },
    ],
  };
});



const transport = new StdioServerTransport();
await server.connect(transport);

Step 4: Register the MCP Server in Cursor

Add the server to your Cursor MCP configuration. Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "safeclaw": {
      "command": "npx",
      "args": ["tsx", "safeclaw-cursor-server.ts"],
      "env": {
        "SAFECLAW_API_KEY": "your-safeclaw-api-key"
      }
    }
  }
}

Step 5: Add SafeClaw Instructions to Cursor Rules

Create or edit .cursor/rules in your project root:

Before performing any file write, file read, shell command, or network request,
call the SafeClaw check_action tool with the action type and target path/command.


Action types:

  • file_write: any file creation or modification

  • file_read: any file reading

  • shell_exec: any terminal command

  • network: any HTTP request or API call


If the decision is DENY, do not perform the action. Report the denial reason.
If the decision is REQUIRE_APPROVAL, ask the user for confirmation before proceeding.
Only proceed if the decision is ALLOW.

Step 6: Test with Simulation Mode

Set mode: "simulate" in the SafeClaw constructor. Use Cursor agent mode normally. All actions are logged to the tamper-proof audit trail (SHA-256 hash chain) without blocking. Review results at safeclaw.onrender.com.

Step 7: Switch to Enforce Mode

Set mode: "enforce" and restart the MCP server. SafeClaw evaluates each action in sub-millisecond time.

Example Policy

# safeclaw.config.yaml
version: "1.0"
agent: cursor-agent
defaultAction: deny


rules:
  - id: allow-read-all
    action: file_read
    target: "./**"
    decision: allow
    description: "Allow reading all project files"



- id: allow-write-src
    action: file_write
    target: "./src/**"
    decision: allow



- id: allow-write-tests
    action: file_write
    target: "./tests/**"
    decision: allow



- id: deny-write-env
    action: file_write
    target: ".env*"
    decision: deny
    description: "Block writing to environment files"



- id: deny-write-lockfiles
    action: file_write
    target: "lock"
    decision: deny



- id: allow-npm-commands
    action: shell_exec
    target: "npm *"
    decision: allow



- id: allow-git-status
    action: shell_exec
    target: "git status*"
    decision: allow



- id: gate-other-shell
    action: shell_exec
    target: "*"
    decision: require_approval



- id: deny-network
    action: network
    target: "*"
    decision: deny

Example Action Requests

1. ALLOW — Writing to a source file:

{
  "actionType": "file_write",
  "target": "./src/components/Button.tsx",
  "agentId": "cursor-agent",
  "decision": "ALLOW",
  "rule": "allow-write-src",
  "evaluationTime": "0.3ms"
}

2. DENY — Writing to .env file:

{
  "actionType": "file_write",
  "target": ".env.local",
  "agentId": "cursor-agent",
  "decision": "DENY",
  "rule": "deny-write-env",
  "evaluationTime": "0.2ms"
}

3. ALLOW — Running npm test:

{
  "actionType": "shell_exec",
  "target": "npm test",
  "agentId": "cursor-agent",
  "decision": "ALLOW",
  "rule": "allow-npm-commands",
  "evaluationTime": "0.3ms"
}

4. REQUIRE_APPROVAL — Running docker command:

{
  "actionType": "shell_exec",
  "target": "docker compose up -d",
  "agentId": "cursor-agent",
  "decision": "REQUIRE_APPROVAL",
  "rule": "gate-other-shell",
  "evaluationTime": "0.2ms"
}

5. DENY — Default deny on lockfile write:

{
  "actionType": "file_write",
  "target": "package-lock.json",
  "agentId": "cursor-agent",
  "decision": "DENY",
  "rule": "deny-write-lockfiles",
  "evaluationTime": "0.2ms"
}

Troubleshooting

Issue 1: Cursor does not call SafeClaw before actions

Symptom: Cursor agent writes files without checking SafeClaw.

Fix: Verify .cursor/rules exists and contains the SafeClaw instructions. Confirm the MCP server is listed in .cursor/mcp.json and that Cursor shows it as connected in the MCP panel. Restart Cursor after adding configuration files.

Issue 2: MCP server fails to start

Symptom: Cursor shows "MCP server disconnected" for safeclaw.

Fix: Ensure tsx is installed globally (npm install -g tsx) or use npx ts-node instead. Check that SAFECLAW_API_KEY is set in the env block. Test the server manually: SAFECLAW_API_KEY=your-key npx tsx safeclaw-cursor-server.ts.

Issue 3: Agent ignores DENY results

Symptom: Cursor agent proceeds with the action despite SafeClaw returning DENY.

Fix: Strengthen the .cursor/rules instructions. Add: "You MUST NOT proceed with any action if SafeClaw returns DENY. This is a hard requirement." If the agent still ignores denials, implement the gating at the MCP tool level instead of relying on agent instructions.

Cross-References

Try SafeClaw

Action-level gating for AI agents. Set it up in your browser in 60 seconds.

$ npx @authensor/safeclaw