# Cursor MCP server setup and continuity test

Connect Cursor IDE or Agent CLI to Handover's remote Streamable HTTP MCP
server, verify the authenticated boundary, and prove a fresh Cursor agent can
retrieve and continue exact source context.

Canonical guide:
https://handover.sh/guides/cursor-mcp-server-setup

Handover endpoint:
https://handover.sh/api/mcp?profile=core

## What a passing setup proves

1. Cursor reaches the remote Streamable HTTP server.
2. A protected call resolves the expected named service identity.
3. Search and reads stay inside that identity's authorized boundary.
4. An approved private handoff can be created and read back exactly.
5. A separately authenticated successor can retrieve and continue it.
6. Missing, denied, read-only, stale, disabled, and revoked paths remain
   constrained.

A saved configuration, successful command exit, connected indicator, or tool
list proves only an earlier checkpoint.

## 1. Create two named service identities

Create two Handover service agents with the minimum workspace grants and
scopes required for the test:

```text
Cursor publisher: cursor-publisher
Cursor successor: cursor-successor
```

Use separate credentials. Never paste them into a prompt, repository,
handoff, screenshot, install URL, or this file.

## 2. Choose global or project scope

Use one configuration location:

```text
Global, private to this installation:
~/.cursor/mcp.json

Project, inherited by repository collaborators:
.cursor/mcp.json
```

Prefer the global file for a personal service credential. A project file can
describe the server, but it must not contain a populated credential.

Cursor IDE and Agent CLI read the same MCP configuration.

## 3. Expose the credential to Cursor

Set the credential in the environment that launches Cursor:

```bash
read -s HANDOVER_TOKEN
export HANDOVER_TOKEN
```

If the IDE is launched from a desktop icon, shell-only variables may not reach
the desktop process. Launch Cursor from the same terminal for the first test,
or configure the variable through the operating system's user environment.

Do not print the variable to diagnose this. Rotate the credential if it is
ever displayed in a transcript, issue, screenshot, or handoff.

## 4. Add the remote server

This configuration shape and the state commands below were validated with
Cursor Agent CLI `2026.07.23-e383d2b`.

```json
{
  "mcpServers": {
    "handover": {
      "url": "https://handover.sh/api/mcp?profile=core",
      "headers": {
        "Authorization": "Bearer ${env:HANDOVER_TOKEN}"
      }
    }
  }
}
```

Validate the JSON before opening Cursor:

```bash
python3 -m json.tool ~/.cursor/mcp.json >/dev/null
chmod 600 ~/.cursor/mcp.json
```

For a project file:

```bash
python3 -m json.tool .cursor/mcp.json >/dev/null
```

Cursor also supports an official one-click installer. The Handover link
contains the endpoint and environment-variable reference, not a populated
credential:

https://cursor.com/en/install-mcp?name=handover&config=eyJ1cmwiOiJodHRwczovL2hhbmRvdmVyLnNoL2FwaS9tY3A%2FcHJvZmlsZT1jb3JlIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyICR7ZW52OkhBTkRPVkVSX1RPS0VOfSJ9fQ%3D%3D

Review the decoded configuration before accepting any MCP install link.

## 5. Inspect the explicit connection state

```bash
agent --version
agent mcp list
agent mcp list-tools handover
```

The current CLI also accepts the backward-compatible `cursor-agent` command,
but `agent` is the primary entry point.

Important: in the tested CLI, an invalid static credential produced:

```text
handover: Error: Connection failed
```

while `agent mcp list` still exited with status zero. Do not use the shell exit
code alone as the health check. Parse and require the reported server state.

In Cursor IDE, open **Tools & Integrations > MCP tools** and inspect Handover's
state and available tools. Keep tool approval enabled during setup.

## 6. Understand service credentials and OAuth

Cursor supports OAuth for compatible remote MCP servers:

```bash
agent mcp login handover
```

Handover now exposes first-party dynamic client registration, authorization
code + PKCE, short-lived access tokens, and rotating refresh tokens. The
earlier `does not support dynamic client registration` incompatibility is
resolved. Use `agent mcp login handover` for an interactive profile; retain a
named service credential only for unattended automation.

## 7. Verify identity before reading

Ask Cursor Agent:

```text
Call Handover's identity tool. Show the server-resolved principal, company,
workspace, role, and scopes. Stop if any value differs from the expected
cursor-publisher identity.
```

Expected operation:

```text
handover.whoami
```

Never accept identity or workspace values supplied only in prompt text.

## 8. Verify protected reads

Expected operations:

```text
handover.search
handover.get
handover.read_artifact
```

Search for a known private record, open its canonical revision, and read one
exact source artifact. Pass only when the record is in the expected workspace,
the artifact matches the canonical source, and a denied record remains hidden.

## 9. Create and read back one private handover

Ask before the first write. Create a disposable private handoff with a unique
marker:

```text
CURSOR-MCP-SETUP-2026-08-04-01
```

Attach:

```markdown
# Cursor MCP verification

- Marker: CURSOR-MCP-SETUP-2026-08-04-01
- Objective: prove authenticated publish and read-back
- Constraint: private to the test workspace
- Next action: retrieve from cursor-successor
```

Expected operations:

```text
handover.create
handover.get
handover.read_artifact
```

Pass only when the server attributes the revision to `cursor-publisher`,
visibility remains private, and the exact artifact is retrievable from the
canonical revision.

## 10. Prove successor continuity

Use a fresh Cursor profile or installation with the `cursor-successor`
credential. Give it only the stable link or marker, not the publisher's
conversation.

Ask:

```text
Verify your identity, find this handoff, read the current source artifact,
state the exact marker, and continue the bounded next action using the current
expected revision. Read the result back.
```

Expected operations:

```text
handover.whoami
handover.search
handover.get
handover.read_artifact
handover.annotations
handover.continue
handover.get
```

Pass only when the server reports the successor identity, the exact artifact
is retrieved, the marker comes from that artifact, the write uses
`expectedRevisionId`, and the new revision records the successor as author.

## 11. Run negative tests

### Missing credential

Remove `HANDOVER_TOKEN` from a disposable profile. A protected call must fail;
the server must not guess or reuse another actor.

### Rejected static header

Use a dedicated invalid test credential. Cursor must report a connection
failure. Do not accept the command's zero exit status as a passing connection.

### OAuth identity mismatch

Run `agent mcp login handover` in a disposable interactive profile and approve
the browser consent. `handover.whoami` must resolve to the approving person,
company, workspace, and scopes rather than silently assigning another
identity.

### Disabled server

```bash
agent mcp disable handover
agent mcp list
```

The tested CLI reports:

```text
handover: disabled
```

Re-enable only after reviewing the configuration:

```bash
agent mcp enable handover
```

### Denied workspace

An identity without the test workspace grant must not discover titles,
summaries, artifacts, annotations, or counts.

### Read-only scope

A read-only identity may inspect granted context but must not create, continue,
annotate, assign, archive, or delete.

### Stale revision

Continue with an obsolete `expectedRevisionId`. The server must reject the
write until the agent reads and reconciles the current revision.

### Revoked credential

Revoke a dedicated test agent and call `handover.whoami` again. The old
credential must fail even if Cursor still has a local server entry.

## 12. Diagnose explicit states

```text
Connection failed, command exits 0
  Inspect the reported state, full URL, and named service credential.

HANDOVER_TOKEN is unresolved
  Launch Cursor with the variable or configure the OS user environment.

OAuth login fails
  Re-read discovery metadata, inspect the exact callback URI, and retry browser
  consent. Use a named service credential only for unattended automation.

handover: disabled
  Review the configuration, then run agent mcp enable handover.

Connected but tools unavailable
  Run agent mcp list-tools handover and inspect Cursor's MCP output logs.

Search returns nothing
  Verify whoami and search a known unique marker.

Write conflict
  Read the current revision, reconcile, and retry only with approval.
```

## 13. Remove local and remote access

Remove the Handover object from the relevant global or project `mcp.json`.
Then revoke the named service agent in Handover and require the old credential
to fail against `handover.whoami`.

`agent mcp disable handover` is temporary state control, not offboarding.
Deleting local configuration also leaves the remote credential valid.
Revoking only the credential leaves confusing stale configuration. Complete
offboarding requires local removal and remote revocation.

## 14. Record the result

```markdown
# Cursor MCP setup result

- Cursor Agent CLI version:
- Configuration scope: global | project
- Handover endpoint:
- Publisher identity:
- Successor identity:
- Workspace:
- Publisher revision:
- Successor revision:
- Exact artifact read-back passed:
- Missing credential passed:
- Rejected static header passed:
- Dynamic registration state recorded:
- Disabled server passed:
- Denied workspace passed:
- Read-only scope passed:
- Stale revision passed:
- Revocation passed:
- Local removal passed:
- Overall result: PASS | FAIL
- First failing checkpoint:
- Evidence:
```

Mark the workflow `PASS` only after the second authenticated identity retrieves
the exact source artifact and creates a verified successor revision.