Quickstart - JD Codec

This guide gets you from zero to a working JD Codec setup that’s compressing browser snapshots inside your AI agent. If you have any AI client that speaks the Model Context Protocol (Claude Code, Cursor, Windsurf, or similar), this is your fastest path.

Prerequisites

Node.js 22 or newer (node --version to check). Install from nodejs.org if needed.
An AI client that can register MCP servers. The examples below use Claude Code; the wiring step adapts cleanly to Cursor, Windsurf, and other MCP-capable clients.
macOS or Linux. Windows support is on the roadmap.

1. Install the connector

npm install -g jdcodec

The -g flag installs the jdcodec binary globally so it’s available on your PATH. Without it, the binary lands inside a local node_modules/.bin/ and won’t be found by your shell or your AI client.

pip install jdcodec

The Python package is a thin wrapper. It still requires Node.js 22+ on your PATH because the underlying connector is a TypeScript binary.

Both paths land on the same connector binary. Pick whichever fits your project’s existing tooling — they’re equivalent at runtime.

jdcodec not found after installing? This is common if you use nvm (switching Node versions loses globals from other versions) or if your npm global prefix isn’t on your PATH. Two options:

Run npx jdcodec <command> in place of jdcodec <command> anywhere in this guide — npx resolves the binary without a global install.
Or check npm config get prefix, ensure <prefix>/bin is in your $PATH, then re-run npm install -g jdcodec.

2. Get an API key

jdcodec start

This opens a browser tab to authenticate, joins you to the early-access waitlist, and surfaces your stable Machine ID. A confirmation email arrives in your inbox immediately. You’ll receive a second email with your API key once your slot is provisioned.

Provisioning is currently manual during early access — expect your key within ~24 hours of registration. You can complete Step 4 (wire MCP into your client) ahead of the key arriving, but the connector will not start without it, so the jdcodec MCP server will appear inactive in your AI client until you finish Step 3.

While you wait, you can explore the API Reference and Concepts.

3. Configure the API key

Your API key is two parts joined by a dot:

jdck_9f3a2b7c8d1e4f05.BASE32URL_SECRET

api_key_id — everything before the dot (jdck_9f3a2b7c8d1e4f05 in the example above). Always starts with jdck_. This half is public — safe to log, paste in dashboards, and quote in support tickets. We use it to look up your key.
api_key_secret — everything after the dot (BASE32URL_SECRET in the example above). This half is secret — never log it, never share it, never commit it to a repo. We only ever store its hash, never the value.

The connector takes both parts together as a single bearer. Write it to ~/.jdcodec/config.json:

{
  "api_key": "jdck_yourid.yoursecret"
}

The config file is the right choice for MCP use. AI clients (Claude Code, the Claude VS Code extension, Cursor, Windsurf, VS Code) launch the connector themselves and inherit your system environment, not your terminal session — a key set with export JDC_API_KEY=... in your shell will be invisible to the connector when it’s spawned by your AI client. Use the config file unless you’re calling jdcodec directly from a shell script in the same terminal.

For terminal-only use (e.g. calling jdcodec directly from the same shell where you set it), an environment variable also works:

export JDC_API_KEY="jdck_yourid.yoursecret"

The connector reads from the environment variable first, then falls back to the config file.

If you accidentally commit the full key to a repo or paste it in a public channel, treat it as compromised — email [email protected] to revoke it and we’ll issue a new one. The api_key_id half alone is not sensitive; only the combined id.secret bearer needs that treatment.

4. Wire it to your AI client

JD Codec exposes two MCP servers that you’ll typically register together:

jdcodec (required) — the local stdio connector you just installed. Routes your agent’s browser-snapshot calls through JD Codec.
jdcodec-docs (optional) — an HTTP MCP server at https://jdcodec.com/docs/mcp. Lets your agent answer questions like “how does pass-through work?” by querying the live docs instead of its training data.

The fastest path is jdcodec setup <client>, which wires both servers into your AI client. The four supported clients are listed below; pick yours.

Claude Code
Cursor
Windsurf
VS Code (Copilot)

jdcodec setup claude-code

This runs claude mcp add ... for both servers. Equivalent manual commands if you’d rather copy-paste:

claude mcp add --scope user jdcodec -- jdcodec
claude mcp add --transport http jdcodec-docs https://jdcodec.com/docs/mcp

Restart Claude Code. The jdcodec and jdcodec-docs MCP servers appear in your tools list.Also covers the Claude VS Code extension. Both the Claude Code CLI (terminal) and Anthropic’s Claude VS Code extension read MCP servers from ~/.claude.json, so this same command wires both. If you’re using Claude inside VS Code, pick this tab — not the “VS Code (Copilot)” tab below.jdcodec setup claude-vscode is an alias of jdcodec setup claude-code — same command, same flow, different name for users who think of themselves as “running Claude in VS Code.” Use whichever feels natural.

jdcodec setup cursor

Cursor doesn’t ship a CLI for MCP registration, so the command prints what to add and where. Open ~/.cursor/mcp.json (create it if it doesn’t exist) and register the two servers per Cursor’s MCP guide:

jdcodec — command: jdcodec (stdio)
jdcodec-docs — url: https://jdcodec.com/docs/mcp (HTTP)

jdcodec setup windsurf

Open ~/.codeium/windsurf/mcp_config.json (create it if it doesn’t exist), or use Settings > Tools > Windsurf Settings > Add Server in the GUI. See Windsurf’s MCP guide. Register the two servers:

