kitsune-mcp

Kitsune is a runtime MCP proxy. It discovers, connects to, and runs any of 130,000+ MCP servers live, mid-session — no config edit, no client restart (134,945 indexed on Glama alone as of May 2026). shapeshift(server_id) connects to a target server and makes its tools callable in the current turn; shapeshift() with no args disconnects and drops them again.

The core advantage is the runtime, not the token count. Adding a normal MCP server means editing your client config and restarting the session. Kitsune removes both steps: the model can reach — and execute — a server it has never seen, without you touching config or restarting. That is the durable win: access and execution on demand.

Two use cases where nothing else fits:

1. Developing your own MCP server, live. Edit a tool's code, shapeshift() back into it, and call it again in the same session — an edit → reload → test loop (an MCP REPL) instead of restarting your client on every change.

2. Shifting into an unknown MCP on demand. Hit a task that needs a server you've never set up? shapeshift() into it — discover, connect, run — then drop it. No config edit, no restart, no leaving the session to go install anything.

This is where the name earns itself: you shift into an unfamiliar server's shape, use its tools, and shift back.

What about native deferred loading? Since Claude Code v2.1.7 (Jan 2026), clients defer the tool schemas of configured servers until the model searches for them (Tool Search), so the old "keep tools out of context" benefit is now built into the client for servers you've already set up. Kitsune's edge is the servers you haven't set up — the long tail, one-offs, and anything you'd otherwise add-and-restart for. Standard servers you always keep on (Supabase, Google Drive, GitHub) are likely already configured and deferred natively; Kitsune isn't trying to replace those. It covers everything else, on demand.

Kitsune is not free at rest. It is itself an always-on MCP server: its six built-in tools cost ~1,358 tokens in every turn. Against a client with native deferral, that floor is additive — so don't install Kitsune to save tokens. Install it for reach: one config entry that puts the entire MCP ecosystem one call away, with no restart. The token math below still applies when you compare against servers kept fully mounted (always-on, or clients without native Tool Search).

What this actually solves

Native Tool Search already handles the token problem for servers in your config. These four problems it does not touch — they are what Kitsune is for:

The through-line: reach and execution, at runtime, without giving up your session — and a safety layer because "run any of 130,000 servers on demand" is only usable if running an unknown one is contained.

Why not just shell out to a CLI?

Shelling out to aws, gcloud, kubectl, or gh from a Bash tool also costs ~0 tokens at rest. So why MCP at all?

Because long-tail CLI commands fail. LLMs have great recall on the top ~20 commands of a CLI they've seen in training (git status, gh pr list, aws s3 cp) and steeply degraded recall on everything else. For an API surface the size of aws (~9,000 subcommands), first-call success drops to 30–50% on long-tail operations — wrong flag names, singular-vs-plural verbs, case-sensitive enums, and silently-deprecated options. Each miss costs a retry turn, and the worst failures aren't errors but plausible-looking wrong calls that succeed.

MCP gives you structured tool schemas the model can read and validate against:

That's the structural argument for the hub model: CLI-cheap at rest, MCP-accurate when it matters. For one-off ops on a CLI the model knows cold, gh is fine. For unfamiliar APIs, internal tooling, or any operation where a wrong call has real cost (production AWS changes, billing operations, security flows), Kitsune gives you schema-validated execution without the always-on tax. See examples/scenarios/ for seven worked use cases.

Token savings vs always-on (secondary benefit)

Honest note — this was the original idea, and Tool Search has largely overtaken it. Cutting always-on token overhead was Kitsune's founding motivation. But at roughly the same time it was being built, the client layer solved the same problem natively: since Claude Code v2.1.7 (Jan 2026), configured servers' tool schemas are deferred until the model searches for them (Tool Search). Against such a client the numbers and graph below no longer describe a unique win — Kitsune's ~1,358-token floor is even additive rather than a saving. Treat this section as historical / edge-case: it still holds for servers kept fully mounted always-on or for clients without native deferral, but it is not the reason to run Kitsune today. That reason is runtime reach and live development without a restart (above).

Kitsune carries a fixed ~1,358-token floor (measured: 6 lean-profile tools — run python examples/benchmark.py to reproduce). Every comparison below already includes that floor; it is never subtracted out or hidden. Savings come from the floor staying flat while always-on servers stack linearly:

Saving formula: 1 − (Kitsune base 1,358 + surgical mount) / always-on total

