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

Related MCP server: mcp-proxy

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