# TokenSafe (pypi · tokensafe)

Your AI agent is smart enough to code all day. Local firewall & zero-loss runtime.

- Trust score: 57/100 (low)
- Change this week: +3
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-21

## Components

- remote · `api.tokensafe.dev`: 65/100, [markdown](https://verifymcp.io/servers/dev-tokensafe-tokensafe/api.md), [page](https://verifymcp.io/servers/dev-tokensafe-tokensafe/api)
- npm · `tokensafe`: 29/100, [markdown](https://verifymcp.io/servers/dev-tokensafe-tokensafe/tokensafe.md), [page](https://verifymcp.io/servers/dev-tokensafe-tokensafe/tokensafe)
- pypi · `tokensafe`: 57/100 (this document), [markdown](https://verifymcp.io/servers/dev-tokensafe-tokensafe/tokensafe-2.md), [page](https://verifymcp.io/servers/dev-tokensafe-tokensafe/tokensafe-2)

## Channel facts

- Registry: `pypi`
- Package: `tokensafe`
- Version: `4.3.3`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-21.

- **Supply Chain Security**: 49/100
  - Malware scan not yet available for this package.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs setuptools.build_meta at install time, a recognised build step with no custom scripting around it.
  - 3 of 19 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 48/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 0 days ago).
  - Publishes a security disclosure policy (SECURITY.md).
- **Schema Quality & AI Usability**: 74/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 1968 tokens (~109/item across 18 items; 18 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 33/100
  - Stability observed for 10 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - We read all 18 captured tool definition(s), and no name or description among them implies an irreversible operation.
  - An AI judge read all 18 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 20/100
  - Spec-recency check failed: implements MCP spec 2024-11-05; the latest is 2026-07-28.

## Install

### How do I install the TokenSafe MCP server?

TokenSafe runs locally as a PyPI package, launched with uvx tokensafe mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add dev-tokensafe-tokensafe -- uvx tokensafe mcp
```

### Cursor

```json
{
  "mcpServers": {
    "dev-tokensafe-tokensafe": {
      "command": "uvx",
      "args": [
        "tokensafe",
        "mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "dev-tokensafe-tokensafe": {
      "command": "uvx",
      "args": [
        "tokensafe",
        "mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add dev-tokensafe-tokensafe -- uvx tokensafe mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "dev-tokensafe-tokensafe": {
      "type": "local",
      "command": [
        "uvx",
        "tokensafe",
        "mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add dev-tokensafe-tokensafe --command uvx --arg tokensafe --arg mcp
```

### Hermes

```yaml
mcp_servers:
  dev-tokensafe-tokensafe:
    command: "uvx"
    args: ["tokensafe", "mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "dev-tokensafe-tokensafe": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "tokensafe",
        "mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add dev-tokensafe-tokensafe -t stdio -c uvx -a tokensafe mcp
```

### Other

```json
{
  "mcpServers": {
    "dev-tokensafe-tokensafe": {
      "command": "uvx",
      "args": [
        "tokensafe",
        "mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-21 (score 57, −15)

- [security regression] Malware scan: pass → unverified
- [functional] Package version: 4.3.1 → 4.3.3
- [functional] Package version: 4.3.1 → 4.3.2

### 2026-11-20 (score 72, +16)

- [security improvement] Malware scan: unverified → pass
- [functional] Package version: 4.2.13 → 4.3.1

### 2026-11-19 (score 56, 0)

- [security regression] Provenance: fail → unverified
- [functional] Package version: 4.2.10 → 4.2.13
- [functional] Package version: 4.2.10 → 4.2.12
- [functional] Package version: 4.2.10 → 4.2.11

### 2026-11-18 (score 56, +1)

- [functional] Package version: 1.8.0 → 4.2.10
- [functional] Package version: 4.2.4 → 4.2.9
- [functional] Package version: 4.2.4 → 4.2.8
- [functional] Package version: 4.2.4 → 4.2.7
- [functional] Package version: 4.2.4 → 4.2.6
- [functional] Package version: 4.2.4 → 4.2.5

### 2026-11-17 (score 55, 0)

- [security improvement] Malware scan: unverified → pass
- [functional regression] Schema quality: pass → fail
- [functional] Package version: 4.1.6 → 4.2.4
- [functional] Package version: 4.1.6 → 4.2.3
- [functional] Package version: 4.1.6 → 4.2.1
- [functional] Package version: 4.1.6 → 4.2.0
- [functional] Package version: 4.1.6 → 4.1.13
- [functional] Package version: 4.1.6 → 4.1.12
- [functional] Package version: 4.1.6 → 4.1.10
- [functional] Package version: 4.1.6 → 4.1.7

### 2026-11-16 (score 55, +1)

- [functional regression] Dependency health: 1.00 → 0.91
- [functional improvement] Schema quality: fail → pass
- [functional] Package version: 3.2.0 → 4.1.6
- [functional] Package version: 3.2.0 → 4.1.5
- [functional] Package version: 3.2.0 → 4.1.3
- [functional] Package version: 3.2.0 → 4.1.2
- [functional] Package version: 3.2.0 → 4.1.0

### 2026-11-15 (score 54, 0)

- [functional] Package version: 3.1.5 → 3.2.0

### 2026-11-14 (score 54, 0)

- [security regression] Provenance: fail → unverified
- [security improvement] Malware scan: unverified → pass
- [functional] Package version: 3.0.0 → 3.1.5
- [functional] Package version: 1.8.0 → 3.1.4
- [functional] Package version: 3.0.0 → 3.1.3
- [functional] Package version: 3.0.0 → 3.1.2
- [functional] Package version: 3.0.0 → 3.1.1
- [functional] Package version: 3.0.0 → 3.0.1

## MCP tools (18)

### `smart_read_file` (~218 tokens)

AST-skeleton file reader: keeps the target function/class body + 1-line 1-hop dependency signatures, folds inert code (-90-99% tokens). Relative or absolute paths. Schema files (OpenAPI/Prisma/GraphQL/SQL) auto-slice via 'symbol'. For 3+ related symbols use smart_bundle instead.

Input parameters:

- `dep_mode` (string): 'signature' (default) = 1-line dep signatures; 'full' = inline dependency bodies
- `end_line` (integer): Optional: ending line number
- `force_full` (boolean): Bypass pointer dedup — use only after context compaction or as a fresh subagent
- `include_deps` (boolean): Include 1-hop dependency signatures (default true)
- `path` (string, required): File path (relative to workspace or absolute)
- `start_line` (integer): Optional: starting line number
- `symbol` (string): Optional: function/method/class/component or schema model/type/table to extract (omit for whole-file skeleton)

### `smart_bundle` (~131 tokens)

Reads 2-8 related symbols across files as ONE merged bundle: per-file skeletons, deduplicated shared imports, merged 1-hop dep signatures. Replaces 3+ separate smart_read_file calls in a single roundtrip.

Input parameters:

- `dep_mode` (string): Parity only; bundles always merge signatures
- `force_full` (boolean): Bypass session pointer dedup
- `include_deps` (boolean): Include merged 1-hop dep signatures (default true)
- `targets` (array, required): Up to 8 {path, symbol} targets; several symbols of one file = separate entries

### `get_architecture_graph` (~82 tokens)

Returns top architectural God Nodes and dependency topology for the target project in < 250 tokens without file crawling. Call this BEFORE reading files or searching.

Input parameters:

- `project_path` (string): Target project root directory. IMPORTANT: Always pass the absolute directory path (e.g. '/path/to/repo') when working in multi-workspace setups or repositories outside CWD.

### `get_api_surface` (~75 tokens)

Generates and returns a compact markdown map of all exported interfaces, classes, and types in the project without crawling files.

Input parameters:

- `project_path` (string): Target project root directory. IMPORTANT: Always pass the absolute directory path (e.g. '/path/to/repo') when working in multi-workspace setups or repositories outside CWD.

### `compress_prompt` (~44 tokens)

Compresses a verbose developer prompt into an ultra-dense TOCP S-Expression via DeepSeek-V3 / Regex.

Input parameters:

- `prompt` (string, required): Natural language request from developer

### `context_budget` (~163 tokens)

Context Budget HUD & Context Quality Score (Grade S/A/B/C/F): estimates context window usage, headroom %, static tool/skill tax, and outputs a unified health grade. Call before large multi-step tasks. When warning/critical or Grade C/F, call tokensafe:compact_conversation.

Input parameters:

- `model` (string): Optional: model name to resolve window size (default: env TOKENSAFE_CONTEXT_WINDOW or 200k)
- `session_id` (string): Optional: session identifier (default: mcp_session)
- `transcript_path` (string): Optional: path to the session JSONL transcript; when provided, REAL history mass is measured instead of the instrumented floor (recommended)
- `window_tokens` (integer): Optional: explicit context window size in tokens

### `compact_conversation` (~112 tokens)

On-demand context compaction: folds a long agent conversation transcript into a Consolidated State Ledger with a 3-line Post-Compaction Orientation Digest (Active Goal, Last State, Next Focus) so the agent immediately resumes without losing flow. Use when context_budget reports warning/critical or Grade C/F.

Input parameters:

- `invocation_num` (integer): Optional: current turn number (default 3; folding requires >= 3 turns)
- `transcript_path` (string, required): Path to the JSONL transcript of the current session

### `sanitize_command` (~223 tokens)

Per-stage shell command rewrites: prunes lockfiles, caps unbounded git log/show/blame/rg and docker/kubectl logs, strips git push progress animations (--no-progress), wraps git commit with tokensafe wrap when pre-commit/husky hooks exist, and quiets npm/pip installs, bounds cat/curl output. Compound commands (a && b ; c) are optimized per stage without breaking operators. Test commands (bun test, pytest, python -m unittest, vitest, jest) are automatically wrapped or forced into run-once mode (CI=true, --watch=false, --forceExit) so passing suites emit a clean 1-line summary and agents never hang on watch mode. Pass optional cwd for test commands to unlock package.json runner detection for opaque yarn/npm test scripts.

Input parameters:

- `cmd` (string): Alias for command
- `command` (string): Raw bash command line
- `cwd` (string): Optional working directory the command will run in; enables the package.json peek that identifies the runner behind opaque yarn/npm test scripts

### `slice_diff` (~59 tokens)

Slices unified diffs, omitting lockfiles and minimizing context lines to reduce tokens by up to 80%.

Input parameters:

- `diff` (string, required): Raw git diff text
- `max_context` (integer): Maximum surrounding context lines (default: 2)

### `get_token_savings_metrics` (~19 tokens)

Returns cumulative token and cost savings analytics.

### `guard_inspect` (~136 tokens)

Pre-flight security & hygiene audit for commands or code snippets. Detects secret leaks, SQL injection, TLS bypass (incl. git-level), CORS wildcard, destructive commands, raw grep, in-place stream editing (sed -i, perl -i), and never-terminating streams (tail -f, watch, docker attach).

Input parameters:

- `cmd` (string): Alias for command
- `code` (string): Optional: Code snippet, replacement diff, or file content to audit
- `command` (string): Optional: Terminal command line to audit
- `file_path` (string): Optional: File path being written or modified

### `list_dir` (~123 tokens)

Returns a clean, token-efficient directory tree up to depth N without permissions, timestamps, or ignored folders (node_modules, .git, dist, .env). Replaces verbose ls -la. Pass '.' for project root or a subfolder like 'src'.

Input parameters:

- `depth` (integer): Maximum traversal depth (default: 2, max: 4)
- `max_entries` (integer): Maximum entries to display before pruning (default: 80)
- `path` (string, required): Path to the directory (relative to workspace or absolute, e.g. '.', './src')

### `scoped_search` (~194 tokens)

Safe, token-bounded symbol/text search replacing raw grep/find (-90% tokens). '|' or \d in query auto-enables regex when use_regex is omitted; false forces literal.

Input parameters:

- `case_sensitive` (boolean): Case-sensitive search (default false)
- `max_results` (integer): Max matching lines (default 25, max 100)
- `path` (string): Directory to search (alias for project_path; relative or absolute)
- `project_path` (string): Optional root directory (defaults to current project)
- `query` (string, required): Text, identifier, or symbol name
- `scope` (string): Filter: 'code', 'config', 'all', extension ('go', '*.py'), or subfolder ('internal/promo') (default 'all')
- `use_regex` (boolean): Omit = auto-detect ('|', \d → regex); false = literal; true = regex

### `expand_ref` (~108 tokens)

Expands a previously folded or stashed tool, command, file, or MCP result by its 8-character hex hash anchor (e.g. 'a1b2c3d4' or '#a1b2c3d4'). Returns the full original text that TokenSafe folded.

Input parameters:

- `hash` (string, required): 8-character hex hash from the fold marker (e.g. 'a1b2c3d4' or '#a1b2c3d4')

### `read_web_page` (~60 tokens)

Fetches a web page URL and converts it to clean, readable Markdown, stripping scripts, styles, navbars, and ads (-80-95% tokens compared to raw HTML).

Input parameters:

- `url` (string, required): Web URL to fetch and convert to Markdown

### `optimize_image` (~98 tokens)

Downscales oversized screenshots/diagrams before passing them to LLM vision endpoints. Resizes images exceeding max_edge (default: 1024px) while preserving aspect ratio and crispness, keeping the original image intact on disk (-50-75% vision tokens).

Input parameters:

- `image_path` (string, required): Absolute or relative path to the image file
- `max_edge` (integer): Maximum width/height in pixels (default: 1024)

### `prune_superseded` (~60 tokens)

Prunes obsolete intermediate tool read outputs in long conversation transcripts that have since been modified by subsequent edits or re-read in later steps (-30-40% context mass).

Input parameters:

- `transcript_path` (string, required): Path to the JSONL conversation transcript to prune

### `get_mistakes` (~63 tokens)

Returns known dead-ends, failed hypotheses, and reverted code changes for this project to prevent repeating unsuccessful approaches.

Input parameters:

- `clear` (boolean): If true, clears the mistakes ledger
- `project_root` (string): Optional project root directory (defaults to current project)

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/dev-tokensafe-tokensafe/tokensafe-2#diagnostics

## Score history

- 2026-11-21: 57
- 2026-11-20: 72
- 2026-11-19: 56
- 2026-11-18: 56
- 2026-11-17: 55
- 2026-11-16: 55
- 2026-11-15: 54
- 2026-11-14: 54
- 2026-11-13: 54
- 2026-11-12: 53
- 2026-11-11: 53
- 2026-11-10: 40

## Common questions

### What is the TokenSafe MCP server?

TokenSafe is an MCP server listed in the public MCP registry as dev.tokensafe/tokensafe. Your AI agent is smart enough to code all day. Local firewall & zero-loss runtime. This page covers its PyPI package (tokensafe).

### Is the TokenSafe MCP server safe to use?

TokenSafe scores 57 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 21 November 2026. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the TokenSafe MCP server expose?

TokenSafe exposes 18 tools: smart_read_file, smart_bundle, get_architecture_graph, get_api_surface, compress_prompt, and 13 more. Their descriptions and schemas cost roughly 1,968 tokens of context every time the server is loaded.

### Is the TokenSafe MCP server still maintained?

TokenSafe is still listed as active in the MCP registry. We last reached this channel on 21 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the TokenSafe MCP server under?

TokenSafe declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

### What did VerifyMCP test on the TokenSafe MCP server?

VerifyMCP ran 15 checks on TokenSafe, covering Known CVEs, Install scripts, Dependency health, Source repository and 11 more. One item could not be completed, a gap on our side rather than a finding about TokenSafe: Malware scan. Endpoint Security and Transport & Reachability do not apply to a PyPI package, so they were not tested. The score does not measure everything, and the scoring documentation lists what it leaves out.

## Links

- PyPI project: https://pypi.org/project/tokensafe/
- Socket report: https://socket.dev/pypi/package/tokensafe
- Repository: https://github.com/tokensafe-dev/tokensafe
- Website: https://tokensafe.dev/
- Changelog RSS feed: https://verifymcp.io/servers/dev-tokensafe-tokensafe/tokensafe-2.xml
- Changelog JSON feed: https://verifymcp.io/servers/dev-tokensafe-tokensafe/tokensafe-2/changelog.json
- Trust report (JSON): https://verifymcp.io/servers/dev-tokensafe-tokensafe/tokensafe-2.json
- HTML version of this page: https://verifymcp.io/servers/dev-tokensafe-tokensafe/tokensafe-2
