Launch offer: use code LAUNCH20 for 20% off any single pack. See the packs

Cursor MCP Allow-List Hook: beforeMCPExecution with failClosed (Tested)

Published 2026-11-16 · 6 min read · by AgentKit Co

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

  1. 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": true on the hook definition and those failures block instead. Cursor's docs recommend this for security-critical beforeMCPExecution hooks.
  2. beforeMCPExecution doesn't run in cloud agents. Cursor lists it (with afterMCPExecution) under hooks not available in cloud agents. preToolUse does run there, and for MCP tools it fires with tool_name set to MCP:<tool_name>.
  3. preToolUse doesn't enforce "ask". The schema accepts it, but the docs say it isn't enforced for preToolUse today. 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 your mcp.json. Anything else is denied, including a server someone adds to the repo later. Matching is case-sensitive, so GitHub is not github.
  • deny_tools: regexes for tools that should never run from the agent.
  • ask_tools: regexes for tools that change data. With the default hooks.json you 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 on preToolUse, where Cursor gives no server name.
  • An optional secret_pattern regex: arguments that look like an API key or private key trigger "ask" (or "deny" on preToolUse).

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 preToolUse path has no server name, so two servers that both expose get_issue look the same there. Keep allow_tools_without_server short and read-only.
  • Because the guard fails closed, a typo in mcp-policy.json blocks every MCP call until you fix it. Run jq . .cursor/hooks/mcp-policy.json after editing.
  • Project hooks in .cursor/hooks.json only load in trusted workspaces. User hooks in ~/.cursor/hooks.json are 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.

Keep reading

Agent Skills (SKILL.md) Explained: Formats, Folders and SafetyWhat an Agent Skill is, how SKILL.md works, which folders Claude Code, Codex, Cursor and Copilot read, and how to write and vet one. Checked on 2026-10-17.4 min readAGENTS.md Examples: 7 Copy-Paste Files for Real Projects (2026)Seven AGENTS.md examples to copy: Next.js, Python API, Go, a monorepo with nested files, a global ~/.codex file, an override and review rules.7 min readWhat Is an AI Agent? Plain-English Guide for BeginnersWhat an AI agent is, how it differs from a chatbot or automation, and the four building blocks every agent has. No jargon.4 min read