Break-even: if you only ever run one small server (e.g. mcp-server-time at ~261 tokens), always-on is cheaper than Kitsune — you'd pay 261 tokens instead of Kitsune's 1,358 floor. Kitsune wins when the always-on alternative exceeds ~1,358 tokens, which happens as soon as you'd keep one medium server (GitHub-sized) or two-plus small ones loaded. The bigger and more numerous your servers, the bigger the win.

This graph compares Kitsune against fully-mounted always-on servers. A client with native Tool Search already flattens most of this curve on its own, so read the chart as "what deferral buys you" — not as something unique to Kitsune.

Fewer tools in context also means more reliable answers. Research consistently shows LLM tool-selection degrades as the visible tool count grows — though on a modern client, native Tool Search delivers much of that focus too.

Related MCP server: mcp-proxy

Contents

• What this actually solves

• Why not just shell out to a CLI?

• Installation

• Quick start

• Developing an MCP server live

• How it works

• Tool reference

• Server sources

• GATEWAY: context bloat detection

• Performance

• Configuration

• Agent profiles

• Safety model

• For MCP developers

• Contributing

Installation

pip install kitsune-mcp      # recommended
# or
uvx kitsune-mcp              # isolated env via uv, no venv setup
# or
npx kitsune-mcp              # npm (delegates to uvx internally)

Requirements: Python 3.12+ · node/npx for npm-based servers · uvx from uv for PyPI-based servers

Add to your MCP client config — once, globally:

{
  "mcpServers": {
    "kitsune": { "command": "kitsune-mcp" }
  }
}

Compatible with Claude Desktop, Claude Code, Cursor, Cline, OpenClaw, Continue.dev, Zed, and any MCP-compatible client.

Quick start

# Find a server
search("web scraping")

# Mount specific tools, use them, release
shapeshift("notion-hosted", tools=["notion-search"])
call("notion-search", arguments={"query": "roadmap"})
shapeshift()                          # disconnect; context back to baseline

# One-shot via auto() — use server_hint for reliable routing
auto("current time in Tokyo", server_hint="mcp-server-time")

# Store a credential, then mount
auth("BRAVE_API_KEY", "sk-...")
shapeshift("brave", tools=["brave_web_search"])
call("brave_web_search", arguments={"query": "MCP protocol 2025"})
shapeshift()

Run a long-tail server from Glama or Smithery — none of it pre-installed:

search("pdf", registry="glama")        # search a specific registry
# Community sources (glama/npm/pypi) need one explicit confirm:
shapeshift("mcp-pdf-tools", confirm=True)     # spawns via npx/uvx, isolated subprocess
call("extract_text", arguments={"path": "report.pdf"})
shapeshift()                                  # process released

# Smithery-hosted (HTTP) — needs a free SMITHERY_API_KEY
search("exa", registry="smithery")
shapeshift("exa")                             # hosted, no local install
call("web_search_exa", arguments={"query": "MCP registry growth 2026"})
shapeshift()

See Developing an MCP server live for the edit → reload → test loop, and the full real-time demo script.

Developing an MCP server live

Building your own MCP server normally means a restart on every change: edit a tool, reboot the client so it re-reads the schema, re-establish your session, test, repeat. Kitsune turns that into an edit → reload → test loop in one session — an MCP REPL for your work-in-progress server.

The loop uses connect() (start a local command as a pooled process) and release() (kill it so the next connect() picks up your new code). These are dev tools, not in the default lean profile — enable them:

{
  "mcpServers": {
    "kitsune": {
      "command": "kitsune-mcp",
      "env": { "KITSUNE_TOOLS": "all" }
    }
  }
}

Then, without ever restarting your client:

# 1. Start your work-in-progress server
connect("uvx --from . my-mcp-server", name="dev")
#   → Connected: dev (PID 40213) | Tools (3): search, fetch, summarize

# 2. Call a tool, see it work (or fail)
call("summarize", arguments={"url": "https://example.com"})

# 3. Edit the tool's code in your editor …

# 4. Reload: drop the old process, start the new code
release("dev")
connect("uvx --from . my-mcp-server", name="dev")     # now running your edit

# 5. Re-test immediately
call("summarize", arguments={"url": "https://example.com"})

The footgun this removes: connect() pools processes, so calling it again after an edit without release() first hands you the old process running the old code. Kitsune detects this and tells you: "Changed the code? release('dev') first — this process predates your edit." Always release() before reconnecting.

