Cursor MCP Allow-List Hook: beforeMCPExecution with failClosed (Tested)
Adding an MCP server to Cursor gives the agent every tool that server exposes. A hook lets you say which servers may run at all, which tools need your OK, and what happens when the guard itself breaks. This page gives one tested script that does all three, plus the spec details that make most MCP guards quietly do nothing.
Everything here was checked against Cursor's hooks documentation on 2026-11-16. The script was tested by piping 27 sample payloads through it (the test file is in the download). We have not run it on Windows or inside a live Cursor session, and Cursor changes quickly, so re-check the docs for anything you rely on.
Download free-cursor-mcp-guard.zip (MIT, bash + jq, 1 script, policy file, two hooks.json variants, test.sh)
Three facts that break most MCP guards
- Hooks fail open by default. If your script crashes, times out or exits with any code other than 0 or 2, Cursor logs it and lets the MCP call through. Set
"failClosed": trueon the hook definition and those failures block instead. Cursor's docs recommend this for security-criticalbeforeMCPExecutionhooks. beforeMCPExecutiondoesn't run in cloud agents. Cursor lists it (withafterMCPExecution) under hooks not available in cloud agents.preToolUsedoes run there, and for MCP tools it fires withtool_nameset toMCP:<tool_name>.preToolUsedoesn't enforce "ask". The schema accepts it, but the docs say it isn't enforced forpreToolUsetoday. A guard that answers "ask" there is not pausing anything, so treat "ask" as "deny" on that path.
A fourth one bites people with project hooks: in .cursor/hooks.json the command path is relative to the project root, so write .cursor/hooks/guard-mcp.sh, not ./hooks/guard-mcp.sh.
What Cursor sends the hook
beforeMCPExecution gets the tool, its arguments as a JSON string, and the server's key from mcp.json, plus either the URL (HTTP/SSE servers) or the launch command (stdio servers):
{
"tool_name": "create_issue",
"tool_input": "{\"title\":\"Fix login\"}",
"mcp_server_name": "github",
"url": "https://example.com/mcp",
"mcp_server_url": "https://example.com/mcp"
}
It answers allow, deny or ask. Match on mcp_server_name, not on command: the docs point out that the launch string differs between installs (relative paths, plugin roots) and HTTP servers have no command at all.
On the preToolUse path, tool_input is an object and there is no server name in the documented input, which is why the guard below uses a separate tool allow-list there.
The hooks.json (editor)
For the editor agent, one hook is enough:
{
"version": 1,
"hooks": {
"beforeMCPExecution": [
{ "command": ".cursor/hooks/guard-mcp.sh", "timeout": 10, "failClosed": true }
]
}
}
Strict mode for cloud agents
If the repo is also worked on by cloud agents, beforeMCPExecution won't run there, so the download includes hooks.strict-cloud.json, which adds the same script on preToolUse:
"preToolUse": [
{ "command": ".cursor/hooks/guard-mcp.sh", "timeout": 10, "failClosed": true, "matcher": "^MCP:" }
]
The matcher is a regex tested against the tool type, so ^MCP: runs the guard only for MCP tools and leaves Shell, Read and Write alone. The trade-off: preToolUse fires in the editor too, and Cursor merges hook answers so any deny wins over ask. With strict mode on, write tools are denied everywhere instead of asked, and only the read-only tools you list pass. That is the price of covering cloud agents with a hook that can't see the server name.
The policy file
All the rules live in .cursor/hooks/mcp-policy.json. Edit it to match your own servers (these names are examples):
{
"allow_servers": ["github", "context7"],
"deny_tools": ["^delete_repository$", "^(drop|truncate)_", "^execute_sql$"],
"ask_tools": ["^(create|update|delete|remove|merge|push|send|post|publish|write|upload|move|rename|close|comment|add)_"],
"allow_tools_without_server": ["get_issue", "search_issues", "get_file_contents"]
}
allow_servers: exact keys from yourmcp.json. Anything else is denied, including a server someone adds to the repo later. Matching is case-sensitive, soGitHubis notgithub.deny_tools: regexes for tools that should never run from the agent.ask_tools: regexes for tools that change data. With the defaulthooks.jsonyou get a prompt; in strict mode they are denied.allow_tools_without_server: strict mode only. The read-only tools you're happy to let through onpreToolUse, where Cursor gives no server name.- An optional
secret_patternregex: arguments that look like an API key or private key trigger "ask" (or "deny" onpreToolUse).
The guard, shortened
The full script in the download adds the secret check and messages for the agent. The core logic:
#!/usr/bin/env bash
here=$(cd "$(dirname "$0")" && pwd); policy="$here/mcp-policy.json"
deny() { printf '{"permission":"deny","user_message":"guard-mcp: %s"}\n' "$1"; exit 0; }
command -v jq >/dev/null || deny "jq is not installed"
input=$(cat)
printf '%s' "$input" | jq -e 'type=="object"' >/dev/null 2>&1 || deny "unreadable hook input"
jq -e 'type=="object"' "$policy" >/dev/null 2>&1 || deny "missing or broken policy file"
tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
server=$(printf '%s' "$input" | jq -r '.mcp_server_name // empty')
inlist() { jq -e --arg v "$2" "($1 // []) | index(\$v) != null" "$policy" >/dev/null; }
matches() { jq -e --arg v "$2" "($1 // []) | any(. as \$re | \$v | test(\$re; \"i\"))" "$policy" >/dev/null; }
if [ -n "$server" ]; then # beforeMCPExecution
ask=ask
inlist .allow_servers "$server" || deny "server '$server' is not allow-listed"
else # preToolUse, tool_name "MCP:<tool>"
case "$tool" in MCP:*) ;; *) echo '{"permission":"allow"}'; exit 0 ;; esac
tool=${tool#MCP:}; ask=deny # "ask" isn't enforced here
inlist .allow_tools_without_server "$tool" || deny "tool '$tool' is not allow-listed"
fi
matches .deny_tools "$tool" && deny "tool '$tool' is blocked"
matches .ask_tools "$tool" && { printf '{"permission":"%s","user_message":"guard-mcp: %s changes data"}\n' "$ask" "$tool"; exit 0; }
echo '{"permission":"allow"}'
Note how every failure path prints a deny and exits 0. That matters twice: a permission hook that prints invalid JSON blocks anyway, and failClosed covers the crash and timeout cases the script can't catch itself.
Test it without opening Cursor
echo '{"tool_name":"read_file","tool_input":"{}","mcp_server_name":"random-server"}' | .cursor/hooks/guard-mcp.sh
# {"permission":"deny","user_message":"guard-mcp: MCP server 'random-server' is not on the allow-list ..."}
echo '{"tool_name":"create_issue","tool_input":"{}","mcp_server_name":"github"}' | .cursor/hooks/guard-mcp.sh
# {"permission":"ask", ...}
echo '{"tool_name":"MCP:create_issue","tool_input":{}}' | .cursor/hooks/guard-mcp.sh
# {"permission":"deny", ...} (strict-mode path: not a listed read-only tool)
The download's test.sh runs 27 cases, including a missing policy file, a broken policy file, garbage input and no jq on the PATH, and prints 27 passed, 0 failed.
Honest limits
- A hook is a safety net, not a sandbox. Tool-name patterns can't see what a tool really does; an allowed server can still cause damage through a tool whose name looks harmless. Keep Cursor's own approval prompts on for MCP tools that matter.
- The
preToolUsepath has no server name, so two servers that both exposeget_issuelook the same there. Keepallow_tools_without_servershort and read-only. - Because the guard fails closed, a typo in
mcp-policy.jsonblocks every MCP call until you fix it. Runjq . .cursor/hooks/mcp-policy.jsonafter editing. - Project hooks in
.cursor/hooks.jsononly load in trusted workspaces. User hooks in~/.cursor/hooks.jsonare not available in cloud agents.
Related
The free Cursor hooks examples cover the other permission hooks: risky shell commands, .env reads and prompts that contain API keys. Choosing which servers to allow in the first place? The Claude Code .mcp.json examples walk through scopes and secrets, and the Claude Code hooks examples show the same guard idea for Claude Code. For rules and context files across Cursor, Claude Code and Codex, see the AGENTS.md vs CLAUDE.md vs Cursor rules guide.
AI Coding Agent Config Kit
Instruction-file templates for 12 stacks and 12 prompts that write and audit them. 34-page PDF, $14.
Not ready to buy? Start with the free PDF.
Get 10 of our most-used prompts as a free PDF from Gumroad. You will be asked for your email so Gumroad can deliver it.