kitsune-mcp

Kitsune is a runtime MCP proxy: one always-on gateway your agent uses to reach the rest of the ecosystem. `search` finds a server across 7 registries. `shapeshift(id)` mounts its tools in the current turn. `shapeshift()` drops them. No config edit. No client restart.

search → shapeshift → call → shapeshift()       # reach, use, release
connect → shapeshift → edit → reload → call     # MCP REPL (default install)

Install for reach and live execution — not for token savings. Native Tool Search already defers schemas for servers you've configured. Kitsune covers what Tool Search cannot: servers you've never set up, servers you're writing right now, and community packages you want to try without wiring them into `mcp.json` forever.

Worked high-stakes flows (IAM, IR, audits): `examples/scenarios/`. CLI vs MCP accuracy argument lives there too — short version: models nail common CLI commands and fail on the long tail; Kitsune mounts schemas only while you need them.

Contents

• Installation
• Quick start
• Developing an MCP server live
• How it works
• Tool reference
• Server sources
• Safety model
• GATEWAY: consolidate always-on servers
• Performance
• Configuration
• Mount patterns
• For MCP developers
• Why Kitsune?
• 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 · Docker optional (sandbox)

Add once to your MCP client config:

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

Also works with OpenClaw, Zed, and any MCP-compatible client.

Lean profile at rest: 9 tools · ~1,774 tokens/turn (`status`, `search`, `auth`, `shapeshift`, `call`, `auto`, plus the `connect` / `release` / `reload` REPL trio) — measured via `python examples/benchmark.py`.

Quick start

Borrow a server you never configured:

search("web scraping")
shapeshift("firecrawl", tools=["scrape_url"])   # surgical: one tool, not the whole surface
call("scrape_url", arguments={"url": "https://example.com"})
shapeshift()                                    # drop form — session stays up

Community / long-tail (confirm; caged by default):

search("pdf", registry="glama")
shapeshift("mcp-pdf-tools", confirm=True)  # npm/PyPI caged in Docker by default (when available)
call("extract_text", arguments={"path": "report.pdf"})
shapeshift("mcp-pdf-tools", confirm=True, sandbox=False)  # opt out of the cage
shapeshift()

Hosted (Smithery HTTP — needs a free `SMITHERY_API_KEY`):

search("exa", registry="smithery")
shapeshift("exa")
call("web_search_exa", arguments={"query": "MCP registry growth 2026"})
shapeshift()

Credentials mid-session:

auth("BRAVE_API_KEY", "sk-...")
shapeshift("brave", tools=["brave_web_search"])
call("brave_web_search", arguments={"query": "MCP protocol 2026"})
shapeshift()

One-shot — pass `server_hint` when you know the id (`auto` without it is best-effort and can misfire):

auto("current time in Tokyo", server_hint="mcp-server-time")

Full live walkthrough: `docs/demo-realtime.md`.

Developing an MCP server live

Building an MCP normally means: edit → restart client → lose session → re-test. Kitsune turns that into an MCP REPL in one session — and `connect` / `release` / `reload` are in the default lean profile, so this works on a plain `pip install` with no `KITSUNE_TOOLS=all`.

connect("uvx --from . my-mcp-server", name="dev")       # start child process
shapeshift("dev")                                       # mount tools → client sees them
call("summarize", arguments={"url": "https://example.com"})

# … edit the tool in your editor …

reload("dev")                                           # release → restart fresh code → remount, one call
call("summarize", arguments={"url": "https://example.com"})

`reload("dev")` folds the whole cycle — kill the stale process, start your edited code, remount so the client sees the new schemas — into a single call. It also removes the classic footgun: calling `connect()` again after an edit *without* releasing first hands you back the old process; `reload` always releases first.

Local `connect()` targets are untrusted (`confirm` / `KITSUNE_TRUST` apply). Process isolation ≠ security sandbox — see Safety model. Companion skill: `kitsune-dev`.

How it works

`shapeshift(server_id)` picks a transport (stdio / HTTP+SSE / WebSocket / Docker), connects, fetches `tools/list`, and registers each tool as a native FastMCP tool with the server's real schema. The client gets `notifications/tools/list_changed` and sees first-class tools — no wrapper indirection.

