> ## 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

> Register a TrustGate MCP consumer in Cursor — mcp.json scopes, OAuth login, API-key headers, and tool approvals.

Cursor treats TrustGate as a **remote MCP server**: one `url` per
[MCP consumer](/trustgate/mcp/overview), and the agent sees the merged toolkit that consumer
is routed to. Copy the endpoint from the consumer **Connect** tab (Cursor snippet):

```text theme={null}
https://<mcp-host>/<consumer-slug>/mcp
```

MCP credentials are consumer credentials: **OAuth**, or an API key prefixed `ag_`. A
TrustGuard collector key (`tgk_…`) never authenticates MCP.

## Where the config lives

| Scope       | Path                                | Use it for                                                                 |
| ----------- | ----------------------------------- | -------------------------------------------------------------------------- |
| **Project** | `.cursor/mcp.json` in the repo root | A consumer tied to one codebase; commit it so the team gets the same tools |
| **Global**  | `~/.cursor/mcp.json`                | A consumer every project should reach                                      |

Both files load. When the same server name exists in both, the **project** file wins in
that workspace. Cursor infers the transport from the keys: `url` means remote, `command`
means local — never mix them in one entry.

## OAuth consumers (recommended)

Omit `headers` and let Cursor run the handshake. TrustGate advertises discovery at
`/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource` and
supports dynamic client registration, so no client ID or secret is pasted anywhere.

```json theme={null}
{
  "mcpServers": {
    "TrustGate": {
      "url": "https://<mcp-host>/<consumer-slug>/mcp"
    }
  }
}
```

Open **Customize** in the sidebar to find the server and complete the login. Cursor stores
the tokens; the tools then show up under **Available Tools** in chat.

Cursor authenticates from fixed callbacks —
`https://www.cursor.com/agents/mcp/oauth/callback` (web and Cloud Agents) and
`http://localhost:8787/callback` (desktop) — and TrustGate accepts both shapes, so nothing
has to be whitelisted per developer. Cursor's static `auth` block (client ID and secret) is
for providers without dynamic registration and is not needed here; which IdP backs the login
is a property of the consumer, set once in the console.

<Note>
  Use OAuth for consumers that resolve tools per user — the identity Cursor logs in with
  selects the [roles](/trustgate/concepts/roles), and therefore the registries and tools, on
  Identity-based consumers.
</Note>

## API-key consumers

Send the consumer key as a header. TrustGate accepts `X-AG-API-Key`, `x-api-key`, or
`Authorization: Bearer ag_…`.

```json theme={null}
{
  "mcpServers": {
    "TrustGate": {
      "url": "https://<mcp-host>/<consumer-slug>/mcp",
      "headers": {
        "X-AG-API-Key": "${env:TRUSTGATE_MCP_API_KEY}"
      }
    }
  }
}
```

Cursor resolves `${env:VAR}` in `url` and `headers`, so a committed project file carries no
secret. Export the variable where Cursor can read it (shell profile or your secret tooling)
and reload the window.

Authenticating to TrustGate is not the same as authenticating to the upstream servers. When
a registry uses **OAuth (forwarded)**, the first call for a user without a stored credential
returns a connect link; the user authorizes once and TrustGate vaults and refreshes the
credential from then on.

## Private (Hybrid) data plane

Add the gateway slug unless the MCP host already scopes the gateway:

```json theme={null}
"headers": {
  "X-AG-API-Key": "${env:TRUSTGATE_MCP_API_KEY}",
  "X-AG-Gateway-Slug": "<gateway-slug>"
}
```

For OAuth consumers on Hybrid, send `X-AG-Gateway-Slug` alone.

## Apply changes

After editing `mcp.json`, refresh the server (or toggle it off and on) in **Customize**.
Editing the file alone does not reconnect an already-loaded server, which is the most
common “my tools did not appear” cause.

## Tools and approvals

Two products decide two different things here, and the setting names are easy to confuse:

