Connecting your assistant

Research does not run inside GradWorkbench. It runs in an AI assistant you already have — Claude Code, Claude Desktop, Claude on the web, Codex, Cursor, Windsurf, Antigravity, VS Code, OpenCode, or anything else that speaks MCP. It reads university pages, faculty pages, Google Scholar and ORCID, and writes what it finds back into your workspace.

This chapter explains how that works and what to ask for. The step-by-step for your assistant is a page of its own — pick it from the table below.

Full screen

10.0 The five-minute path#

If you have never done this and want the shortest route that works, do exactly this and skip the rest of the chapter until something goes wrong.

1. Install Claude Code. It is a terminal program and the install is one command.

2. Run this, replacing the address if your workspace is somewhere other than the one below:

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

3. Run claude, type /mcp, choose gradworkbench, choose Authenticate, and approve it in the browser that opens.

4. Do steps 2 and 3 again, with gradworkbench-verify in place of gradworkbench. Two connections, not one — §10.4 explains why, and research stops dead at verification without it.

5. Check it:

claude mcp list

Both should say ✔ Connected.

6. Ask it something harmless:

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

If it answers with your universities and professor counts, you are done. Go to §10.5.

Already have a different assistant? Pick it from the table — every one of them works, and each has a page with the same six steps written for it.

10.1 Why it works this way#

The app could have done the research itself. It deliberately doesn't, and the reason is worth a paragraph because it explains most of what follows.

Research means reading dozens of pages per professor and judging what they say. Doing that well needs a capable model and a lot of reading. Doing it inside a web app means you are trusting a system you cannot watch, paying for tokens you cannot see, and taking whatever model the app happened to pick. Running it in your own assistant means you watch the work happen, you use the subscription you already pay for, and you can stop it.

What GradWorkbench provides is the other half: the workspace it writes into, the rules it follows, and the checks it cannot skip. Your assistant connects to it over MCP — the Model Context Protocol, an open standard for letting an assistant use an outside tool. Once connected, GradWorkbench appears in your assistant as about fifty tools it can call: read your profile, propose a department, submit a finding, check a source.

You do not need to understand MCP to use it. You need to paste one thing into one place, which is what the next pages are.

10.2 Pick your assistant#

Every one of these works. If you have none of them and no preference, install Claude Code.

Each page covers both ways of connecting, how to check it worked, and what goes wrong in that particular tool. They repeat each other on purpose — you should never have to read two of them.

10.3 The two ways to connect#

Settings → Research Access offers both and writes the setup for you either way. The choice is not about security; both end up with the same permissions.

Full screen

1 is the Settings tab you want. 2 is the choice between signing in and using a key. 3 is your assistant — ten of them, and the tab you pick changes everything below it, because they do not all take the same configuration. 4 copies the block. 5 is the block itself, already filled in with your workspace's address. 6 goes to that assistant's page in this chapter.

Everything on that card is generated for your workspace, so it is always correct even if this chapter is not.

Signing in is the shorter path. You give the assistant the address, it sends you back here to approve it, and that is the whole thing. No key to copy, nothing to keep safe, and you can disconnect it from the same page later. Every assistant in the table above supports it.

Using a key is the older path, and still the right one when you want two separately-scoped connections — see §10.4. Issue the key and the setup blocks on the page fill themselves in.

Either way the assistant can only do what you allowed, nothing can send an email, and nothing reaches your record without you publishing it.

Your address#

Everything below needs one value: your workspace's MCP address, which is your app's address with /api/mcp on the end.

https://gradworkbench.vercel.app/api/mcp

If you are running GradWorkbench somewhere else, use that address instead — and rather than typing it, open Settings → Research Access, where every block on this page is already filled in with yours and has a copy button.

The permissions, and what they mean#

When you issue a key you choose from five. When you sign in, the assistant asks for what it needs and you approve it on screen. They are the same five either way.

Full screen

1 is the label — name it after whatever will use it, because in six months "gradworkbench" tells you nothing and "Laptop researcher" tells you everything. 2 is the permission set. 3 issues it, and the key is shown once. 4 is the list of every key you have, with when each was last used — a key that says Never means nothing has ever reached the server with it, which turns a research problem into a setup problem.

A connection that does the research wants the first two. A connection that checks it wants the first and third — and only the third, which is the whole point of the next section.

10.4 Connect twice, if you want research checked#

Connect once with Submit research and again with Check research, under two names.

