starlens/ mcp

stardata for Claude Code / Codex — the MCP

claude mcp add stardata -e STARLENS_API_KEY=sk-lens-… -- uvx stardata-mcp

One line, nothing to install first (uvx fetches and runs the server). Your coding agent gains a compress-before-you-send tool: when it's about to hand a screenshot to its model, it calls compress_image first — the image comes back smaller with a sealed certificate that the model still reads it the same, or a certified refusal (send the original, no charge) when it can't shrink safely. You pay a share of the tokens it proves it saved.

1. Get a key

Sign in at https://api.s2ar.dev/app — we email you a sign-in code, no password — then click Create API key. The setup blocks on that page come pre-filled with your key; first tries are free in the browser.

2. Add it to your agent

Claude Code: the one-liner at the top of this page.

Codex (~/.codex/config.toml):

[mcp_servers.stardata]
command = "uvx"
args = ["stardata-mcp"]
env = { STARLENS_API_KEY = "sk-lens-…", STARLENS_TARGET = "claude-sonnet-4-6" }

Any MCP-capable client works — it speaks stdio MCP.

No uv? Install the package and point at the console script instead:

pip install stardata-mcp          # or: pip install 'starlens[mcp]'
claude mcp add stardata -e STARLENS_API_KEY=sk-lens-… -- stardata-mcp

Both packages are on PyPI (published from the staros-stardata account): stardata-mcp is the one-install umbrella, starlens the engine. A self-hosted mirror of the wheels also serves at https://s2ar.dev/starlens/dist/ if PyPI is unreachable:

pip install "starlens[mcp] @ https://s2ar.dev/starlens/dist/starlens-0.1.0-py3-none-any.whl"

(needs pip ≥ 20.1; the deploy output of tools/release.py prints the URL with its #sha256= fragment so pip verifies the download.)

Tools it exposes

tool what it does
compress_image(image_path, target_model="") compress a file for a target model; writes <name>.lens.<fmt> beside it (or reports a certified refusal), returns savings + the sealed hash
compress_images(image_paths, target_model="") batch of up to 20 — one line per file + an aggregate footer; refusals and per-file errors don't stop the batch
estimate_image_tokens(image_path, provider="anthropic") free, local, no key — what the image bills as-is per provider; use it to skip images already near the token floor
verify(record_sha256) re-verify any certificate seal
account_balance() prepaid balance + this cycle's savings receipt

What a success looks like:

Compressed 2560×1440 → 827×465 for claude-sonnet-4-6: saved 1020 tokens (67% off), witness verdict isomorphic. Wrote shot.lens.webp. Sealed 56dccb31… — verify at …/v1/verify/56dccb31…

And a certified refusal:

Certified refusal: this image can't be compressed without changing what the model reads — send the original (no charge).

Failures come back as one-line explanations with the fix (starlens error (credit): prepaid balance empty (402) — add credits: …), never tracebacks.

The CLI

The same verbs work from a shell (installed alongside the server):

starlens compress shot.png --target claude-sonnet-4-6   # or many files
starlens estimate shot.png              # local, free, keyless
starlens verify <record_sha256>
starlens balance

starlens compress --json emits the raw result dicts for scripting.

Config (env)

var default
STARLENS_API_KEY — (required, except estimate)
STARLENS_BASE_URL https://api.s2ar.dev/v1
STARLENS_TARGET claude-sonnet-4-6
STARLENS_TIMEOUT 180 (seconds per request)

Which integration do I want?

python import httpx, openai from starlens.integrations.openrouter import CompressingTransport client = openai.OpenAI(http_client=httpx.Client(transport=CompressingTransport(mode="fidelity")))

Or preprocess a message list explicitly with compress_messages(...). - POST /v1/certify — you already compressed the image yourself and want the certificate auditing that choice (send original + compressed, get the verdict). A curl away; no MCP tool needed.

Same certificate, same savings-share billing on all three.

Troubleshooting