Codex CLI

Add justcrawl as an MCP server in the Codex CLI (codex from OpenAI). Once wired, any codex session can call jc_jobs_submit, jc_workflows_list, and the rest of the justcrawl tools from inside the terminal chat.

Prerequisites

Codex CLI installed (npm install -g @openai/codex — see the OpenAI Codex CLI repo for the canonical install)
Node.js 20 or newer on PATH (node --version to check)
A justcrawl API key — Settings → API Keys in the dashboard. Starts with sr_live_.

Persistent vs per-session

Codex reads MCP server definitions from ~/.codex/config.toml. Two ways to use justcrawl:

| Mode | How to enable | When to use | |------|---------------|-------------| | Persistent | Add the [mcp_servers.justcrawl] block to ~/.codex/config.toml. Loaded by every session. | You scrape often. Default choice. | | Per-session | Keep the block commented out in config.toml; uncomment + relaunch only for sessions where you want it. | You only want the tools in specific sessions. |

The snippet below sets up the persistent path; the per-session toggle is documented further down.

Configure

Open ~/.codex/config.toml. Create it if it doesn't exist:
Terminal window
```
mkdir -p ~/.codex && touch ~/.codex/config.toml
```

Add the justcrawl MCP server block. Append to the file:

[mcp_servers.justcrawl]
command = "npx"
args = ["-y", "@justcrawl/mcp-server"]

[mcp_servers.justcrawl.env]
JUSTCRAWL_API_KEY = "sr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Replace sr_live_xxxxx… with your real key.

Start (or restart) a Codex session. MCP servers are spawned at session start, so quit any running codex and re-launch:
Terminal window
```
codex
```
Confirm it's wired. Inside the session, type /mcp (or whatever the version's MCP inspection command is — codex --help lists it). You should see justcrawl listed as connected with the discovered tool count.

First prompt to try

Inside a Codex session:

List my justcrawl workflows.

Codex calls jc_workflows_list() and renders the result. If you see the workflows from your dashboard, you're done.

Per-session enable / disable

If you'd rather opt-in per session instead of having justcrawl loaded always, comment the block out in ~/.codex/config.toml and uncomment it before the sessions where you want it. The cleanest pattern is to keep two config snippets in a scratch note and swap them in:

# Justcrawl MCP server — uncomment to enable this session.
# [mcp_servers.justcrawl]
# command = "npx"
# args = ["-y", "@justcrawl/mcp-server"]
#
# [mcp_servers.justcrawl.env]
# JUSTCRAWL_API_KEY = "sr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Codex re-reads config.toml on every session start, so a quick uncomment + relaunch is all it takes.

Using an env var instead of a literal key

Don't want the plaintext key in config.toml? Drop the .env block and export the variable in your shell rc instead:

[mcp_servers.justcrawl]
command = "npx"
args = ["-y", "@justcrawl/mcp-server"]

# In ~/.zshrc or ~/.bashrc
export JUSTCRAWL_API_KEY="sr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

The MCP server picks up JUSTCRAWL_API_KEY from the inherited environment.

Troubleshooting

justcrawl doesn't show up in /mcp. TOML parse errors are silently dropped by some Codex versions. Run codex --debug (or your version's verbose flag) and re-launch; the parse error surfaces in stderr. A trailing comma or missing quote in config.toml is the usual culprit.

command not found: npx. Node.js isn't on the PATH Codex sees. On macOS, install Node via the official installer (not nvm) so it lands in /usr/local/bin. Re-launch your shell, then codex.

401 unauthorized in the MCP stderr panel. The API key is malformed or revoked. Generate a fresh one in the dashboard and update config.toml (or the env var).

Stderr shows npm error 404 Not Found - GET https://registry.npmjs.org/@justcrawl%2Fmcp-server. The package isn't published yet (Phase 3). Your config is correct — relaunch a Codex session after the package lands and the same TOML block will spawn the real server.