Coreby Gradien
Docs
Start free today

Agent guide

Cursor Setup

Back to setup docsRaw source

Paste this into your agent

Start with this visible request when you want the agent to help. It keeps the action coming from you, while the linked setup reference stays plain and non-recursive.

Use this in the app you are connecting, then approve only the browser login, app setting, or restart steps that the app requires.

Please help me set up Core for Cursor. Core is a home base for AI agents: it keeps memory, files, decisions, tasks, and work context synced across tools, harnesses, and models.

Use this official setup reference:
https://gradien.ai/core/docs/reference.txt

Source checked: 2026-06-19 Official source: https://cursor.com/docs/mcp.md

Cursor supports MCP configuration through Cursor settings and mcp.json. Use the markdown docs as the source of truth because they are easier for agents to fetch. Cursor supports remote Streamable HTTP MCP servers through a url field and handles OAuth for remote servers.

Core hosted remote MCP URL: https://core.gradien.ai/mcp

Global config path: ~/.cursor/mcp.json. Project config path: .cursor/mcp.json. Prefer global config for Core so the user carries Core across projects.

Expected global config shape:

{
  "mcpServers": {
    "core": {
      "url": "https://core.gradien.ai/mcp"
    }
  }
}

Recommended setup path:

  1. Fetch current Cursor MCP docs before changing config; Cursor labels and auth behavior change over time.
  2. Use Cursor native config first: inspect existing ~/.cursor/mcp.json, back it up, preserve other mcpServers, and add only the Core server entry.
  3. If the user wants a guided CLI walkthrough, run the setup CLI with --harness cursor --yes; it should create Core signup/login, then merge Core into ~/.cursor/mcp.json and back up the previous file.
  4. Do not put bearer tokens or connector keys in Cursor config unless OAuth is impossible and the user explicitly approves that fallback.
  5. Ask the user to reload Cursor or run Cmd+Shift+P -> Developer: Reload Window. Existing Cursor chats may not hot-load new MCP servers.
  6. If Cursor prompts for OAuth, have the user approve Core in the browser.
  7. If Cursor shows Core as user-core, unauthenticated, or with only mcp_auth, that is an auth-ready state, not a failed install. Run the visible mcp_auth tool if the agent can, or ask the user to click Connect/Authenticate in Cursor Settings -> Features -> Model Context Protocol.
  8. If Cursor stays on Waiting for callback... or Exchanging token... after the browser opened Cursor, stop repeated Connect/Allow clicks. Fully quit and relaunch Cursor once, then inspect Cursor MCP Logs before another auth attempt.
  9. In logs, repeated unauthenticated requests from Cursor/<version> to /mcp mean the server is reachable but Cursor did not complete/store OAuth. Treat this as a Cursor OAuth callback state, not a bad mcp.json URL.
  10. Verify after reload/auth with Cursor MCP tools or Cursor MCP logs. Logs are in the Output panel (Cmd+Shift+U) -> MCP Logs.
  11. If native OAuth keeps hanging after one clean relaunch, use the fallback only with explicit user approval: create a scoped Core connector key from Core Settings -> Connectors, then add it as an HTTP Authorization header in Cursor mcp.json. Prefer ${env:CORE_CONNECTOR_KEY} interpolation if Cursor resolves it in the user's version; otherwise warn that a pasted key is stored locally in plaintext and should be rotated later.

If Cursor rejects the minimal remote config, retry using the latest Cursor-documented remote server shape. Some examples include an explicit type for HTTP servers; keep the URL as the source of truth and do not add secrets.