Cursor

Prerequisite

Use Cursor IDE with Settings -> Features -> MCP or marketplace support. Interface and prerequisites:

• Concrete interface: Cursor IDE (~/.cursor/mcp.json or Settings -> Features -> MCP).
• Endpoint: https://xmemo.dev/mcp.
• Preferred auth mode: Browser OAuth.
• Fallback auth mode: Direct bearer token for headless and container environments.
• Account: Valid XMemo account at https://xmemo.dev.

Install / setup

Open Cursor Settings -> Features -> MCP or configure ~/.cursor/mcp.json. For headless operation, use the direct configuration block with environment token reference instead of the browser flow:

• OAuth path: Configure the hosted URL only and let first use trigger browser consent.
• Direct fallback: Keep the token in XMEMO_KEY, never directly in the settings file.
• Do not mix the OAuth URL configuration with an Authorization header in the same entry.

Set the credential

OAuth path requires no key — complete browser OAuth on first prompt. For direct headless fallback, set XMEMO_KEY in the shell environment and never paste token values into Cursor settings:

# OAuth path: no XMEMO_KEY needed (browser prompt)
# 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. If a headless wrapper supplies XMEMO_AGENT_INSTANCE_ID, generate it once per local profile and reuse it.

Preserve the existing config block

Preferred OAuth path: Use the reviewed URL-only Cursor configuration in ~/.cursor/mcp.json for browser-based OAuth authentication:

{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp"
    }
  }
}

Direct fallback config block

Direct headless fallback: When running Cursor in headless or non-interactive environments, configure the Authorization header referencing ${env:XMEMO_KEY} from your local environment:

{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}"
      }
    }
  }
}

Restart the client

Restart Cursor or toggle the MCP server off and on in Settings -> Features -> MCP after editing configuration so changes take effect.

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.

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.

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

First useful task: Synthetic memory lifecycle

Exercise the complete synthetic memory task inside Cursor Composer or Agent mode:

• 1. Save synthetic fact: Ask Cursor to remember convention ("Demo project timestamps use UTC.") to "projects/demo-onboarding/conventions".
• 2. Stateless transition: Start a new Cursor Composer chat or reopen the project workspace.
• 3. Recall with source attribution: Query "demo project timestamp format". Confirm returned Reference and Location.
• 4. Correct memory: Call update_memory with active ID to format timestamps with ISO 8601.
• 5. Optional cleanup: Call forget with memory ID when onboarding testing completes.

Capabilities and profile tools

Cursor has access to profile-qualified tools defined in the MCP documentation contract for cursor-plugin profile:

• Core memory tools: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context, search_knowledge.
• Snapshot and conflict tools: create_restart_snapshot, restore_restart_snapshot, list_memory_versions, list_memory_conflicts, resolve_memory_conflict.
• Project and planning tools: get_mcp_identity, get_project_context, get_timeline, list_memory_todos, complete_memory_todo, create_memory_todo, update_project_decision, update_project_todo, update_state.
• Cloud skills and governance: recall_cloud_skill, save_cloud_skill, propose_write, propose_todo_mutation, propose_profile_mutation, query_audit, record_event, memory_stats.

Limitations and boundaries

Operational boundaries and constraints for Cursor:

• Config purity: Do not mix OAuth URL-only configuration with an Authorization header in the same server block.
• Workspace boundary: Memory access is strictly limited to the authenticated user's workspace.
• Headless token requirement: Direct MCP fallback requires explicit environment token provisioning.

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 — Direct fallback token is missing, expired, or invalid: verify XMEMO_KEY in the headless environment.
• 403 insufficient_scope — Credential does not grant memory:read: approve the required scope or issue a token with it.

Update and removal

Maintenance procedures for Cursor:

• Update: Toggle the server off and on in Cursor MCP settings to reload schemas.
• Removal: Delete the xmemo entry from ~/.cursor/mcp.json or remove it from Cursor MCP settings.