OpenCode

The open-source terminal agent. Its config shape is different from everything else here — servers live under mcp rather than mcpServers, and a remote one has to say "type": "remote".

Before you start#

You need: OpenCode installed, and a model that can call tools.

You will know it worked when: OpenCode lists the server without asking you to sign in again.

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#

• ~/.config/opencode/opencode.json — everywhere. Use this one.
• opencode.json in a project folder — that project only.

They are merged rather than replaced, so a project file can add to the global one without repeating it.

Sign in — the short way#

1. Put this in ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gradworkbench": {
      "type": "remote",
      "url": "https://gradworkbench.vercel.app/api/mcp",
      "enabled": true
    }
  }
}

2. Start OpenCode. It handles the sign-in itself — a browser opens on your workspace and asks you to approve the connection. It registers itself automatically; there is nothing to set up on the GradWorkbench side first.

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 the header, and turn OAuth off so OpenCode does not try to sign in over the top of the key:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gradworkbench": {
      "type": "remote",
      "url": "https://gradworkbench.vercel.app/api/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer sk_your_key_here" }
    }
  }
}

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 second key that has Read your workspace and Check research ticked — and not Submit research:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gradworkbench": {
      "type": "remote",
      "url": "https://gradworkbench.vercel.app/api/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer sk_your_first_key" }
    },
    "gradworkbench-verify": {
      "type": "remote",
      "url": "https://gradworkbench.vercel.app/api/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer sk_your_second_key" }
    }
  }
}

Try it#

In OpenCode:

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#

Nothing appears — the block is mcp, not mcpServers. OpenCode is the only tool here that names it that way.

It tries to run a command — "type": "remote" is missing. Without it OpenCode assumes a local process.

It keeps asking you to sign in even with a key — add "oauth": false.

Your model can't call tools — OpenCode lets you bring your own model, and a small local one may not support tool calling well enough to work through a research batch. Try a frontier model before concluding the connection is broken.

← Back to Connecting your assistant