Local connect() targets are treated as untrusted (confirm=True / KITSUNE_TRUST applies) and run as isolated subprocesses — but note that isolation is not a security sandbox; see Safety model. Full walkthrough: docs/demo-realtime.md.

How it works

Kitsune is a dynamic MCP proxy. shapeshift(server_id) connects to a target server via the appropriate transport (stdio subprocess, HTTP, WebSocket), fetches its tools/list, and registers each tool as a native FastMCP tool with the exact schema from the server. The AI client receives a notifications/tools/list_changed event and sees the new tools as first-class — no wrapper, no indirection.

shapeshift() with no args reverses all of it: deregisters the proxy closures, closes the connection, and notifies the client. Context returns to the ~1,358-token baseline.

Tool-schema RAG

Transport selection

Tool reference

Context overhead at rest: ~1,358 tokens for all 6 lean-profile tools (measured via examples/benchmark.py).

auto() note: auto(task, server_hint="server-id") gives reliable results. Without server_hint, routing is best-effort via semantic search and can misfire on ambiguous queries — use search() first when unsure.

Server sources

Kitsune searches 7 registries in parallel. No single registry is required.

search() fans out across all no-auth registries by default. Add a SMITHERY_API_KEY to include Smithery's hosted catalog (HTTP servers, no local install required).

GATEWAY: context bloat detection

status() scans your active MCP client configs and reports what other servers are running on every turn:

GATEWAY
  ⚠  1 other server(s) active in claude-desktop (~8 extra tools in context)
     Run setup() to harvest their credentials and reduce bloat
  ⚠  1 other server(s) active in claude-code (~8 extra tools in context)

To consolidate:

setup()                    # preview — shows what can be harvested
setup(action="harvest")    # extract API keys → ~/.kitsune/.env  (non-destructive)
setup(action="absorb")     # register those servers for shapeshift()
setup(project=True)        # write .claude/mcp.json with only Kitsune (this project)

Kitsune never modifies existing configs without explicit confirmation.

Performance

Token overhead: surgical mount vs full mount

The same caveat as above applies to this whole section: these savings are real only versus fully-mounted always-on servers. On a client with native Tool Search (Claude Code 2.1.7+), configured servers are already deferred, so most of these numbers no longer represent a Kitsune-specific advantage. Kept here for transparency and for clients/servers without native deferral.

Full-mount figures measured live via shapeshift() probes. Surgical estimates (~) are proportional approximations based on tool count, not individually measured. Every Kitsune figure includes the fixed ~1,358-token floor — it is never omitted. To measure Kitsune's own profile size: python examples/benchmark.py.

Saved = 1 − (1,358 floor + surgical) / always-on. A negative result means always-on is cheaper for that single server.

¹ For a single server smaller than Kitsune's ~1,358-token floor (time, git), running it always-on is cheaper than Kitsune. Kitsune only pays off once the always-on alternative exceeds the floor — i.e. one medium server, or two-plus small ones sharing the single baseline.

Multi-server compounding

Kitsune's resting cost (~1,358 tokens) is constant regardless of how many servers are registered. Always-on cost grows linearly with each server added — that linear stack is where Kitsune wins.

All figures include the 1,358 floor + surgical mount for whichever server is active. The range reflects the cheapest (git ~310) to most expensive (Notion ~1,950) surgical call.

Tool-selection reliability

LLM tool-selection degrades as the visible tool count grows — a finding consistent across multiple tool-use benchmarks (Gorilla, ToolBench). The failure mode is typically adjacent-name confusion: a model that sees read_file, read_text_file, and read_media_file simultaneously is more likely to call the wrong one than a model that sees only the one it needs.

Kitsune holds 6 tools at rest; 7–9 during active use. A Kitsune-specific benchmark measuring selection accuracy across tool-count conditions does not yet exist — contributions welcome.

Connection latency

Kitsune maintains a persistent process pool — re-attaching to a running server within a session takes 0 ms.

Configuration

Env vars and .env files

Kitsune re-reads credentials on every shapeshift() and call(). Add or update a key mid-session — no restart needed.

Search order: CWD/.env → ~/.env → ~/.kitsune/.env (last wins).

# Write a key and activate immediately
auth("BRAVE_API_KEY", "sk-...")    # writes to ~/.kitsune/.env

