io.github.kaiser-data/kitsune-mcp

Kitsune is a gateway MCP server that discovers, installs, and dynamically loads any of 130,000+ MCP servers at runtime (134,945 indexed on Glama alone as of May 2026). Instead of keeping every server's tools in context permanently, Kitsune mounts tools on demand via shapeshift() and releases them when done. Thousands available on request. No restarts.

Kitsune is not free at rest. It is itself an always-on MCP server: its six built-in tools cost ~1,321 tokens in every turn, whether you use them or not. That is its fixed floor — it never drops to zero. The win is that this floor stays flat no matter how many servers sit behind it, whereas always-on servers stack linearly. So Kitsune only pays for itself once you'd otherwise be loading more than one non-trivial server (see the break-even note below).

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

Kitsune carries a fixed ~1,321-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,321 + 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,321 floor. Kitsune wins when the always-on alternative exceeds ~1,321 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.

Fewer tools in context also means more reliable answers. Research consistently shows LLM tool-selection degrades as the visible tool count grows — Kitsune keeps the model focused on exactly what the current task needs.

Contents

• Why not just shell out to a CLI?
• Installation
• Quick start
• How it works
• Tool reference
• Server sources
• GATEWAY: context bloat detection
• Performance
• Configuration
• Agent profiles
• Security
• 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()                          # context returns to ~1,321 tokens

# 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()

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,321-token baseline.

Tool-schema RAG

Transport selection

Tool reference

Context overhead at rest: ~1,321 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

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,321-token floor — it is never omitted. To measure Kitsune's own profile size: python examples/benchmark.py.

Saved = 1 − (1,321 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,321-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,321 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,321 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" }
    }
  }
}

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,321 floor: ~2,600 vs 6,516 always-on  →  60% 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,321 floor: ~2,300 vs 4,449 always-on  →  48% 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,321 floor: ~3,850 vs 16,322 always-on  →  76% reduction

Security

Trust tiers

Community servers require confirm=True on shapeshift() — an explicit acknowledgement before running arbitrary code. Set KITSUNE_TRUST=community (via auth("KITSUNE_TRUST", "community") or .env) to skip the gate globally for servers you already trust.

Credential handling

• Credentials stored at ~/.kitsune/.env and ~/.kitsune/oauth/ with mode 0600
• OAuth 2.1 with PKCE S256 and Dynamic Client Registration (RFC 7591) for hosted servers
• shapeshift() warns on missing credentials before any tool call
• auth("server-id", "logout") clears cached OAuth tokens

Process isolation

• stdio servers run as isolated OS subprocesses — no shared memory with Kitsune
• Docker servers run with --rm -i --memory 512m
• fetch() blocks private IPs, loopback, and non-HTTPS URLs
• Process pool capped at 10 concurrent servers; idle processes evicted after 1 hour
• Install commands validated against shell metacharacter and path-traversal patterns before execution

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.

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