`shapeshift()` with no args deregisters proxies, closes the connection, and returns to the lean baseline.

Mental model — tool-schema RAG: index the ecosystem → `search` retrieves candidates → `shapeshift(..., tools=[…])` injects only what's needed → agent calls natively → `shapeshift()` evicts.

Tool reference

Lean (default)

Forge (`KITSUNE_TOOLS=all` or `kitsune-forge`): `connect`, `release`, `prewarm`, `inspect`, `test`, `bench`, `compare`, `craft`, `run`, `fetch`, `setup`, `skill`, `shiftback`, … — see For MCP developers.

Server sources

`search()` fans out across no-auth registries by default. Add `SMITHERY_API_KEY` for hosted HTTP servers (no local install).

Safety model

Reach into 130k community servers only works if unknown code can be contained. Consent, sandbox, and pins are product features — not footnotes.

Headline controls

• `confirm=True` (or `KITSUNE_TRUST`) before community / local mounts
• Community npm/PyPI mounts cage in hardened Docker by default (when Docker is present); `sandbox=False` or `KITSUNE_SANDBOX=off` opts out, `sandbox=True` forces it, `KITSUNE_SANDBOX=all` cages every local mount
• TOFU pins in `~/.kitsune/pins.json` — later malicious publishes don't silently replace what you already ran

What it protects against

1. Unverified code without consent

`KITSUNE_TRUST=community` waives the gate; `status()` warns when that override is active.

> `confirm=True` is not a human-approval boundary. The model can set it. Real approval belongs in your client's tool-approval UI.