Two, not one, because of the single rule the whole system rests on: whatever finds a fact is refused when it tries to confirm that same fact. A research pass produces claims; a separate pass with a separate identity checks each claim against the source it cites; only then does anything become part of your record.

That is not ceremony. An assistant asked to check its own work will agree with itself almost every time — it is reading the same page with the same expectations. The independence is the only thing standing between a confident-sounding claim and a checked one. With a single connection, research runs and then stops dead at verification.

What the server actually compares#

Not your account, not the assistant, not the machine — the connection the request arrives on. Every finding is stored with the connection that submitted it. When a verification verdict arrives, the server compares the two, claim by claim, and refuses any claim whose research came in on the same connection that is now trying to confirm it. The refusal is worded:

Claim … was produced by the same agent credential attempting to verify it — verification must be independent.

The same comparison guards publications and batch items, so there is no side door: you cannot verify a paper you submitted, and you cannot close a batch item whose research you did.

A few consequences that are easy to guess wrong:

• Two keys in one assistant is fine. The two connections can live in the same Claude Code or Codex session, one conversation, one machine. Nothing has to run twice, or anywhere else. It is the connection that must differ, not the computer or the person.
• Signing in twice counts as two connections. OAuth sign-in creates a connection entry exactly as a key does. Two sign-ins under two names are two identities and satisfy the rule.
• One key with both permissions ticked does not work. It is a single connection, so it is refused at the moment it tries to check itself, no matter how many permissions it carries.
• Reconnecting the same name does not reset anything. The check is against what submitted the finding, which is recorded on the finding itself.

What it looks like when you have only one#

Research runs, looks productive, and produces claims — then verification fails with the message above, and everything stays candidate. Nothing reaches your record: no match scores, no email drafts, because both refuse to build on unverified findings. The symptom reads like the research broke. It didn't; the second connection is missing.

Setting up the second one#

Every page in this chapter shows you how, tool by tool. The shape is the same everywhere:

1. Add the server a second time, under a second name. The convention throughout is gradworkbench and gradworkbench-verify.
2. Give the second one Read your workspace and Check research — and not Submit research. Withholding it is what makes the two connections genuinely different rather than differently labelled. (Signing in a second time instead of using a key does the same job.)
3. Say which is which when you ask for work: research through gradworkbench, verify through gradworkbench-verify. Your assistant sees two near-identical sets of tools and has no way to know your intent otherwise. Nothing in the client enforces the split — only the server does, by refusing.

If you are using keys, copy each one when it is shown — they are shown once.

Settings → Research Access lists both connections and when each was last used, which is the quickest way to tell a wiring problem from a research problem: a connection reading Never has never been reached at all.

One practical limit: a free Claude plan allows a single custom connector, one short of what this needs. Use sk_ keys instead, or a plan that allows two.

10.5 What to actually say#

You do not have to write any of this yourself. Every university, department and professor page has a Research this button that hands you the prompt for whatever that record needs next, with its name already in it — copy, paste, send. Prompts in the sidebar lists every job an assistant can be given, and the dashboard leads with the single next thing worth doing and the prompt that does it.

The rest of this section is what those prompts look like, so you can edit them or write your own. Once connected, you talk to your assistant normally. It knows the tools; you don't need to name them.

Starting a university from nothing:

Research the University of Illinois Urbana-Champaign in GradWorkbench. Find the departments that could admit someone with my profile and propose them. Stop there.

You do not need a professor list first. A name is enough — the assistant creates the university record and the research fills in the rest.

After you have picked departments in the app:

The Siebel School is selected now. Research its programs and labs, then propose the faculty whose work overlaps mine. Don't research anyone in depth yet.

Deep research on professors you approved:

Research these five professors properly: their recent papers, their group, and whether they're taking students for Fall 2027. Use the researcher connection to submit and the verifier connection to check. Report anything you couldn't confirm.

The match:

Write the match for Lingming Zhang — the fit score, the dimension breakdown, and at least three specific ways my work connects to his. Include the honest mismatches.

Being explicit about the two connections is the one thing worth doing every time. If an assistant tries to verify with the connection that submitted, it gets refused and may waste several turns trying to work around a rule it cannot work around.

Asking, rather than asking for work#

Once research exists you will want to ask about it, and that is not a request to do the work again:

Looking at what's already in GradWorkbench for Illinois, which professors fit me best and why?

Who there is actually taking students for Fall 2027?

Why did this one score so low?

