> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuraltrust.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor

> Screen prompts, tool calls, and tool results in Cursor — TrustGuard firewall hooks plus the TrustGate MCP Gateway in one plugin.

The [NeuralTrust Cursor plugin](https://github.com/NeuralTrust/trustguard-cursor-plugin)
covers the two risks of agentic coding in Cursor — what the agent is **told**,
and what the agent **does**. It runs on each developer machine and puts your
org's policy check at each moment:

| Moment                                                  | What you can stop                                                                                                                                                                         | Enforcement                                                                                                             |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Prompt, before submit                                   | Jailbreaks ([Prompt Guard](/trustguard/detectors/content-security#prompt-guard--prompt_guard)); secrets and PII pasted into the agent ([DLP](/trustguard/detectors/data-loss-prevention)) | **Block** (Cursor has no Ask dialog at this event)                                                                      |
| Tool call, before it runs (Shell, MCP, everything else) | Dangerous or out-of-policy shell commands; risky MCP tool calls                                                                                                                           | **Block** or **Ask** (Cursor approval prompt)                                                                           |
| Tool result, after it runs                              | [Indirect prompt injection](/trustguard/detectors/agent-mcp-security) in MCP / tool output                                                                                                | **Warn** — Cursor's `postToolUse` cannot block, so findings are injected as an untrusted-content warning the agent sees |

Every decision lands in **Activity** with `consumer_id` = `cursor:<email>`, so
you also get a per-developer audit trail; start in **Report** policy mode to
observe before enforcing.

The **TrustGate MCP** half is governance for the tools themselves: instead of
developers wiring arbitrary MCP servers, the agent gets one org-curated
endpoint whose tool calls still pass through the firewall hooks above.

## Coverage

| Surface     | Monitor | Block | Redact |
| ----------- | :-----: | :---: | :----: |
| LLM input   |    ✅    |   ✅   |    ❌   |
| LLM output  |    ➖    |   ➖   |    ➖   |
| Tool call   |    ✅    |   ✅   |    ❌   |
| Tool result |    ✅    |   ✅   |    ❌   |

**Ask** — honoured on tool calls, through Cursor's approval prompt. There is no
dialog at the prompt event, so an `ask` on a prompt is enforced as a block.

**Use it when** your developers work with the Cursor agent and you want its tool
calls governed from one org key. **Not when** you rely on `ask` stopping a
prompt — Cursor has no confirmation dialog at that event and submits with a
warning.

**Limits.** No redaction: `transform` maps to `ask` by default, so a masking
policy degrades to a warning unless `transform_action: "deny"` is set. The
model's response is never evaluated, and `postToolUse` cannot revoke a tool that
already ran. Tool declarations are not evaluated.

Full comparison: [Coverage](/trustguard/integrations/coverage).

## Two surfaces, two credentials

The plugin (`trustguard` package) ships both surfaces:

| Surface              | Role                                                                                | Credential                                         |
| -------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------- |
| **TrustGuard hooks** | Prompts, tool calls, tool results → [`POST /v1/evaluate`](/trustguard/api/evaluate) | Org Cursor collector `tgk_…` (MDM / `cursor.json`) |
| **TrustGate MCP**    | Aggregated MCP tools for the agent                                                  | Plugin variables: MCP URL (+ API key if not OAuth) |

Developers do not need NeuralTrust accounts for the firewall path. Do **not** reuse
the `tgk_…` collector key as an MCP credential.

## What IT deploys vs what developers install

| Component           | Who                                                     | What                                                    |
| ------------------- | ------------------------------------------------------- | ------------------------------------------------------- |
| **Plugin**          | Each developer (or Team Marketplace / standard rollout) | Import from GitHub — see below                          |
| **Firewall config** | IT / MDM                                                | `cursor.json` with the org `tgk_…` key                  |
| **MCP config**      | IT (team plugin variables) or developer                 | `TRUSTGATE_MCP_URL` (+ optional API key / gateway slug) |

You do **not** need to package or push the plugin binary tree via MDM. MDM only needs
the managed firewall config file. The plugin’s bootstrap downloads the platform
`trustguard-cursor` binary from GitHub Releases on first use (checksum-pinned).

## Console setup

1. Create a **Cursor** collector (Catalog → IDE & coding agents).
2. Mint a `tgk_…` API key on the **Auth** tab (shown once — store it).
3. Assign a default [policy](/trustguard/concepts/policies) on the **Policies** tab.

## Install the plugin (from GitHub)

The plugin is published as a public GitHub repo. In Cursor, add it the same way you
import any GitHub-hosted plugin (Plugins / marketplace → import or add from GitHub):

**Repository:** [https://github.com/NeuralTrust/trustguard-cursor-plugin](https://github.com/NeuralTrust/trustguard-cursor-plugin)

Exact UI labels vary by Cursor version; look for add/import plugin from GitHub or from a
git URL and paste that repo.

### Local clone (optional)

If you prefer a local checkout (e.g. offline pilots):

```bash theme={null}
git clone https://github.com/NeuralTrust/trustguard-cursor-plugin.git
cd trustguard-cursor-plugin
make install-local
```

Or **Customize → Plugins → Add → From Local Repo** pointing at the clone.
`make install-local` copies into `~/.cursor/plugins/local/trustguard` (Cursor rejects
out-of-tree symlinks).

## Managed config (MDM — config only)

Deploy **only** this file with MDM. Do not distribute the plugin package via MDM unless
you have a separate reason to pin a private fork.

```json theme={null}
{
  "data_url": "https://<your-trustguard-host>",
  "api_key": "tgk_…",
  "fail_mode": "closed"
}
```

| OS      | Managed config path                                   |
| ------- | ----------------------------------------------------- |
| macOS   | `/Library/Application Support/TrustGuard/cursor.json` |
| Linux   | `/etc/trustguard/cursor.json`                         |
| Windows | `%ProgramData%\TrustGuard\cursor.json`                |

### Managed mode

When the managed file includes `api_key`:

* **Locked:** `api_key`, `data_url`, `fail_mode` — user file and env cannot replace them.
* **Soft prefs** may still live in `~/.trustguard/cursor.json`: `timeout_ms`,
  `transform_action`, `events`, `consumer_id`.

### Local config only (no MDM)

For pilots without MDM, write `~/.trustguard/cursor.json` (`chmod 600`) with the same
JSON shape.

## TrustGate MCP Gateway (same plugin)

The plugin registers a remote MCP server named **TrustGate**. Values are Cursor
[plugin variables](https://cursor.com/docs/reference/plugins) (Customize → Plugins →
**Configure**), not `cursor.json`.

1. In the console, open an **MCP consumer** → **Connect** and copy the endpoint
   `https://{host}/{consumer-slug}/mcp`.
2. Set:

| Variable                 | Required          | Notes                                 |
| ------------------------ | ----------------- | ------------------------------------- |
| `TRUSTGATE_MCP_URL`      | Yes               | Full URL from Connect                 |
| `TRUSTGATE_MCP_API_KEY`  | API-key auth only | `X-AG-API-Key`. Leave empty for OAuth |
| `TRUSTGATE_GATEWAY_SLUG` | Hybrid only       | `X-AG-Gateway-Slug`                   |

OAuth consumers need only the URL — Cursor runs the login flow on first tool use.
Team admins can set variables once for Team Marketplace installs.

MCP tool calls still pass through TrustGuard hooks (`preToolUse` / `postToolUse`).
`tool.name` is `payload.params.name`: for Cursor’s `mcp__<server>__<tool>` that is
the last segment. Gate on that short name, not the full hook `tool_name`.

Ask on `preToolUse` shows Cursor’s permission dialog with
`A TrustGuard policy needs your approval to continue.` (not the gate name).

## Verify

### Firewall

1. Open Cursor and send a test prompt.
2. Confirm the event in TrustGuard **Activity**.
3. `consumer_id` is typically `cursor:<email>` when the Cursor account email is present.

Smoke-test the binary (optional):

```bash theme={null}
echo '{"hook_event_name":"preToolUse","tool_name":"Shell","tool_input":{"command":"echo hello"},"user_email":"you@company.com"}' \
  | trustguard-cursor hook
```

### MCP

1. Confirm **TrustGate** is enabled under Customize → MCP.
2. Ask the agent to list or use a tool from a toolkit bound to that consumer.

## What is evaluated

| Cursor hook                                         | TrustGuard                                                       |
| --------------------------------------------------- | ---------------------------------------------------------------- |
| `beforeSubmitPrompt`                                | `protocol: llm`, `direction: input`                              |
| `preToolUse` (Shell)                                | `protocol: all`, `{ "input": "<command>" }`, `direction: input`  |
| `preToolUse` (other tools, including TrustGate MCP) | `protocol: mcp`, `tools/call` (`params.name` = last MCP segment) |
| `postToolUse`                                       | `protocol: mcp`, tool result, `direction: output`                |

## Attributes

* `attributes.collector.type = "ide"`
* `attributes.source.application = "cursor-plugin"`
* `attributes.cursor.event`, workspace, and related fields
* `consumer_id` typically `cursor:<email>`

Gate on `source.application` and/or `tool.name` / `tool.command`. Do not rely on
`attributes.tool` for MCP `preToolUse` — the name is on the payload.

## Related

* [Plugin README](https://github.com/NeuralTrust/trustguard-cursor-plugin)
* [Policies — Gates](/trustguard/concepts/policies#gates)
* [Evaluate API](/trustguard/api/evaluate)
* [TrustGate MCP in Cursor](/trustgate/integrations/cursor)
* [TrustGate auth](/trustgate/concepts/auth)