# Or manage .env directly
echo "BRAVE_API_KEY=sk-..." >> ~/.kitsune/.env

Custom tool surface

Expose only specific tools via KITSUNE_TOOLS:

{
  "mcpServers": {
    "kitsune": {
      "command": "kitsune-mcp",
      "env": { "KITSUNE_TOOLS": "shapeshift,call,auth" }
    }
  }
}

Custom state directory

All persistent state — credentials (.env), absorbed servers, OAuth tokens, session state, skills — lives under ~/.kitsune/ by default. Set KITSUNE_HOME to relocate the whole directory, e.g. for benchmarks, CI, or multi-tenant isolation:

KITSUNE_HOME=/tmp/kitsune-iso kitsune-mcp

Everything Kitsune writes then stays under /tmp/kitsune-iso/ — nothing touches ~/.kitsune/.

Smithery

{ "env": { "SMITHERY_API_KEY": "your-key" } }

Get a free key at smithery.ai/account/api-keys. Without it, Kitsune is fully functional via npm, PyPI, official registry, and GitHub.

Agent profiles

Research agent — web search + fetch + memory

shapeshift("brave", tools=["brave_web_search"])                              # ~450 tokens
shapeshift("mcp-server-fetch")                                               # ~289 tokens
shapeshift("@modelcontextprotocol/server-memory",
           tools=["read_graph", "search_nodes"])                             # ~580 tokens
# Mounts: ~1,300 tokens; total with ~1,358 floor: ~2,650 vs 6,516 always-on  →  59% reduction

Code agent — filesystem + git

shapeshift("@modelcontextprotocol/server-filesystem",
           tools=["read_file", "write_file", "edit_file"],
           server_args=["/path/to/project"])                                 # ~690 tokens
shapeshift("mcp-server-git",
           tools=["git_status", "git_diff", "git_log"])                     # ~310 tokens
# Mounts: ~1,000 tokens; total with ~1,358 floor: ~2,350 vs 4,449 always-on  →  47% reduction

Notes / PM agent — Notion + memory

shapeshift("notion-hosted",
           tools=["notion-search", "notion-append-block-children"])         # ~1,950 tokens
shapeshift("@modelcontextprotocol/server-memory",
           tools=["add_memory", "search_nodes"])                            # ~580 tokens
# Mounts: ~2,500 tokens; total with ~1,358 floor: ~3,850 vs 16,322 always-on  →  76% reduction

Safety model

Kitsune executes third-party code — npm, PyPI, GitHub, and local packages — with your permissions. That makes it a supply-chain execution surface, not just a router. Be clear-eyed about what it contains and what it does not.

What it protects against

1. Unverified code running without consent.

Community and local sources refuse to run until you pass confirm=True on shapeshift()/connect(). KITSUNE_TRUST=community waives the gate for sources you already trust; status() warns when that override is active.

