Skip to main content

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.

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 jdcodec
Both paths land on the same connector binary. Pick whichever fits your project’s existing tooling — they’re equivalent at runtime.

​
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. You’ll receive an API key by email once your slot is provisioned. 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. Set it as an environment variable on the machine where you’ll run your AI agent: 
export JDC_API_KEY="jdck_yourid.yoursecret"
Or write it to ~/.jdcodec/config.json: 
{
  "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 — the local stdio connector you just installed. Routes your agent’s browser-snapshot calls through JD Codec.
  • jdcodec-docs — 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. 
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.
If you only want one of the two servers, pass --no-docs (connector only) or --no-connector (docs only) to any of the commands above.

​
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.
SymptomLikely causeFix
command not found: jdcodec after installNode binary not on PATH, or the global install went to a non-PATH directoryCheck node --version returns 22+. Don’t use sudo npm install -g. If npm config get prefix returns a path you can’t write to, follow npm’s official guide for fixing global install permissions.
jdcodec start opens the browser but nothing happens afterThe session_id never reaches the server; usually a network or DNS issueCheck connectivity to jdcodec.com. Try again; the connector retries gracefully.
Agent runs but no compression visibleAPI key not configured, or pasted as jdck_id only without the secret halfVerify 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 clientClient didn’t pick up the new MCP serverQuit 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 startRead-only home directory, or the connector exited before persistingConfirm 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_missingEdge case — the connector’s Privacy Shield audit signal isn’t reaching the cloudThis 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].