jdcodec — command: jdcodec (stdio)
jdcodec-docs — url: https://jdcodec.com/docs/mcp (HTTP)

jdcodec setup vscode

Wires the two MCP servers into VS Code’s native Copilot agent and any other extension that reads VS Code’s mcp.json. Using Anthropic’s Claude VS Code extension instead? Pick the Claude Code tab — the Claude extension reads ~/.claude.json, not VS Code’s mcp.json, so this tab is the wrong target for it.If jdcodec isn’t on your PATH yet, use npx instead:

npx jdcodec setup vscode

Runs code --add-mcp '...' for both servers. Equivalent manual commands if you’d rather copy-paste:

code --add-mcp '{"name":"jdcodec","command":"jdcodec"}'
code --add-mcp '{"name":"jdcodec-docs","type":"http","url":"https://jdcodec.com/docs/mcp"}'

Requires VS Code 1.94+ and the code shell command on your PATH. If code isn’t on PATH, run “Shell Command: Install ‘code’ command in PATH” from the Command Palette in VS Code first. See VS Code’s MCP guide for the underlying JSON schema.

Disable VS Code’s built-in browser tools. VS Code ships its own browser tool surface (introduced in VS Code 1.110) that runs independently of JD Codec. When both are active, the Copilot agent routes navigation through VS Code’s browser and snapshots through JD Codec’s — two separate browser sessions that have never shared a page. The result: JD Codec’s snapshot sees a blank page, compression is silently skipped, and your agent still completes the task via the uncompressed fallback. You won’t notice unless you check the logs.Add this to your VS Code user settings (Cmd+Shift+P → Open User Settings (JSON)):

"workbench.browser.enableChatTools": false

This disables VS Code’s built-in browser tools and routes all browser activity through JD Codec. The setting persists across restarts — you only need to do it once. Restart VS Code after adding it.

The docs server is optional. Pass --no-docs to skip it — the connector works fully without it.

How to know it worked

After restarting your AI client, ask it to list its available tools (or check the MCP tools panel in your client UI). You should see browser-automation tools appear — names like browser_snapshot, browser_click, browser_type, etc. Those tools are now flowing through JD Codec. If you don’t see them, your client probably hasn’t picked up the new MCP server. Quit and restart it; if that doesn’t work, run jdcodec doctor to diagnose, or jump to the Troubleshooting section below.

5. Run a task and watch compression land

Ask your agent to do anything browser-shaped:

Open the Hacker News front page and tell me the top story.

Behind the scenes, your agent’s browser_snapshot calls now route through JD Codec. Every snapshot is redacted on your machine, compressed in the cloud, and the smaller representation is what your agent reads.

What just happened?

Your first snapshot is a keyframe — the full DOM/ARIA state.
Every subsequent snapshot is a delta — just the references and values that changed.
PII never leaves your machine. The Privacy Shield ran on every snapshot before the cloud saw it.
Pass-through kicks in automatically on snapshots where compression wouldn’t help (large table dumps, full-text scans).

Troubleshooting

The most common failures and what to check, in rough order of frequency.

Symptom	Likely cause	Fix
`command not found: jdcodec` after install	npm global bin not on PATH, or nvm version switch lost the global	Use `npx jdcodec` as an immediate workaround. To fix permanently: check `node --version` returns 22+, confirm `npm config get prefix` gives a path whose `bin/` is in `$PATH`, and re-run `npm install -g jdcodec`. Don’t use `sudo npm install -g`. If the prefix isn’t writable, follow npm’s official guide for fixing global install permissions.
`jdcodec start` opens the browser but nothing happens after	The session_id never reaches the server; usually a network or DNS issue	Check connectivity to `jdcodec.com`. Try again; the connector retries gracefully.
Agent runs but no compression visible	API key not configured, or pasted as `jdck_id` only without the secret half	Verify your key has the `jdck_id.secret` shape (two parts joined by a dot). Re-export `JDC_API_KEY` and restart your agent.
MCP tools don’t appear in your AI client	Client didn’t pick up the new MCP server	Quit the client fully and restart. Some clients require a full app quit, not just a window close.
`~/.jdcodec/machine-id` doesn’t exist after `jdcodec start`	Read-only home directory, or the connector exited before persisting	Confirm your home directory is writable. The Machine ID still works in-process, but won’t survive across restarts until the file persists.
Errors mention `privacy_shield_missing`	Edge case — the connector’s Privacy Shield audit signal isn’t reaching the cloud	This is a connector bug. Email `[email protected]` with the request_id from the error and we’ll investigate.

Run jdcodec doctor to check Node version, npx availability, your config file, your API key shape, and a live cloud-auth probe in one pass. Each failure links to the relevant docs.

Next steps

Sessions, tasks, steps

The unit framing the API uses — and what each one means for your usage.

Privacy posture

What’s redacted, what’s persisted, what the cloud never sees.

API Reference

The full surface — endpoints, schemas, error codes.

Get help

Stuck? Reply to your waitlist email or reach out at [email protected].

​Prerequisites

​1. Install the connector

​2. Get an API key

​3. Configure the API key

​4. Wire it to your AI client

​How to know it worked

​5. Run a task and watch compression land

​What just happened?

​Troubleshooting

​Next steps

Sessions, tasks, steps

Privacy posture

API Reference

Get help

Prerequisites

1. Install the connector

2. Get an API key

3. Configure the API key

4. Wire it to your AI client

How to know it worked

5. Run a task and watch compression land

What just happened?

Troubleshooting

Next steps