For the complete documentation index, see llms.txt. This page is also available as Markdown.

Cursor Hooks

Akto Guardrails for Cursor provides comprehensive security monitoring and validation for both chat interactions and MCP tool executions. It intercepts all agent operations, validates against security policies, blocks risky behavior, and reports events to your Akto dashboard.

Key Features

  • Zero Installation - No standalone apps or packages to install

  • Comprehensive Coverage - Monitors both chat prompts/responses and MCP requests/responses

  • Transparent Integration - Uses Cursor's native hook mechanism

  • Real-time Protection - Intercepts every interaction before execution

  • Centralized Monitoring - All events reported to Akto dashboard

  • Flexible Deployment - Supports both Argus and Atlas modes

How It Works

Cursor's hook system executes custom scripts at four critical points:

4 Hook Points:

  1. beforeSubmitPrompt - Validates chat prompts before sending to AI

  2. afterAgentResponse - Validates AI responses before displaying

  3. beforeMCPExecution - Validates MCP tool requests before execution

  4. afterMCPExecution - Validates MCP tool responses

File Structure

Key Files:

  • Wrapper scripts (.sh): Set environment variables, invoke Python scripts

    • ⚠️ Contains AKTO_DATA_INGESTION_URL placeholder - Must be replaced with your Akto instance URL

  • Python scripts (.py): Core validation logic and Akto API communication

  • akto_ingestion_utility.py: Shared validation/ingestion logic imported by the hook scripts — lives in a different GitHub directory (shared/, not cursor-hooks/), so it needs its own download step

  • akto_machine_id.py: Generates unique device identifiers for Atlas mode

  • hooks.json: Links hooks to wrapper scripts

Setup Guide

Prerequisites

  • Cursor IDE (version 0.40+ with hooks support)

  • Akto instance URL

  • macOS, Linux, or Windows with bash/zsh

Installation Steps

1

Create Directories

2

Download Hook Scripts

akto_ingestion_utility.py must land in the same directory as the hook scripts — they import it as a plain top-level module, resolved from the script's own directory. Skipping this download makes the hooks fail with ModuleNotFoundError: No module named 'akto_ingestion_utility'.

3

Configure Akto Ingestion URL and API Token ⚠️ CRITICAL STEP

DEVICE_ID becomes the first label of the reported hostname (<DEVICE_ID>.ai-agent.cursor), and the dashboard displays that label verbatim as the device name. Substitute a real device label rather than deleting the line — with DEVICE_ID empty the hooks fall back to the lowercased computer name, which won't match how the same machine is named by the enterprise installer.

Automated replacement:

Manual replacement (alternative):

Edit each wrapper script and replace:

With:

Files to update:

  • akto-validate-chat-prompt-wrapper.sh

  • akto-validate-chat-response-wrapper.sh

  • akto-validate-mcp-request-wrapper.sh

  • akto-validate-mcp-response-wrapper.sh

4

Configure Hooks

Create Cursor hooks configuration:

5

Configure Hook Behavior (Optional)

Edit wrapper scripts to customize:

Mode Options:

  • Argus: Standard validation and reporting

  • Atlas: Includes device-specific metadata

Sync Mode:

  • true: Blocks threats

  • false: Reports but allows execution

6

Restart Cursor

7

Verify Installation

Check logs to confirm hooks are working:

Test by typing a message in Cursor's chat or using an MCP tool. You should see log entries indicating validation occurred.

Configuration Reference

Wrapper Script Variables

Environment Variables (Optional)

Override defaults via environment variables:

Troubleshooting

ModuleNotFoundError: No module named 'akto_ingestion_utility'

The shared ingestion utility was not downloaded, or landed outside ~/.cursor/hooks/akto/. It lives in the shared/ directory on GitHub, not under HOOKS_BASE, so it needs its own curl.

If the file is present and the import still fails, check that PYTHONSAFEPATH is unset — it suppresses the script-directory entry on sys.path that this import relies on.

Hooks Not Executing

Ingestion URL Not Configured

Device Shows Up With the Wrong Name

The device name in the dashboard is the first label of the reported hostname, which is whatever DEVICE_ID the wrapper exports. Check what is actually set:

An unsubstituted {{DEVICE_ID (optional)}} is reported verbatim; an empty or missing value falls back to the lowercased computer name (or the raw machine UUID where that cannot be resolved). Substitute a real label:

Check Logs for Errors

Events Not in Dashboard

Uninstallation

To completely remove Akto hooks from Cursor:

Complete Removal

Selective Removal (Keep Logs)

If you want to preserve logs for audit purposes:

Backup Before Removal

Verify Removal

Restore Cursor to Default

After uninstallation, Cursor will operate without Akto security monitoring. No restart or additional configuration is needed beyond removing the files.

Enterprise Deployment

Automated Deployment Script

Deploy to developers:

Quick Setup Summary

Resources

Last updated