> ## Documentation Index
> Fetch the complete documentation index at: https://jdcodec.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Install the connector, get an API key, see your first compression event. ~5 minutes.
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](https://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
```bash theme={null}
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.
```bash theme={null}
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 ` in place of `jdcodec ` anywhere in this guide — npx resolves the binary without a global install.
* Or check `npm config get prefix`, ensure `/bin` is in your `$PATH`, then re-run `npm install -g jdcodec`.
## 2. Get an API key
```bash theme={null}
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](/docs/api-reference) and [Concepts](/docs/concepts/what-is-jdcodec).
## 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`:
```json theme={null}
{
"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:
```bash theme={null}
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 `hello@jdcodec.com` 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 `, which wires both servers into your AI client. The four supported clients are listed below; pick yours.
```bash theme={null}
jdcodec setup claude-code
```
This runs `claude mcp add ...` for both servers. Equivalent manual commands if you'd rather copy-paste:
```bash theme={null}
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.
```bash theme={null}
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](https://docs.cursor.com/context/model-context-protocol):
* `jdcodec` — `command: jdcodec` (stdio)
* `jdcodec-docs` — `url: https://jdcodec.com/docs/mcp` (HTTP)
```bash theme={null}
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](https://docs.windsurf.com/windsurf/cascade/mcp). Register the two servers:
* `jdcodec` — `command: jdcodec` (stdio)
* `jdcodec-docs` — `url: https://jdcodec.com/docs/mcp` (HTTP)
```bash theme={null}
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:
```bash theme={null}
npx jdcodec setup vscode
```
Runs `code --add-mcp '...'` for both servers. Equivalent manual commands if you'd rather copy-paste:
```bash theme={null}
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](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) 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)**):
```json theme={null}
"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](#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](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally). |
| `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 `hello@jdcodec.com` 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
The unit framing the API uses — and what each one means for your usage.
What's redacted, what's persisted, what the cloud never sees.
The full surface — endpoints, schemas, error codes.
Stuck? Reply to your waitlist email or reach out at [hello@jdcodec.com](mailto:hello@jdcodec.com).