Cursor

The Cursor editor. One JSON file, and Cursor handles the sign-in itself when the file has no key in it.

Before you start#

You need: Cursor installed, and a text editor for one JSON file.

You will know it worked when: Cursor Settings → MCP lists gradworkbench with a tool count next to it.

Your workspace address is your app's address with /api/mcp on the end. The block on Settings → Research Access has yours already filled in, with a copy button — use that rather than typing it.

Where the file goes#

Two choices, and for this you want the second:

• .cursor/mcp.json in a project folder — available only in that project.
• ~/.cursor/mcp.json in your home folder — available everywhere.

Research is not tied to a codebase, so use the home-folder one. Create the .cursor folder if it does not exist.

Sign in — the short way#

1. Put this in ~/.cursor/mcp.json. If the file already exists, add the gradworkbench entry inside the existing mcpServers block rather than replacing the file:

{
  "mcpServers": {
    "gradworkbench": {
      "url": "https://gradworkbench.vercel.app/api/mcp"
    }
  }
}

2. Save it, then open Cursor Settings → MCP. GradWorkbench appears in the list with a sign-in prompt. Click it, approve the connection in the browser that opens, and come back.

3. The entry should now show as connected, with a tool count.

Use a key instead#

1. In Settings → Research Access, issue a key with Read your workspace and Submit research ticked. Copy it — it is shown once.

2. Add a headers block:

{
  "mcpServers": {
    "gradworkbench": {
      "url": "https://gradworkbench.vercel.app/api/mcp",
      "headers": { "Authorization": "Bearer sk_your_key_here" }
    }
  }
}

3. Save, and reload Cursor if the entry does not pick it up on its own.

Connect the second one, so research gets checked#

Whatever submits a finding is refused when it tries to confirm that same finding. Add a second entry with a different name and, if you are using keys, a second key with Read your workspace and Check research ticked — and not Submit research:

{
  "mcpServers": {
    "gradworkbench": {
      "url": "https://gradworkbench.vercel.app/api/mcp",
      "headers": { "Authorization": "Bearer sk_your_first_key" }
    },
    "gradworkbench-verify": {
      "url": "https://gradworkbench.vercel.app/api/mcp",
      "headers": { "Authorization": "Bearer sk_your_second_key" }
    }
  }
}

On the sign-in path, leave both headers blocks out and approve each entry separately in Cursor Settings → MCP.

Try it#

In Cursor's chat, with Agent mode on:

What's in my GradWorkbench workspace? Just summarise it — don't research anything.

If it comes back with your universities and professor counts, you are connected. Go to what to actually say.

When it doesn't work#

The file saved but nothing appears — invalid JSON. A missing comma between two entries is the usual cause; paste the file into any JSON validator. Cursor ignores a config it cannot parse rather than complaining.

Tools are listed but never called — Cursor only calls MCP tools in Agent mode. Ask in the chat's Agent mode, not Ask mode.

The sign-in window fails to return — Cursor uses fixed callback addresses (http://localhost:8787/callback on the desktop app). A firewall or a second Cursor window holding that port will break the handoff; close other Cursor windows and try again.

Editing the file did nothing — you edited the project file while working in a different project, or the other way round. ~/.cursor/mcp.json is the one that applies everywhere.

← Back to Connecting your assistant