2. Shell injection at spawn. Install commands are validated (no `& ; | $ \` `\n` / `../`) and launched with `create_subprocess_exec` — no shell. Vets the launch line, not what the package does once running.

3. SSRF. `fetch()` and registry HTTP are HTTPS-only; private/loopback/non-global hosts blocked; every redirect hop re-validated (`KITSUNE_ALLOW_LOCAL_FETCH=1` to opt out).

4. Credential exposure. `~/.kitsune/.env` and `oauth/` at mode `0600`; OAuth 2.1 + PKCE S256 + DCR (RFC 7591); missing-cred warnings before calls; `auth(id, "logout")` clears tokens (RFC 7009 where available).

5. Docker sandbox for untrusted local servers — on by default. Community `npm`/`pypi`/`github` mounts (and the `auto()`/`call()`/`run()` exec paths) cage automatically when Docker is on `PATH`; no host FS, `--cap-drop ALL`, read-only rootfs, RAM/PID caps. Cred env vars forwarded by name only (`docker -e KEY`) — never in argv, `ps`, or the pool key. First sandboxed mount pulls `node:22-slim` / `uv:python3.13-bookworm-slim`. Best-effort: no Docker → runs uncaged with a nudge (an explicit `sandbox=True` hard-fails instead). Opt out per-call with `sandbox=False` or session-wide with `KITSUNE_SANDBOX=off`. Filesystem-style servers need host paths and don't fit the sandbox.

What it does NOT do

• Cage needs Docker + opt-in-trusted sources. Community mounts cage by default *only when Docker is present*; without it (or with `sandbox=False`/`KITSUNE_SANDBOX=off`, or for medium/high-trust sources) local stdio runs as your user — full FS, network, inherited env. Process isolation ≠ a security boundary.
• Docker ≠ kernel boundary. Hardened flags blunt escalation / fork bombs / FS tampering; not a guarantee against container escape. No default non-root / `--network none` (most servers need egress).
• TOFU ≠ digest pin. Pins a version, not a content hash. `github:` / `git+` / hand-written `connect()` commands aren't pinned. High assurance: pin by digest or vendor.
• Tools first. Resource/prompt proxying is narrower (URI templates skipped; HTTP path differs). "Any server" means tool execution.

Bottom line: strong for supervised developer and personal use. Do not run unattended with production admin, billing, or security credentials in default local mode. Keep Docker installed so the default cage engages, and prefer client approval for untrusted packages.

See guards live: `docs/demo-realtime.md`.

GATEWAY: consolidate always-on servers

Optional. Keep daily drivers (GitHub, filesystem, …) native if you prefer. When a config is crowded, `status()` flags other always-on servers so you can collapse to one Kitsune entry and reach them via `shapeshift`:

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

setup()                    # preview
setup(action="harvest")    # keys → ~/.kitsune/.env (non-destructive)
setup(action="absorb")     # register for shapeshift()
setup(project=True)        # project mcp.json with only Kitsune

Never modifies existing configs without explicit confirmation. (`setup` is forge-profile.)

Performance

Connection latency (what you feel)

Warm pool re-attach within a session: 0 ms.

Use `prewarm` (forge) when you know you'll need a server soon.

Token overhead (secondary)

> Real vs fully-mounted always-on or clients without Tool Search. On Claude Code 2.1.7+ with native deferral, this is mostly not a Kitsune-specific win. Product pitch is reach + REPL above — not this table.

Every Kitsune figure includes the ~1,774 floor. Reproduce: `python examples/benchmark.py`. Methodology: `docs/benchmarks.md`.

¹ Break-even: Kitsune pays off past one medium server, or two-plus small ones sharing the single floor. Multi-server stack (GitHub+fs+git → Notion suite): ~72–85% vs fully-mounted always-on — same caveat as above.

Fewer visible tools also helps selection reliability (Gorilla / ToolBench); on modern clients Tool Search delivers much of that focus for *configured* servers. Kitsune-specific accuracy bench: not yet — contributions welcome.

Configuration

Env and `.env`

Re-read on every `shapeshift` / `call` — add keys mid-session, no restart.

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

auth("BRAVE_API_KEY", "sk-...")    # → ~/.kitsune/.env

Tool surface

{ "env": { "KITSUNE_TOOLS": "shapeshift,call,auth" } }   # subset
{ "env": { "KITSUNE_TOOLS": "all" } }                    # forge

State directory

Default `~/.kitsune/` (credentials, pins, OAuth, session). Relocate with `KITSUNE_HOME=/tmp/kitsune-iso`.

Sandbox / trust policy

KITSUNE_SANDBOX=community   # Docker-cage community npm/PyPI mounts
KITSUNE_SANDBOX=all         # cage every local mount
KITSUNE_TRUST=community     # waive confirm gate (status warns)
KITSUNE_REPIN=1             # adopt newer pinned version

Smithery

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

Free key: smithery.ai/account/api-keys. Without it, npm / PyPI / official / GitHub still work.

Mount patterns

Switch forms mid-session — take only the slice you need:

# Research
shapeshift("brave", tools=["brave_web_search"])
shapeshift("mcp-server-fetch")
shapeshift("@modelcontextprotocol/server-memory", tools=["read_graph", "search_nodes"])

# Code
shapeshift("@modelcontextprotocol/server-filesystem",
           tools=["read_file", "write_file", "edit_file"],
           server_args=["/path/to/project"])
shapeshift("mcp-server-git", tools=["git_status", "git_diff", "git_log"])

# Notes
shapeshift("notion-hosted", tools=["notion-search", "notion-append-block-children"])
shapeshift("@modelcontextprotocol/server-memory", tools=["add_memory", "search_nodes"])

shapeshift()   # always drop when the task is done

For MCP developers

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

Test inside real Claude / Cursor sessions — not only an inspector UI. Companion skills: `kitsune-dev`, `kitsune-improve`.

Why Kitsune?

In Japanese folklore the Kitsune (狐) is known for what it can *become*: borrow a form, use that power, cast it off, return to itself.

That is the product loop — reach, use, release; or edit, reload, re-test. One config entry. Long tail one call away. Session intact.

`shapeshift()` is a literal mid-session mount, not a metaphor. Durable advantages: reach, live development, contained try-before-trust — not a smaller token bill on clients that already defer schemas.

> *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.*

Contributing

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

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

*MIT License · Python 3.12+ · Built on FastMCP*