Codex

OpenAI's coding agent, in the terminal. Worth using if you already pay for ChatGPT. It handles long runs well, which makes it the closest thing here to Claude Code.

Before you start#

You need: Codex installed, and a terminal.

You will know it worked when: codex mcp list shows gradworkbench.

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#

1. Add the server. Codex takes a remote server with --url:

codex mcp add gradworkbench --url https://gradworkbench.vercel.app/api/mcp

2. Tell it to use OAuth. Open ~/.codex/config.toml — create it if it isn't there — and make the entry look like this:

[mcp_servers.gradworkbench]
url = "https://gradworkbench.vercel.app/api/mcp"
auth = "oauth"

3. Sign in:

codex mcp login gradworkbench

A browser opens on your workspace and asks you to approve the connection. Approve it.

4. Check it:

codex mcp list

Use a key instead#

Codex reads the key from an environment variable rather than the config file, so your key never sits in a file you might commit or share. That is a genuine advantage over the JSON-based editors.

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

2. Put this in ~/.codex/config.toml:

[mcp_servers.gradworkbench]
url = "https://gradworkbench.vercel.app/api/mcp"
bearer_token_env_var = "GRADWORKBENCH_KEY"

3. Set the variable in your shell, and add the same line to ~/.zshrc (or ~/.bashrc) so it survives a restart:

export GRADWORKBENCH_KEY="sk_your_key_here"

4. Open a new terminal — the old one does not have the variable — and run codex mcp list.

Connect the second one, so research gets checked#

Whatever submits a finding is refused when it tries to confirm that same finding.

Signing in:

[mcp_servers.gradworkbench-verify]
url = "https://gradworkbench.vercel.app/api/mcp"
auth = "oauth"

then codex mcp login gradworkbench-verify.

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

[mcp_servers.gradworkbench-verify]
url = "https://gradworkbench.vercel.app/api/mcp"
bearer_token_env_var = "GRADWORKBENCH_VERIFY_KEY"

export GRADWORKBENCH_VERIFY_KEY="sk_your_second_key"

Try it#

Start Codex 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. Go to what to actually say.

When it doesn't work#

It cannot find the key — bearer_token_env_var names the variable, it does not hold the key. bearer_token_env_var = "sk_..." is the mistake people make; the value must be a variable name. Check with echo $GRADWORKBENCH_KEY in the same terminal Codex runs in.

It worked yesterday and not today — the export was typed into a terminal rather than added to ~/.zshrc, so it vanished when that window closed.

TOML complains about the section name — the table is [mcp_servers.name] with an underscore, not [mcpServers.name]. Codex is the only tool here that uses TOML at all, which makes this easy to get wrong when copying from another tool's docs.

A static header instead — if you would rather not use an environment variable, http_headers = { "Authorization" = "Bearer sk_your_key" } works, with the key sitting in the file. The environment variable is better.

← Back to Connecting your assistant