Frequently asked questions

Yes — Claude Code is the primary supported client. In the shell where you run claude:

export ANTHROPIC_API_KEY=sk-ant-api03-...
export ANTHROPIC_BASE_URL=http://127.0.0.1:7777
tokenshield up --daemon
tokenshield run -- claude

The tokenshield run wrapper invokes claude --bare, which strictly uses your API key (bypasses any cached OAuth from a prior claude login).

Yes — all four honor a custom base URL when configured for the Anthropic API.

• • Cursor: Settings → Models → Override OpenAI Base URL → set to http://127.0.0.1:7777
• • Windsurf: Settings → AI Provider → Custom endpoint
• • Zed: Settings → Assistant → custom base URL
• • Aider: aider --anthropic-api-base http://127.0.0.1:7777

tokenshield integrations show prints the exact copy-paste snippet for every tool.

No. Two reasons it can't and won't:

1. Claude Desktop hardcodes the endpoint to api.anthropic.com and authenticates via OAuth tied to your claude.ai login. There's no way to point it at a local proxy.
2. Pro ($20/mo) and Max ($200/mo) plans are flat subscriptions — Anthropic doesn't bill per token in those flows. Even if we could route the traffic, there's no dollar lever to pull.

TokenShield's customer is the team that has graduated to API-billed developer tooling (Claude Code, Cursor, Windsurf, the SDK in production) and watches a metered Anthropic invoice climb each month.

Yes — both SDKs honor ANTHROPIC_BASE_URL out of the box. Any production app or batch job built on the SDK works with no code changes.

Not yet. The provider adapter interface is in the codebase (src/providers/types.ts), but we ship one provider correctly before claiming three.

• ✅ Anthropic — live in v1.x
• 🕒 OpenAI — targeted for v1.1 (chat completions + assistants)
• 🕒 Google Gemini — targeted for v1.2

Join the waitlist for the provider you need most — signal weight directly informs which ships first.

No. The proxy reads it from your shell environment and forwards it as an x-api-key header on each outbound request to Anthropic. We never receive it, log it, or persist it. The CuratedMCP servers don't have a code path that could touch it.

No. Prompt and response bodies are processed entirely in the local Node process. Even if you enable cloud telemetry, only aggregate counters are sent (request count, total bytes, total dollars, top model used). The server-side ingest schema explicitly rejects any field whose name suggests content (prompt, message, content, text, body, args).

Yes — MIT licensed.

• Proxy core + CLI: github.com/oneprofile-dev/tokenshield
• npm package: @curatedmcp/tokenshield
• Run tokenshield telemetry show to see the exact JSON schema sent to our servers (with a sample payload).

A SQLite ledger at ~/.tokenshield/ledger.db with per-request rows: timestamp, model, endpoint, token counts, duration, status, dollar cost. No prompt or response content. Default retention is 7 days, configurable via --retention-days.

No. The proxy runs as your local user. If your employer has separate network monitoring or endpoint logging, that's outside TokenShield's scope. The Enterprise tier offers an opt-in private registry for centralized policy, but it still never captures prompt content.

The current processor is conversation-dedup. It hashes every tool_result content block per-conversation. On the second and subsequent appearances of identical content within the same conversation, the content is replaced with a deterministic 60-byte pointer stub. The model sees the same tool_use_id reference (so semantics are preserved); Anthropic counts fewer input tokens, you pay less. Conservative threshold: only payloads >= 256 bytes are eligible.

Yes — by design. Compression is deterministic: the same input always produces the same output, so the cache key Anthropic computes stays stable. We don't strip cache_control headers and don't touch system prompts or first-user messages (the typical cache anchors). In one of our recorded fixtures, dedup and prompt-cache co-existed with no measurable cache-hit-rate degradation.

No. We preserve tool_use_id verbatim on every stub. The pointer payload references the prior message index AND the original toolUseId, so the model has full traceability if it needs it (in practice it almost never does — the model treats stubs as 'I already saw this').

