MCP Directory

How to add Token Savior to Windsurf

Structural code navigation, persistent memory, and Bash output compaction for AI coding agents. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 993★ · stdio · no auth

Windsurf config for Token Savior

pip install "token-savior-recall[mcp]"
{
  "mcpServers": {
    "token-savior": {
      "command": "/path/to/venv/bin/token-savior",
      "args": [],
      "env": {
        "WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
        "TOKEN_SAVIOR_CLIENT": "claude-code",
        "TOKEN_SAVIOR_PROFILE": "optimized"
      }
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Token Savior config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Token Savior's tools become available to Cascade.

Before you start

  • Python 3.11+
  • An MCP-compatible client (e.g. Claude Code, Cursor, Gemini, Codex)
  • Install the token-savior-recall PyPI package (with the [mcp] extra), or run via uvx

What Token Savior can do in Windsurf

find_symbol

Locate a symbol (function, class, import) by name and navigate to it by pointer instead of reading the whole file — e.g. find_symbol("send_message") returns ~67 chars vs a full-file read.

get_function_source

Return the source of a named function directly, replacing a grep + cat chain.

get_change_impact

Report the change impact / call-graph dependents for a symbol (e.g. get_change_impact("LLMClient")).

get_edit_context

Provide the surrounding context needed to make a safe edit at a location.

memory_index

Index/store persistent memory observations (decisions, bugfixes, conventions, guardrails, session rollups) into the SQLite WAL + FTS5 + vector store.

memory_search

Search the persistent memory store, ranked by Bayesian validity and ROI, for relevant prior context.

capture_get

Retrieve the full original output that was sandboxed when hybrid compact mode emitted only a compact preview for a bulky Bash result.

get_usage_stats

Report token-usage statistics: a 30-day ASCII sparkline, a 7-day daily breakdown table, top tools cumulative, with optional format="json".

Security

Core navigation and memory require no credentials. Optional integrations use environment variables: TS_API_KEY (only for LLM auto-extraction of memory observations via TS_AUTO_EXTRACT=1) and TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID (critical-observation feed). Bash compaction (TS_BASH_COMPACT=1) and the PreToolUse command rewriter (TS_BASH_REWRITE=1) are opt-in; the rewriter supports an optional JSONL audit log of every rewrite via TS_BASH_REWRITE_LOG. The server reads local Claude Code transcripts under ~/.claude/projects for ts_discover and benchmarking; args are pruned to load-bearing keys (described as PII-safe).

Token Savior + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Token Savior config there under the "mcpServers" key and restart the client.

Is Token Savior safe to use with Windsurf?

Core navigation and memory require no credentials. Optional integrations use environment variables: TS_API_KEY (only for LLM auto-extraction of memory observations via TS_AUTO_EXTRACT=1) and TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID (critical-observation feed). Bash compaction (TS_BASH_COMPACT=1) and the PreToolUse command rewriter (TS_BASH_REWRITE=1) are opt-in; the rewriter supports an optional JSONL audit log of every rewrite via TS_BASH_REWRITE_LOG. The server reads local Claude Code transcripts under ~/.claude/projects for ts_discover and benchmarking; args are pruned to load-bearing keys (described as PII-safe).

Which profile should I use?

The README recommends `optimized` (set TOKEN_SAVIOR_PROFILE=optimized). It exposes 15 hot tools with a thin inputSchema (~1.5 KT manifest), disables capture sandboxing, and gates memory hooks for cross-project safety — the configuration it reports as the Pareto win on tsbench. Other profiles: auto (adaptive), tiny (6 tools), lean (51), full (68).

How do I enable Bash compaction and command rewriting?

They are opt-in. Set TS_BASH_COMPACT=1 (PostToolUse output compactors) and/or TS_BASH_REWRITE=1 (PreToolUse rewriter), then run `ts init --agent claude --yes` to auto-merge the hook config into ~/.claude/settings.json. `ts init` is idempotent, prints a unified diff, and backs up settings.json before writing.

Can I use it without MCP?

Yes. The `ts` CLI exposes a subset of tools via shell for non-MCP agents (Cursor, Aider, Continue, scripts, CI): e.g. `ts use <path>`, `ts get <symbol>`, `ts search <pattern>`, `ts daemon start`. On Claude Code the README recommends the MCP server, which it measured as cheaper than the CLI on Opus 4.7.

View repo Full Token Savior page