# Cursor setup
Source: https://pushary.com/docs/agents/guides/cursor
Last updated: 2026-10-18
> Set up enforced Cursor approvals on your phone. The Pushary plugin stops shell commands, MCP calls and file edits in Cursor until your policy allows them.
Pushary adds enforced Cursor approvals. Its plugin registers Cursor hooks (small programs Cursor runs before an action) that hold a shell command, an MCP call, or a Write, Delete or Edit tool call until your Pushary policy allows it, and send the risky ones to your phone. The agent does not choose whether to ask. Plain MCP, without the plugin, only gives the agent tools it may never call.
## Set it up [#set-it-up]
```bash
npx pushary@latest setup
```
On Windows PowerShell, run `npx.cmd pushary@latest setup`. The CLI needs Node.js 20.17+, 22.13+ or 23.5+.
### Scan the QR code with your phone [#scan-the-qr-code-with-your-phone]
Setup shows a QR code first. Scan it with your phone's camera or the Pushary app. Sign in or create an account, check that the code on your phone matches the one in your terminal, then tap **Approve** on **Connect this computer?** and allow notifications.
New accounts start a 3-day free trial, then pay $9.99 a month. A card is needed to start the trial. If this computer already has a Pushary key, setup reuses it and skips this step.
### Pick Cursor [#pick-cursor]
Setup asks **Which agents do you use?** with the agents it found already selected. Keep Cursor selected. To skip the question, run `npx pushary@latest setup --agents cursor`.
### Answer the test question [#answer-the-test-question]
Setup sends a test push, then a test question. Answer it on your phone. The terminal says **You're set** once your answer arrives.
### Fully quit and reopen Cursor [#fully-quit-and-reopen-cursor]
Cursor loads hooks when it starts. A **Developer: Reload Window** is not always enough.
On a Mac you can use [Pushary Isle](/docs/agents/mac-app) instead. Connecting your agents there registers the gate in `~/.cursor/hooks.json`, links your key in `~/.cursor/mcp.json`, and writes the always-on rule that tells Cursor to ask through Pushary. The CLI is still what installs the full plugin, including the skill.
## What setup changes on your computer [#what-setup-changes-on-your-computer]
| File | What changes |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `~/.cursor/plugins/local/pushary/` | The Pushary plugin: the MCP tools (`mcp.json`, with your key), the always-on rule (`rules/pushary.mdc`) and the skill. |
| `~/.cursor/hooks.json` | The approval gate for `beforeShellExecution`, `beforeMCPExecution` and `preToolUse` (`Write`, `Delete`, `Edit`), plus activity hooks for prompts, tool results, subagents and sessions. Every entry runs `pushary-gate.mjs` from the plugin. |
| `~/.pushary/config.json` and your shell profile | Your API key, as `PUSHARY_API_KEY`. |
The user-level `~/.cursor/hooks.json` is the reliable place for the gate. Setup also strips the gate from the plugin's own copy, because some Cursor versions run a local plugin's bundled hooks too, which would fire each approval twice.
## Check that it works [#check-that-it-works]
```bash
npx pushary@latest doctor
```
Doctor checks your key and plan, that the gate is registered in `~/.cursor/hooks.json`, that its script path resolves, and that the MCP server has your key. It sends a real test push. Add `--roundtrip` to send a test question too.
Then try a real approval. A new workspace starts on **Always**, so it reaches your phone while you sit at your computer. If yours is on When away, decisions stay in Cursor while you are there. To test from your desk, open the Pushary app, tap **Questions & approvals** at the top of your inbox, and pick **Always**.
Ask Cursor's agent to run `touch pushary-test.txt`. Your phone buzzes. Tap **Approve** and the command runs. Switch back to **When away** when you are done.
## What Pushary can and cannot enforce on Cursor [#what-pushary-can-and-cannot-enforce-on-cursor]
* **Gated before they run:** shell commands, MCP calls, and `Write`, `Delete` and `Edit` tool calls. Your approval rules decide which of them need your answer. Ordinary safe actions can proceed.
* **Not gated:** file reads. Cursor's read hook can only answer allow or deny, so a gate there would have to allow every read while Pushary is down.
* **Wait time:** the gate waits up to 45 seconds for your phone, inside Cursor's 60-second hook limit.
* **When Pushary hands a call back:** shell commands and MCP calls go to Cursor's own prompt. File edits have no Cursor prompt, so they are refused instead.
* **When Pushary is unavailable:** the same rule applies. A missing key, a missing gate script or no Node sends shell and MCP calls to Cursor's prompt and refuses file edits. On Windows, a missing gate script or no Node makes the hook itself fail, and Cursor blocks the call. A required approval is never allowed silently.
### Plugin or plain MCP [#plugin-or-plain-mcp]
| | Plugin | Plain MCP |
| ---------------------------------------------------------------------------------------------- | ------ | --------- |
| Send notifications | Yes | Yes |
| Ask questions, wait for answers | Yes | Yes |
| Enforced approval before risky shell commands, MCP calls, and Write, Delete or Edit tool calls | Yes | No |
| Works without installing anything locally | No | Yes |
The plugin bundles the same MCP tools and adds the gate.
## Use plain MCP instead [#use-plain-mcp-instead]
If you cannot install the plugin, add Pushary as an MCP server in `~/.cursor/mcp.json`, or in `.cursor/mcp.json` inside one project:
```json
{
"mcpServers": {
"pushary": {
"url": "https://pushary.com/api/mcp/mcp",
"headers": {
"Authorization": "Bearer pk_xxx.xxx"
}
}
}
}
```
Replace `pk_xxx.xxx` with your API key. Your agent gets the notification and question tools, so it can ping your phone and wait for an answer. Nothing is intercepted, though. The agent must choose to call the tools. If it never asks, you are never asked, even right before a dangerous command.
The plugin includes the Pushary skill. With plain MCP, install it so your agent knows when to notify you:
```bash
npx skills add Pushary/pushary-skill
```
## Troubleshooting [#troubleshooting]
### The gate never fires [#the-gate-never-fires]
Run `npx pushary@latest doctor`. It checks that the hook is registered and that its script path resolves. Then fully quit and reopen Cursor.
### I installed the plugin from the marketplace and nothing is gated [#i-installed-the-plugin-from-the-marketplace-and-nothing-is-gated]
The plugin on its own gives you the MCP tools, the rule and the skill. It does not link your API key or register the gate reliably across platforms. Run `npx pushary@latest setup` once to do both.
### Cursor asks me twice for one action [#cursor-asks-me-twice-for-one-action]
There are two causes.
Cursor also runs Claude Code's hooks. With Pushary set up for both, the Claude Code hook and the Cursor gate each asked about the same call. From CLI 1.9.62 the Claude Code hook leaves those calls to the Cursor gate. Run `npx pushary@latest upgrade` to get it. Pushary for Mac never caused this: it does not ask about the calls Cursor passes to Claude Code's hooks.
Your plugin copy still carries its own gate. Run setup again. It removes the gate from the plugin copy and keeps the one in `~/.cursor/hooks.json`.
### On Windows I get Cursor's own prompt and no push [#on-windows-i-get-cursors-own-prompt-and-no-push]
Cursor on Windows sends the hook a payload that starts with a byte order mark. Old gate versions could not read it and fell back to Cursor's prompt. The current gate reads it. If you patched the gate by hand, run setup again to get the shipped version.
### I want to see what the hook received [#i-want-to-see-what-the-hook-received]
Open Cursor's hooks output channel. It shows each hook call and its answer.
### Setup says Pushary for Mac handles Cursor's approvals [#setup-says-pushary-for-mac-handles-cursors-approvals]
The Mac app already owns Cursor's hooks. Setup reuses the app's key and keeps the app's hooks. To have the CLI own them instead, run `npx pushary@latest setup --take-over-hooks`.
## Next steps [#next-steps]