# Cursor

Choose the reviewed Cursor config path and keep credentials in the client environment or secret store.

- Canonical: https://docs.xmemo.dev/docs/mcp/cursor
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 12bb993553e621843b7f8b6a70adcd9ff4b2ef38095daa171a447cc4f34f8553
- Edition-Digest: 3850d45fc8d0cec57fe470d1de6563c4f21a01c215a63836207087b02e017673
- Source-Revision: sha256:6d246486aef6d676aef49e112a718c42272f46abd70a244b63cb397ceb600c09

## Prerequisite

Use a Cursor version with Settings -> MCP or marketplace support. Cursor has a reviewed OAuth path and a direct XMEMO_KEY fallback for headless use.

- Endpoint: https://xmemo.dev/mcp.
- Preferred auth mode: browser OAuth.
- Fallback auth mode: direct bearer token for headless use.

## Install / setup

Open Cursor Settings -> MCP or install the reviewed server from the marketplace. For headless operation, use the existing direct configuration block on this page instead of the browser flow.

- OAuth path: configure the hosted URL only and let first use open browser consent.
- Direct fallback: keep the token in XMEMO_KEY, not in the settings file.
- Do not mix the OAuth entry with an Authorization header.

## Set the credential

OAuth path: no key — complete browser OAuth. Direct headless fallback: set XMEMO_KEY in the environment and never paste its value into Cursor settings.

```bash
# OAuth path: no XMEMO_KEY
# Direct fallback:
export XMEMO_KEY='<your-xmemo-token>'
```

## Generate / confirm XMEMO_AGENT_INSTANCE_ID

The reviewed Cursor OAuth and direct snippets do not require a client-side instance header. Confirm that the selected path has no identity header to add; if a headless wrapper supplies XMEMO_AGENT_INSTANCE_ID, generate it once per local profile and reuse it.

## Preserve the existing config block

Use the existing Cursor XMemo configuration block rendered on this page. Preserve the OAuth URL-only shape for the interactive path and the Authorization environment reference for the direct fallback.

## Restart the client

Restart Cursor after changing MCP settings or the direct environment so it reloads the selected authentication mode.

## Test with a real recall call

Make the first MCP call read-only. This is an actual recall invocation, not a health-check placeholder, and it does not write memory.

```text
recall({ query: "connection check", limit: 1 })
```

## Expected response (literal shape)

A successful call returns the public ranked text shape below; the reference and content are real values from the authorized memory space.

```text
### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>
```

## Common Errors

Cursor can fail on either its OAuth path or its direct headless fallback.

- invalid_grant — the OAuth authorization code is invalid, expired, or already used: reconnect Cursor and authorize again.
- 401 invalid_token — the direct fallback token is missing, expired, revoked, or otherwise invalid: verify XMEMO_KEY in the headless environment.
- 403 insufficient_scope — the credential does not grant memory:read: approve the required scope or issue a token with it.

## Headless fallback reference

Only use the direct fallback when the OAuth path cannot complete; the existing environment-backed Authorization block is the reviewed fallback.

## Cursor

Direct client: configure in ~/.cursor/mcp.json with XMEMO_KEY in the environment. Run npx @xmemo/client mcp add cursor to install automatically.

```
{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "cursor",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```