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:
beforeSubmitPrompt- Validates chat prompts before sending to AIafterAgentResponse- Validates AI responses before displayingbeforeMCPExecution- Validates MCP tool requests before executionafterMCPExecution- Validates MCP tool responses
File Structure
Key Files:
Wrapper scripts (
.sh): Set environment variables, invoke Python scripts⚠️ Contains
AKTO_DATA_INGESTION_URLplaceholder - Must be replaced with your Akto instance URL
Python scripts (
.py): Core validation logic and Akto API communicationakto_ingestion_utility.py: Shared validation/ingestion logic imported by the hook scripts — lives in a different GitHub directory (shared/, notcursor-hooks/), so it needs its own download stepakto_machine_id.py: Generates unique device identifiers for Atlas modehooks.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
Create Directories
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'.
Configure Akto Ingestion URL and API Token ⚠️ CRITICAL STEP
All wrapper scripts contain the placeholders {{AKTO_DATA_INGESTION_URL}}, {{AKTO_API_TOKEN}} and {{DEVICE_ID (optional)}} that must be replaced — the URL with your actual Akto instance URL, and the token with your Akto API token (obtain it from Akto Atlas → Connectors → Setup Guardrail card). If your deployment does not require auth, set the token to an empty string so the placeholder is removed (an unsubstituted {{AKTO_API_TOKEN}} would be sent as an invalid Authorization header).
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.shakto-validate-chat-response-wrapper.shakto-validate-mcp-request-wrapper.shakto-validate-mcp-response-wrapper.sh
Configure Hooks
Create Cursor hooks configuration:
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
Restart Cursor
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
Support: support@akto.io
Community: https://www.akto.io/community
Last updated