Hashing tool_results on the outbound path adds < 2ms p99 for typical conversations. The proxy is byte-faithful on response streams (SSE bytes are passed through unchanged, accumulator runs on a copy). First-token-time is essentially unchanged.

No. Response streams pass through byte-for-byte. The accounting layer parses a copy of the SSE events to extract usage tokens, but the bytes you receive are identical to what Anthropic sent. Compression is exclusively on the outbound request path.

It replays recorded sessions through the dedup pipeline locally, with no network calls, and reports the request-payload bytes removed on each — light (Q&A, no tool use) shows ~0% because there's nothing to dedup, while tool-heavy sessions show more. Treat the bundled-fixture numbers as a directional demo of the mechanism, not a forecast of your bill: the bytes removed are not the same as billed-token savings, especially on prompt-cached workloads where the repeats are already discounted. The honest figure is the one the ledger records on your own traffic — run it for a week and read it there.

Those are LLM gateways — they route requests across providers and log responses. They don't modify the wire payload of a request. TokenShield specifically rewrites tool_result content before it leaves your machine to dedupe within a conversation. Different layer of the stack. You can run TokenShield in front of LiteLLM if you want both routing and compression.

Prompt cache works at request boundaries — it can't dedup across a conversation when the same tool_result appears at messages 3, 7, and 11. Dedup composes with prompt cache, not against it. Our stubs are deterministic so cache keys stay stable.

Cloudflare AI Gateway is a hosted reverse proxy with logging, rate limiting, and caching at the response level. TokenShield runs locally, never sends prompts off-machine, and modifies the request body to dedupe redundant content. If privacy posture or zero-network-dependency matters, TokenShield is the answer; if you want hosted observability across multiple providers, AI Gateway is a different tool.

Yes. The free tier includes the proxy, local dashboard, ledger, every diagnostic tool, and the measurement pipeline. It will always be free. Paid tiers unlock cloud sync, multi-machine views, and active processors as they ship.

Cloud dashboard at curatedmcp.com/tokenshield/dashboard with cross-machine view, multi-machine license sync, the opt-in optimization processors (conversation-dedup, response-cache, diff-file-reads as they ship), founding-rate price lock, and email support. Free tier keeps full local measurement; Pro adds the cloud dashboard and the optimization layer you measure against your own baseline.

$199/mo flat (no setup fee) for the first 10 engineering teams. Includes white-glove install (Zoom + Slack), a shared per-engineer/per-project spend dashboard, weekly CFO-ready reports, dedicated support channel, and every optimization processor as it ships. Cancel anytime, 30-day money-back. Locked at $199/mo forever even after retail per-seat pricing rises.

Not in v1. The cloud dashboard is curatedmcp.com-hosted; the local dashboard at localhost:7778 always works. Enterprise pilots can request an isolated deployment — email [email protected].

response-cache (LRU+TTL keyed on model + system_prompt_hash + last_user_message_hash, scoped to deterministic temperature=0 calls), diff-file-reads (replace unchanged file re-reads with a tiny diff against the prior version), and stream-early-stop (detect end-of-turn patterns in streaming output and signal the model to wrap up). Roadmap is public and reorders based on which signals correlate best with measured savings.

It depends entirely on workload shape, and we won't quote a percentage your own bill might not back up. Light Q&A has little to dedup. On prompt-cached workloads — Claude Code's default — much of the repeated context is already discounted by Anthropic, so the deduplication win can be small. Coding sessions with lots of file re-reads have more headroom (the diff-reads processor, on the roadmap, targets exactly that). The honest answer is: the ledger is free, run it for a week with the processors on in diff-mode, and read your real number off your own data. We measure, we don't promise.

Hosted SaaS proxy variant. SOC 2 / BAA. Charging a percentage of measured savings (we charge flat per-seat — no usage-based pricing games). Speculative execution. Per-tool field pruning. These are v2 candidates only after we ship v1.x to scale and learn what's actually needed.