---
title: "Cursor MCP Setup | Gazebo Docs"
description: "Add Gazebo to Cursor as an MCP server. Retrieve scoped credentials from your vault using the get_credential tool."
url: "https://gazebohq.com/docs/mcp/cursor"
---

> Documentation index: [llms.txt](https://gazebohq.com/docs/llms.txt). Markdown versions are available by appending `.md` to documentation page URLs.

Add Gazebo to Cursor as an MCP server so your agent can retrieve credentials from the vault using natural language tool calls.

## Prerequisites

- A Gazebo account with at least one service connected
- For manual bearer authentication only: an agent created in Gazebo with a bearer token

## Connect with OAuth

Add the following to your project `.cursor/mcp.json` or global `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gazebo": {
      "url": "https://app.gazebohq.com/api/mcp"
    }
  }
}
```

Save, then use Cursor's connect or sign-in action. Cursor can dynamically register a public client and open Gazebo's approval screen. Sign in, select only the service keys you want to share and choose an access deadline. Registration alone grants no access. Keep tool-call approval enabled while checking the connection.

OAuth credential requests must specify the approved `key_name`. Desktop and web/cloud connections can have separate sign-ins and execution environments.

**Tested with Cursor Desktop on macOS.** See the [compatibility guide](https://github.com/gazebohq/gazebo-mcp/blob/main/docs/client-verification.md) for detailed results.

## Manual bearer-token configuration

Add the following to your Cursor MCP config file at `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gazebo": {
      "url": "https://app.gazebohq.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:GAZEBO_AGENT_TOKEN}"
      }
    }
  }
}
```

Set `GAZEBO_AGENT_TOKEN` in the environment inherited by Cursor to the token from [Gazebo Agents](https://app.gazebohq.com/agents), then restart Cursor. This is a scoped Gazebo agent token, not a provider key. Do not commit real tokens to a project's configuration.

Use `<project>/.cursor/mcp.json` for project configuration or `~/.cursor/mcp.json` for global configuration. Remote servers do not support Cursor's `envFile` option. See [Cursor's current MCP documentation](https://cursor.com/docs/mcp) for configuration and environment interpolation. These instructions are documentation-checked, not a claim of a completed test in your installed Cursor version.

## Verify the connection

Ask Cursor to call `get_identity` — you should see your agent's name and connected services:

```
get_identity()
→ {
    status: "ok",
    name: "cursor-dev",
    accessible_services: [
      { service: "stripe", allowed_methods: ["GET", "POST"] }
    ]
  }
```

## Retrieve a credential

```
get_credential({ service: "stripe", key_name: "api_key", method: "GET" })
→ "<scoped-service-credential>"
```

Cursor (or your agent inside Cursor) can now use this credential to make Stripe API calls.

The runtime receives the actual provider key. The declared method limits retrieval, not subsequent API calls; the provider key's own permissions apply. Revoking Gazebo access prevents new retrieval, not use of previously retrieved keys.

## Handling denials

If `get_credential` returns a denial:

```json
{
  "status": "denied",
  "service": "stripe",
  "method": "DELETE",
  "allowed_methods": ["GET", "POST"]
}
```

The agent does not have `DELETE` access for Stripe. Update the access profile in the Gazebo dashboard to add the method, or use a permitted method instead. Do not retry without changing the policy — the denial will repeat.

The denial is JSON text inside an MCP tool result with `isError: true`; the HTTP response is `200`.

## Troubleshooting

**Cursor doesn't show Gazebo tools** — Check that `mcp.json` is valid JSON and that Cursor has restarted after the config change.

**`401 Unauthorized`** — The bearer token is invalid or the agent has been deleted. Verify the token in the Gazebo dashboard.

For OAuth, a revoked or expired connection requires signing in and approving access again. Revocation does not automatically reauthorize a client.

**`get_credential` returns `not_found`** — No credential is stored for that service. Connect the service in **Settings → Services**.