| Decision                          | Where it lives                                                                                                      | Notes                                                                                                                     |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Which tools the consumer exposes  | **NeuralTrust console** — consumer **Routing**, or a [role](/trustgate/concepts/roles) for Identity-based consumers | Bind MCP registries; **Restrict tools** narrows a registry to named tools. Leave it empty to grant the whole server       |
| The tool names Cursor sees        | **TrustGate**, automatically                                                                                        | Unique names pass through; a collision becomes `<registry>_<tool>`                                                        |
| Whether a call needs confirmation | **Cursor** — the agent's Run Mode                                                                                   | Approval is asked by default; in **Auto-review** allowlisted tools run immediately and the rest go through the classifier |
| Hiding a tool from this editor    | **Cursor** — server toggle in **Customize**                                                                         | Local only; the consumer still grants it                                                                                  |

The two Cursor rows are per laptop. Limits that must hold for every client belong on the
consumer or role. For an execution ceiling on MCP tool calls, attach the
[Per-Tool Rate Limiter](/trustgate/policies/tool-governance) policy — the other tool
governance policy, Tool Injection, is LLM-only and does not affect MCP.

## Team rollout

A gateway consumer is the same URL for everyone, so it distributes well from the Cursor
dashboard instead of asking each developer to edit `mcp.json`:

| Where                                 | What it does                                                                                                                                                                  |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Dashboard → Integrations & MCP**    | Register the consumer as a Team MCP server (also reaches Cloud Agents). **Add to Team Marketplace** makes it installable from **Customize** in the Agent Window, IDE, and CLI |
| **Team Settings → MCP Configuration** | MCP allowlist. A **URL entry** approves the MCP host pattern; a **tool allowlist** limits which of its tools may run automatically (empty allows all)                         |

Allowlisting approves a configuration; it does not install or enable the server. Keep the
authoritative tool scope on the consumer or role — the Cursor-side tool allowlist governs
automatic execution, not what the agent can see.

## With the NeuralTrust plugin

The [Cursor plugin](https://github.com/NeuralTrust/trustguard-cursor-plugin) can register
the same server from plugin variables (**Customize → Plugins → Configure**), so a team
admin sets it once instead of shipping `mcp.json`:

| Variable                 | Required               | Maps to             |
| ------------------------ | ---------------------- | ------------------- |
| `TRUSTGATE_MCP_URL`      | Yes                    | MCP `url`           |
| `TRUSTGATE_MCP_API_KEY`  | API-key consumers only | `X-AG-API-Key`      |
| `TRUSTGATE_GATEWAY_SLUG` | Hybrid only            | `X-AG-Gateway-Slug` |

Use the plugin entry **or** `mcp.json` — two entries with the same URL duplicate every
tool. `cursor.json` is the TrustGuard firewall config and never holds MCP values.

Firewall hooks are a separate plane: [TrustGuard Cursor](/trustguard/integrations/ide/cursor).
When both are installed, MCP `tools/call` traffic is still evaluated by the `preToolUse`
and `postToolUse` hooks.

## Verify

1. **Customize** lists **TrustGate** as enabled, and its tools appear under
   **Available Tools** in chat.
2. Ask the agent to call a tool bound to that consumer.
3. Confirm the call in TrustGate telemetry — see [Metrics](/trustgate/observability/metrics).

For connection or auth failures, open the Output panel (`Cmd+Shift+U`) and select
**MCP Logs**.

## Troubleshooting

| Symptom                                        | Cause                                                                                                                     |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Server connects, no tools                      | Consumer has no bound registries, tool restrictions exclude everything, or the upstream connect link was never authorized |
| `401` / repeated login                         | Wrong plane URL, revoked `ag_…` key, or `X-AG-Gateway-Slug` missing on Hybrid                                             |
| Edits ignored                                  | Server not refreshed in **Customize**, or an enterprise MCP allowlist does not cover the URL                              |
| Duplicate tools                                | Same consumer registered twice (plugin **and** `mcp.json`)                                                                |
| Registration rejected (`invalid_redirect_uri`) | The client presented a callback that is not `https`, an `http` loopback, or a private-use scheme                          |

## Related

* [MCP overview](/trustgate/mcp/overview) — consumers, catalog merging, upstream auth
* [Auth](/trustgate/concepts/auth) — MCP consumers use API key or OAuth2
* [TrustGuard Cursor](/trustguard/integrations/ide/cursor) — firewall hooks
* [Cursor MCP docs](https://cursor.com/docs/mcp)