The assistant answers from what is recorded rather than starting a research run. It will tell you when something has not been researched instead of filling the gap, say which claims have been checked and which are still unverified, and put a stated "not taking students" above a high fit score — because a 92 you cannot write to is not the answer to "who should I contact first".

The Ask about this button on a university or professor page hands you the prompt for it, the same way Research this does.

If a request is genuinely ambiguous — "tell me about Professor Chen" could be either — the assistant asks which you meant. A sentence of clarification costs seconds; guessing wrong costs an hour of research nobody asked for.

10.6 The gates it stops at#

Your assistant will stop and hand back to you at four points. This is deliberate — every step after a wrong decision is wasted work.

Gates 1 and 2 are the assistant stopping. Gates 3 and 4 are enforced by the platform: an assistant cannot publish its own findings to your record no matter what it is told.

Gate 3 is the one people miss. Checked research does not appear on a professor's page until you publish it, and until it is published, matches cannot cite it. If research seems to have run but a professor's page still looks thin, look at Review → Ready to publish.

It no longer decides who to skip#

Earlier versions told the assistant to research only tenure-track faculty and skip the rest. That instruction has been removed, because the label it acted on is not reliable: an imported roster carries whatever the university's staff directory said, and real tenure-track faculty regularly arrive labelled affiliate or adjunct.

Your assistant now researches whoever it is given and records three separate things — the appointment type, the normalized rank, and any administrative post. Whether somebody is worth pursuing is your decision, expressed in Settings → Research Batches and on the Professors list, and described in §3.2a, Who gets researched.

If you are running a research prompt you saved months ago and it still says to skip non-tenure-track people, that is why it should come out.

10.7 Costs, and keeping them sane#

Research is the expensive part: a thorough pass on one professor reads a lot of pages.

GradWorkbench routes work to different models by how hard it is — cheap models for mechanical jobs like tidying links, the strongest ones for match analysis where the failure mode isn't an error but a fluent paragraph with the honest mismatches quietly missing. Settings → Model Routing shows the defaults and lets you override them.

Two habits that help more than any setting: research in small batches and look at the results, and be specific about who to research. "Research everyone at Illinois" is expensive and mostly wasted; five professors whose work you have actually looked at is neither.

10.8 What it sees, and when#

Two questions come up once you have been using this for a while.

"I changed a setting mid-conversation. Does the assistant notice?"

Yes, on its next call. Nothing is baked in at connection time — every tool reads the database when it runs, so your review mode, batch size, email guidelines, model routing and research procedures are whatever they are at that moment.

The catch is what the assistant already read. If it fetched your email guidelines ten minutes ago it still has that copy in front of it and has no reason to look again. So after changing something mid-conversation, say so: "I changed the email guidelines — re-read them before the next draft." That is enough. You do not need a new chat, and reconnecting changes nothing.

"We added a new field. Do we have to update the MCP server?"

Depends which direction.

Reading — no. Tools hand back the whole record, so a new column, or a new key inside your research interests and preferences, is visible the moment it exists. Same for new profile entries: the assistant sees every education, publication and project you add without anyone touching the server.

Writing — yes. The write tools list their fields explicitly, so a new column is not writable until it is added to the matching tool. This is deliberate: it is what stops an agent setting its own dataQuality to verified, or deciding which departments you are pursuing.

The failure mode used to be silent — an assistant sending an unknown field got no error and no write. There is now a test that fails the build when a column is writable in the app but not over MCP, so the gap gets caught before anyone hits it. If it fires, either add the field to the tool or record why it should stay off-limits.

10.9 When it doesn't work#

Tool-specific problems are on each tool's own page. These four are the same everywhere.

"Verification must be independent" — the assistant used one connection for both jobs. Tell it which is which, or make the second connection — §10.4.

"No active humanization_instructions policy document" — anything a professor reads must go through your writing rules, and they are not set up yet. Settings → Writing Rules.

Research ran but nothing changed — almost always gate 3. Review → Ready to publish.

"is not verified/promoted" — the same thing from the other direction: a match is trying to cite a publication that has not been published yet. Publish it, then retry.

The assistant says a field can't be recorded — the vocabulary for professor facts is a fixed list, so teaching, awards and funding have nowhere structured to go. Ask it to put them in the biography summary and mention it.

And one that is worth checking before any of the above: Settings → Research Access lists every connection and when it was last used. A connection that has never been used means nothing has reached the server at all, which makes it a setup problem rather than a research one.

← Questions and fixes · Contents