Claude Code

Claude Code is the recommended one. It is a terminal program, it handles hour-long research runs without losing its place, and connecting it is a single command.

Before you start: install it if you haven't — the install instructions are here. You do not need to be in any particular folder for the commands below.

Before you start#

You need: Claude Code installed, and a terminal.

You will know it worked when: claude mcp list shows gradworkbench and ✔ Connected.

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.

Sign in — the short way#

Nothing to copy, nothing to keep safe.

1. Run this in a terminal:

claude mcp add --transport http gradworkbench https://gradworkbench.vercel.app/api/mcp --scope user

Replace the address if your workspace is somewhere else. Settings → Research Access shows this exact command with your address already in it and a button to copy it.

--scope user makes the connection available in every folder, so you never have to remember where you set it up. (The alternatives are --scope project, which writes a .mcp.json you could commit and share, and the default --scope local, which applies only to the folder you are standing in. For this, user is what you want.)

2. Start Claude Code and authorise it:

claude

Then type /mcp, pick gradworkbench, and choose Authenticate. A browser opens on your workspace and asks you to approve the connection. Approve it, and the browser hands control back.

3. Check it:

claude mcp list

You want gradworkbench followed by ✔ Connected. If it says ! Needs authentication, step 2 did not finish — run /mcp again.

Use a key instead#

Use this when you want the two separately-scoped connections that let research be checked — which is the whole point of connecting twice.

1. In Settings → Research Access, under Issue a new key, name it something you will recognise later ("Laptop researcher"), tick Read your workspace and Submit research, and press Issue key.

2. Copy the key. It is shown once and never again.

3. Run:

claude mcp add --transport http gradworkbench https://gradworkbench.vercel.app/api/mcp \
  --scope user \
  --header "Authorization: Bearer sk_your_key_here"

4. Check it with claude mcp list. A key connection goes straight to ✔ Connected — there is no separate authorise step.

If Claude Code warns about Leading or trailing whitespace in: headers.Authorization, your paste picked up a newline. Remove the connection with claude mcp remove gradworkbench and add it again.

Connect the second one, so research gets checked#

Whatever submits a finding is refused when it tries to confirm that same finding. So the verifier needs its own identity, under its own name.

Signing in:

claude mcp add --transport http gradworkbench-verify https://gradworkbench.vercel.app/api/mcp --scope user

Then /mcp → gradworkbench-verify → Authenticate, and approve it in the browser.

With a key: issue a second key with Read your workspace and Check research ticked — and not Submit research — then:

claude mcp add --transport http gradworkbench-verify https://gradworkbench.vercel.app/api/mcp \
  --scope user \
  --header "Authorization: Bearer sk_your_second_key"

Either way, claude mcp list should now show both, both connected.

Try it#

Start Claude Code and say:

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 and done. Go to what to actually say.

When it doesn't work#

✘ Failed to connect — claude mcp list prints the reason next to the status. A 404 usually means the address is missing /api/mcp; a 401 means the key was revoked or mistyped. Check the key in Settings → Research Access — if Last used says Never, nothing has reached the server.

! Needs authentication — run /mcp inside Claude Code and choose Authenticate. This is normal on the sign-in path and is not an error.

It connected but Claude doesn't use the tools — say what you want in terms of the workspace ("in GradWorkbench…"), not in terms of tools. If it still doesn't, check /mcp shows a tool count next to the server rather than zero.

Changing an existing connection — there is no edit. Remove and re-add:

claude mcp remove gradworkbench

Seeing exactly what it is configured as — claude mcp get gradworkbench prints the whole entry plus an Issue: line when something is wrong.

← Back to Connecting your assistant