Caveat — confirm=True is not a human-approval boundary. It is a tool argument the model can set on its own. It's a consent signal and defence-in-depth; the real user-facing approval must come from your host client's tool-approval UI (per the MCP spec's guidance that apps provide real confirmation). Don't rely on confirm alone to keep an autonomous agent from executing a server.

2. Shell injection at spawn time. Install commands are validated against shell-metacharacter (& ; | $ \ \n) and path-traversal (../) patterns and are launched via create_subprocess_exec— no shell is involved. A maliciousserver_id` can't inject a shell command. This vets the launch command, not what the package does once it runs.

3. SSRF. fetch() and every registry call are HTTPS-only; private, loopback, and non-global hosts are blocked, and every redirect hop is re-validated (opt out only with KITSUNE_ALLOW_LOCAL_FETCH=1).

4. Credential exposure. ~/.kitsune/.env and ~/.kitsune/oauth/ are written at mode 0600; OAuth 2.1 with PKCE S256 and Dynamic Client Registration (RFC 7591); missing-credential warnings before any call; auth("server-id", "logout") clears cached tokens.

5. Untrusted local servers — opt-in Docker sandbox. shapeshift("pkg", sandbox=True) runs an npm/PyPI server inside the hardened Docker profile instead of as a host subprocess: no host filesystem, --cap-drop ALL, read-only rootfs, RAM/PID caps. Only credential env vars relevant to that server are forwarded — by name (docker -e KEY), never by value, so secrets stay out of the argv, the process list, and the pool key. Set KITSUNE_SANDBOX=community to sandbox every community-source mount automatically, or KITSUNE_SANDBOX=all for every local mount. Requires Docker; the first sandboxed mount pulls the base image (node:22-slim / uv:python3.13-bookworm-slim). Filesystem-style servers need host paths and are the one category that doesn't fit a sandbox.

What it does NOT do — read before trusting it with real credentials

• A local stdio server is isolated from Kitsune's memory, but it is not sandboxed unless you opt in. Without sandbox=True / KITSUNE_SANDBOX, it runs as your user and inherits your permissions: it can read and write your files, reach the network, spawn processes, and read inherited environment variables. Process isolation is not a security boundary.

• Docker mode is hardened, but Docker is still not a kernel boundary. Every container runs --cap-drop ALL --security-opt no-new-privileges --read-only --tmpfs /tmp --pids-limit 512 --memory 512m by default (opt out per call: writable, cap_add, network, pids_limit, memory). That blunts privilege escalation, fork bombs, and filesystem tampering — but it is defence-in-depth, not a guarantee against a container-escape kernel exploit. It also does not yet default to a non-root user or --network none (most MCP servers need egress).

• Version pinning is trust-on-first-use (TOFU), not a digest lock. When Kitsune first mounts an npm/PyPI server it records the exact resolved version in ~/.kitsune/pins.json and reuses it on every later mount — so a package that publishes a malicious release after you trusted it can't silently execute; you get a ⚠️ pinned to 1.2.3, registry now offers 1.3.0 warning instead. KITSUNE_REPIN=1 adopts the newer version and updates the pin. Limits: it pins a version, not a content digest; and github:/--from git+… targets and hand-written connect() commands carry no version, so they aren't pinned. For high-assurance use, pin by digest or vendor the package.

• Not every MCP capability is proxied identically. Native tools are first-class; resource/prompt proxying is narrower (URI templates are skipped; HTTP transports don't proxy resources/prompts through the same path). "Any server" refers to tool execution, not every MCP capability.

Bottom line: strong fit for supervised developer and personal workflows. Do not run it unattended with production admin, billing, or security credentials in the default local-execution mode — a local (non-Docker) server still runs with your full user permissions. For higher assurance: enforce approval at the client, restrict credentials and filesystem access, and run untrusted servers sandboxed — shapeshift(id, sandbox=True) or KITSUNE_SANDBOX=community — rather than as raw local npx/uvx processes.

See these guards in action in docs/demo-realtime.md.

For MCP developers

The full evaluation suite is available by setting KITSUNE_TOOLS=all:

{ "command": "kitsune-mcp", "env": { "KITSUNE_TOOLS": "all" } }

Additional tools:

Test your server inside real Claude or Cursor sessions — not in an isolated inspector UI.

Why Kitsune?

In Japanese folklore, the Kitsune (狐) is a fox spirit of extraordinary intelligence and magical power. What makes it remarkable is not what it is, but what it can become. With age and wisdom, a Kitsune grows new tails — each one a new ability mastered, a new form borrowed from the world around it. It can shapeshift into anything: a scholar, a warrior, a force of nature. And when the purpose is fulfilled, it casts off that form as easily as it took it on, returning to its true self — ready to become something else entirely.

One fox. Infinite forms. Every power available. Nothing carried that isn't needed.

shapeshift("brave-search") — the fox takes on a new form. Its tools appear as if they were always there. shapeshift() — it returns to its true shape. Context drops back to baseline. Ready for the next form.

Each server mounted is a new tail. Each capability borrowed cleanly and released when done. One entry in your config. Every server in the MCP ecosystem, on demand — summoned, used, and let go.

Concretely, shapeshift() connects to a server at runtime and makes its tools callable — you shift into an unfamiliar server's shape, use it, and shift back. It's an on-demand connect-and-execute, not a transformation of Kitsune itself. The value is that it happens live, mid-session, without editing config or restarting the client.

I am not Japanese, and I use this name with the highest respect for the mythology and culture it comes from. The parallel felt too precise to ignore — a spirit that shapeshifts between forms, gains new powers, and releases them at will. That is exactly what this tool does.

Contributing

make dev     # install with dev dependencies
make test    # pytest
make lint    # ruff

Issues and PRs: github.com/kaiser-data/kitsune-mcp

See CHANGELOG.md for version history.

MIT License · Python 3.12+ · Built on FastMCP